ClioSoft SOS Administration Guide
Software Version 7
October, 2015 Revision G Legal Notices Copyright © 2014 ClioSoft, Inc. All rights reserved. Published in the USA. The information in this publication is provided as is. ClioSoft makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. The use, copying, or distribution of any ClioSoft or third-party software described in this publication requires an applicable software license. ClioSoft and the ClioSoft logo are trademarks of ClioSoft Inc. All other trademarks used in this document are the property of their respective owners.
North American Headquarters ClioSoft, Inc. 39500 Stevenson Place, Suite 110 Fremont, CA 94539 USA Tel: (U. S.) +1 510-790-4732 E-mail: [email protected] Support: [email protected]
2 CHAPTER 0TABLE OF CONTENTS
1 Overview of SOS Administration ...... 7 How Hardware Configuration Management Works ...... 8 Documentation and Support ...... 9
2 Software Installation and Licensing ...... 10 System Requirements ...... 10 Downloading and Installing the Software ...... 12 Downloading ...... 12 Installing the Software on Linux ...... 12 Post-Installation Steps for Linux (Full Installation) ...... 14 Installation Considerations for Multiple Linux Versions...... 15 Post-Installation Steps for the Standalone VDD Utility ...... 16 Installing the Software on Windows ...... 17 Upgrading to a New Release of SOS ...... 20 Upgrading Linux Installations with SOS Minor Revisions ...... 20 Upgrading Linux Installations from SOS 6 to SOS 7 ...... 21 Upgrading Windows Installations ...... 23 Licensing ...... 23 License Options ...... 24 Obtaining License Keys from ClioSoft ...... 24 About the ClioSoft License File...... 25 Specifying a Port Number ...... 27 Setting Up Named User Licensing ...... 28 Setting the License Server Environment Variable ...... 29 Configuring Licensing for Linux...... 29 Configuring Licensing for Windows...... 30 Verifying the Installation ...... 32 Integrating SOS with Your CAD System ...... 33 Integration with Keysight ADS ...... 33 Integration with Cadence Virtuoso ...... 33 Integration with Mentor Pyxis ...... 35 Integration with Synopsys Custom Designer ...... 36 Integration with Synopsys Laker ...... 37 Installing and Configuring the SOS Web Client ...... 37
3 Setting Up SOS Servers and Projects ...... 38 About SOS Servers, Clients, Projects, and Work Areas ...... 39 Maximizing Performance ...... 40 Planning for Multiple Projects and Sites ...... 41 Organizing Project Data on File Servers...... 41 Data Security ...... 42
3 Using the SOSAdmin Application ...... 43 Setting Up Primary and Cache Servers ...... 44 Configuring a Primary Server and its Local Cache Server ...... 44 Setting Up a Remote Cache Server ...... 48 Accessing Linux Servers from Windows Clients...... 49 Starting the SOS Servers Automatically ...... 49 Configuring SSL ...... 50 Configuring Client Authentication ...... 50 Creating Projects ...... 52 Defining a New Project ...... 52 Adding Files to a Project ...... 54
4 Server and Project Administration ...... 60 Creating and Restoring Backups and Archives ...... 60 Archiving a Project ...... 60 Restoring an Archive...... 61 Managing Projects and Servers ...... 62 Shutting Down and Restarting Servers...... 62 Restarting and Messaging the Clients ...... 63 Locking and Unlocking Projects ...... 64 Moving Projects ...... 65 Deleting Projects and Servers ...... 65 Reducing Disk Space Usage ...... 65 Using Shared Work Areas ...... 66 Setting Up Shared Work Areas...... 66 Limitations of Shared Work Areas ...... 67 SOSAdmin Command Line Quick Reference ...... 67
5 Configuring Projects with sosd.cfg ...... 69 Overview of the Server Configuration File ...... 70 Selecting the Server Configuration File to Read...... 70 Working With Configuration Files ...... 70 Configuration File Locations ...... 70 Configuration File Format ...... 71 Configuration File Templates ...... 72 Customizing Configuration Files with SOSAdmin ...... 72 Setting Project Access Controls ...... 74 Host-Based Access Control in SOSAdmin ...... 75 Configuration File Example for Access Control ...... 76 Global and Default Access Controls ...... 77 Access Control Best Practices for Virtuoso Data ...... 78 Roles...... 78 Groups ...... 80 Managing umask and Linux Permissions ...... 83 Setting the Default Revision Search Order, Populate, Branch, and Work Area UMASK Options ...... 83
4 Revision Search Order ...... 83 Directories to Populate ...... 84 Branch Options for Files and Directories ...... 84 UMASK Settings for Work Areas ...... 85 Defining Reference Projects ...... 85 Setting Up Projects for Referencing ...... 85 Adding References ...... 86 Specifying the RSO for a Reference...... 88 Syntax of the REFERENCE_PROJECT Block ...... 88 Integrating SOS Projects with Change Request Tracking Systems ...... 90 Supported Tracking Systems ...... 90
6 Customizing the SOS Client and the User Interface ...... 91 About the sos.cfg File ...... 92 About Attributes and Triggers ...... 92 Defining and Using Attributes ...... 93 Declaring Attributes...... 93 Monitoring Status and Progress with Attributes and Triggers...... 97 Predefined Attributes ...... 97 Using Triggers ...... 99 Assigning Triggers to Files or Directories ...... 99 Default Triggers ...... 100 Defining a Trigger ...... 101 Script Languages and Locations...... 103 Commands that Accept Actions ...... 104 Using Environment Variables in Actions ...... 105 Trigger-Based Access Controls ...... 107 SKILL Triggers ...... 107 Example: Setting the Trigger Attribute When Creating a File ...... 108 Example: Setting the Group Attribute when Creating a File ...... 109 Example: Overriding Attribute Properties in a Trigger ...... 109 Example: Trigger for Running a Verilog Lint Check ...... 110 Example: Script for Notification of Command Results ...... 111 Specifying Exclude, Cleanup, and Local Copy Files ...... 111 Setting the Exclude Files List ...... 112 Setting the Cleanup Files List ...... 112 Setting the Local Copy Files List...... 113 Setting UDMA Rules for Automatic Cellview Packaging ...... 113 UDMA Rule Syntax...... 114 Example UDMA Rule ...... 115 Using X Resources ...... 116 Priority of X Resources ...... 116 Working With X Resource Files ...... 117 Changing Colors and Fonts ...... 118 Displaying Attributes ...... 118 Adding Buttons ...... 119
5 Specifying SOS Tcl Commands in .sosrc ...... 123 Default Settings in .sosrc ...... 123 Priority of .sosrc Files ...... 124
6 CHAPTER 1OVERVIEW OF SOS ADMINISTRATION
This manual explains how to install, configure, and manage the ClioSoft SOS hardware configuration management software. This manual is for CAD managers and project leads who have an administrative role in SOS design projects. This chapter covers the following topics: • How Hardware Configuration Management Works • Documentation and Support
Overview of SOS Administration 7 SOS Administration Guide How Hardware Configuration Management Works
In traditional EDA design methodology, it is very easy for one designer to accidentally overwrite another designer’s changes with changes from their personal “scratch” libraries. It is also difficult to be sure that you are working with the correct version of every cellview and file, especially when you need to run simulation or verification from a high level of the design hierarchy. Hardware configuration management helps design teams avoid these problems by automating and simplifying how you manage all of the files that make up a design. The key features of hardware configuration management are: • Design Management: each designer works in an isolated work area that contains a linked or physical copy of the project libraries. The SOS software prevents accidental or simultaneous changes to project libraries. • Version Control: every time you check in a cellview or file, you create a new revision in the library. You can revert back to older revisions at any time. • Change Tracking: SOS automatically maintains a change history for every cellview and file. You can visualize the change history for any object with Visual Design Diff. • Access Control: CAD managers determine who can make changes to “golden” versions of cellviews, or to specific libraries and cellviews. For example, layout engineers might not be allowed to modify schematic cellviews. • Release Management: you can save snapshots of a design that record the version of every cellview and file in every library. You can recreate these snapshots – a “golden” version, a tapeout, or a successful design experiment – at any time in the future. SOS stores your design data in a PostgreSQL relational database.
Overview of SOS Administration 8 SOS Administration Guide Documentation and Support
To view the online documentation in your web browser: • Choose Help > Documentation from the SOS window. •Use the sos_docs command. To view the documentation in PDF format, look in this directory: $CLIOSOFT_DIR/docs For information about SOS command-line options, use these commands: % soscmd help % sosadmin help To view online training videos and download application notes, visit www.cliosoft.com/support. For troubleshooting information, select Troubleshooting under FAQs.
Overview of SOS Administration 9 CHAPTER 2SOFTWARE INSTALLATION AND LICENSING
This chapter explains how to install the ClioSoft SOS software and set up licensing in the following sections: • System Requirements • Downloading and Installing the Software • Upgrading to a New Release of SOS • Licensing • Verifying the Installation • Integrating SOS with Your CAD System • Installing and Configuring the SOS Web Client
System Requirements
The SOS software is supported on the following platforms and operating system versions: Table 1 Supported Platforms Platform Supported OS Versions Red Hat Enterprise Linux 4.0 and later Microsoft Windows XP and later
Software Installation and Licensing 10 SOS Administration Guide
The next table lists the hardware requirements for SOS servers. Table 2 Server Hardware Requirements Resource Requirements and Recommendations CPU x86 multi-core processor at 3GHz or faster. Because the primary and cache servers are multi-threaded, ClioSoft recommends that you use a multi-CPU server for optimal performance if you plan to run multiple SOS server and cache daemons on the same machine. Memory Minimum of 16 GB. The SOS primary and cache servers are supported by their own PostgreSQL back- end daemons. The primary server does very little work if caching is enabled because the cache server caches all of the data needed. Allow for about 4 kb per managed object to cache meta-data without swapping. For example, a project with 50,000 object files would need 200 MB for cached metadata.
Network connectivity to Gigabit Ethernet or 1 Gbps Fibre Channel storage Storage device Network Attached Storage (NAS), such as a NetApp filer.
NOTE: Slow NFS connectivity can cause performance bottlenecks by blocking access to the SOS database. The next table lists the hardware requirements for the client systems where users run the SOS client software and their EDA tools. Table 3 Client System Hardware Requirements Resource Requirements and Recommendations CPU x86 at 1.5 GHz or faster. Memory Minimum of 4GB. Network connectivity 100 Mbps
Software Installation and Licensing 11 SOS Administration Guide Downloading and Installing the Software
This section covers the following topics: • Downloading • Installing the Software on Linux • Post-Installation Steps for Linux (Full Installation) • Installation Considerations for Multiple Linux Versions • Post-Installation Steps for the Standalone VDD Utility • Installing the Software on Windows NOTE: If you are upgrading your SOS software, read “Upgrading to a New Release of SOS” first.
Downloading
1 Visit www.cliosoft.com and log in to your support account. If you do not have an account, you must register for an account before downloading the software. 2 From the ClioSoft Support page, under Technical Resources, click Download Releases. 3 Click Download to accept the license agreement. 4 Click the link to download the installation file for your release.
Installing the Software on Linux
Follow these steps 1 Log in to the CAD tools software manager account. • Do not install the software as root. • ClioSoft recommends that you install the software using a dedicated account for ClioSoft administration, or an existing CAD software manager account. 2 For a first-time installation, create a directory in which to install the software. For example: % mkdir /edatools/clio 3 Copy or move the installation file to the installation directory. 4 Extract the installation files: % tar -xf filename This creates an installation directory with the name of the ClioSoft release. Previous installations will not be overwritten, because each version of the software uses a release-specific directory name. 5 Move (cd) to the new directory. % cd sos_6.25.p2_linux
Software Installation and Licensing 12 SOS Administration Guide
6 Run the installation script: % ./cliosoft.install NOTE: Usually you can press Enter or Return to accept the default choice at each step of the installation script. The next few steps explain the choices. 7 If you have already selected the correct installation directory, press Return or Enter at the first two questions: ** Current directory : /edatools/clio/sos_6.25.p2_linux Continue [y/n] (
Software Installation and Licensing 13 SOS Administration Guide Post-Installation Steps for Linux (Full Installation)
Your top-level installation directory now contains two directories and the .tar file. For example: SERVERS sos_6.25.p2_linux sos_6.25.p2_linux.tar The SERVERS directory initially contains empty LOCAL and REMOTE subdirectories. After you configure the SOS servers, the SERVERS directory will contain the ClioSoft server definitions. The installation script creates the SERVERS directory above the release-specific directory, so that the location does not change with every SOS software update. Each release-specific directory contains a symbolic link up to the actual SERVERS directory. For example: % ls -l sos_6.25.p2_linux/SERVERS lrwxrwxrwx 1 tools 10 Feb 7 10:54 sos_6.25.p2_linux/SERVERS -> ../SERVERS/ To complete the installation and prepare for future software updates: 1 (Recommended) Create a symbolic link for the newest release-specific directory. For example: ln -s sos_6.25.p1_linux latest_sos Over time, as you install updated SOS software, your top-level installation directory will look like this example: latest_sos@ -> sos_6.25.p2_linux SERVERS/ sos_6.25.p2_linux/ sos_6.24.p1_linux/ sos_6.23.p1_linux/ ... 2 Update your Linux startup file to set the ClioSoft environment variables: 1 Set the $CLIOSOFT_DIR variable to the path to the symbolic link. For example, for the C shell: setenv CLIOSOFT_DIR /edatools/clio/latest_sos For the Bourne shell: export CLIOSOFT_DIR=/tools/clio/latest_sos 2 Update your $PATH or $path environment variable to include $CLIOSOFT_DIR/ bin. 3 Update your $LD_LIBRARY_PATH environment variable to include $CLIOSOFT_DIR/lib. For 64-bit systems, use $CLIOSOFT_DIR/lib/64bit. 4 If you use Virtuoso, set GDM_USE_SHLIB_ENVVAR to 1. 3 By default, SOS uses $CLIOSOFT_DIR/SERVERS7 as the servers directory. You can override this location by having all users set the optional $SOS_SERVERS_DIR environment variable. You might choose to do this: • If you do not want to rely on the symbolic link to the SERVERS directory.
Software Installation and Licensing 14 SOS Administration Guide
• If you wish to use some other location for the directory for any reason. For example, some customers set up a different SERVERS directory for each project. Another reason to use a different location is if you install the SOS software on a read-only disk or partition, because the SERVERS directory must be writable by all users. Another way to relocate the SERVERS directory is by using a symbolic link; in this case, it is not necessary to have all of the users set $SOS_SERVERS_DIR: mkdir writable_servers_dir mkdir writable_servers_dir/LOCAL writable_servers_dir/REMOTE chmod -R a+rwx writable_servers_dir rm -rf $CLIOSOFT_DIR/SERVERS ln -s writable_servers_dir $CLIOSOFT_DIR/SERVERS These permissions allow any user to create a server. Omit the chmod command to restrict creating servers to administrators. 4 If you have a full installation but only want to use VDD as a standalone utility, set the CLIOSOFT_CDS_DIFF variable to 1. For example, for the C shell: setenv CLIOSOFT_CDS_DIFF 1 Here is a summary of the .cshrc file changes: setenv CLIOSOFT_DIR path_to_SOS_installation set path = ($path $CLIOSOFT_DIR/bin) setenv LD_LIBRARY_PATH "$CLIOSOFT_DIR/lib/64bit:$CLIOSOFT_DIR/ lib:$LD_LIBRARY_PATH" setenv GDM_USE_SHLIB_ENVVAR 1 Here is a summary of the Bourne shell .profile file changes: CLIOSOFT_DIR=path_to_SOS_installation PATH=$PATH:$CLIOSOFT_DIR/bin LD_LIBRARY_PATH="$CLIOSOFT_DIR/lib/64bit:$CLIOSOFT_DIR/ lib:$LD_LIBRARY_PATH" GDM_USE_SHLIB_ENVVAR=1 export CLIOSOFT_DIR LD_LIBRARY_PATH GDM_USE_SHLIB_ENVVAR NOTE: All users need to update their Linux startup file with these variables.
Installation Considerations for Multiple Linux Versions
You can install and run the SOS software on multiple versions of Linux. All of the platforms must share the same SERVERS directory.They also share the same licensing server and files. The recommended directory structure for a multi-platform $CLIOSOFT_DIR looks like this: latest_sos_linux@ -> sos_6.25.p2_linux/ latest_sos_linux5@ -> sos_6.25.p2_linux5/ SERVERS/ sos_6.25.p2_linux/ sos_6.25.p2_linux5/ sos_6.24.p1_linux/ sos_6.24.p1_linux5/ ...
Software Installation and Licensing 15 SOS Administration Guide
Create a separate “latest version” symbolic link for each platform, as shown in the example.
Post-Installation Steps for the Standalone VDD Utility
If you are only installing the standalone VDD utility and will not be using SOS for design management, follow the steps below and skip the remainder of this chapter. For a complete installation, skip ahead to the next section, “Post-Installation Steps for Linux (Full Installation)”. 1 (Recommended) Create a symbolic for the newest release-specific directory. For example: ln -s sos_6.25.p1_linux latest_vdd Over time, as you install updated SOS software, your top-level installation directory will look like this example: latest_vdd@ -> sos_6.25.p2_linux SERVERS/ sos_6.25.p2_linux/ sos_6.24.p1_linux/ sos_6.23.p1_linux/ ... 2 Set the $CLIOSOFT_DIR variable to the path to the directory where you installed the ClioSoft software. For example, for the C shell: setenv CLIOSOFT_DIR /edatools/clio/latest_vdd For the Bourne shell: export CLIOSOFT_DIR=/tools/clio/latest_sos 3 Add these lines at the end of each user’s .cdsinit file: let( (clioDir) clioDir = getShellEnvVar("CLIOSOFT_DIR") load((strcat clioDir "/scripts/cds_sosviadfII.il")) ) To ensure that all users can run SOS, make this change to the site (global) .cdsinit file, or include the change in the .cdsinit file in the project work area directory. 4 Add these lines to the cdsLibMgr.il file. These commands load the SOS menus when the Cadence Library Manager starts. let( (clioDir) clioDir = getShellEnvVar("CLIOSOFT_DIR") load((strcat clioDir "/scripts/cdsLibMgr.il")) )
Software Installation and Licensing 16 SOS Administration Guide Installing the Software on Windows
You can install the Windows version of the SOS software by using the interactive setup wizard, or in silent mode.
Installing the Software with the Windows Setup Wizard This procedure uses examples from Windows 7. Installation with other versions of Windows is similar. 1 Double-click the .exe file that you downloaded. 2 Click through any warning dialog boxes that appear. The installation wizard launches and the Welcome page appears.
3 Click Next to continue to the License agreement page.
Software Installation and Licensing 17 SOS Administration Guide
4 Click I Agree to accept the license agreement and continue to the Choose Installation Type page.
5 If you use SOS with Keysight ADS, choose ClioSoft for SOS via ADS. Otherwise choose Default. 6 Click Next and open the Choose Installation Folder page.
Software Installation and Licensing 18 SOS Administration Guide
7 Accept the default location (recommended) or click Browse and choose a different location. Then click Next.
8 Click Browse and choose a new or existing SERVERS folder. This will almost always be a folder on a remote system. Windows and Linux clients share a common SERVERS folder, so you almost never want to create the SERVERS folder in the default location on your local Windows disk. Here is a typical path to the folder: \\myserver.mycompany.com\edatools\clio\SERVERS If the shared SERVERS directory is not on a shared mounted directory, specify a SERVERS directory on the local disk and use the SOSAdmin application to create a local server that references the remote server. This lets you specify the server location with a URL, rather than a CIFS path. For instructions, see “Accessing Linux Servers from Windows Clients”. 9 Click Install to continue. 10Click Next in the Installation Complete page to view the Release Notes page, and then click Finish to complete the installation.
Installing the Windows Software in Silent Mode You can install the software in “silent” mode from the Windows command line. The syntax is: sos_version_win.exe /S [/INSTDIR=installPath] [/SERVERS=serversDir] where • /S selects silent (non-graphical) installation mode. If you omit this flag, the installation wizard launches. • version is the SOS software version.
Software Installation and Licensing 19 SOS Administration Guide
• installPath is the optional installation path. The default path for Windows 7 is C:\Program Files (x86)\ClioSoft\sos_release-number. If you are installing SOS to use with Keysight ADS, you must use this argument to override the default path and specify a path that does not contain spaces. • serversDir is the optional location of the SERVERS directory. The default location is installPath\..\SERVERS. Below are some examples. • To install at the default location: sos_6.23.p3s_win.exe /S • To install at a different location: sos_6.23.p3s_win.exe /S /INSTDIR=c:\cliosoft\sos_6.22.p3 • To install using a different location for the SERVERS directory: sos_6.23.p3s_win.exe /S /SERVERS=z:\cliosoft\SERVERS
Upgrading to a New Release of SOS
You do not need to upgrade the SOS software for all of your projects at the same time. However, it is best if the server and client software versions for everyone working on a given project match. In most cases, SOS client software versions 6.25.p2 or later can communicate with a newer version of the 6.xx server software, and 7.xx clients can communicate with newer versions of 7.xx. Clients can never communicate with older versions of the server software, and version 6.xx and 7.xx clients and servers cannot communicate with each other. Backwards compatibility of client software with newer minor versions of the server software is not guaranteed, however, and in some cases you may need to upgrade the client software to match the server software. With mixed versions, users will see warning messages advising them to update their client software to the latest version, or error messages when the versions are not compatible. You will use the existing license file and (for 6.xx minor version updates only) the existing SERVERS directory with the new version of the software, so be careful not to overwrite them. If you are upgrading from 6.xx to 7.xx, you will be creating a new SERVERS directory. (It’s important that 6.xx and 7.xx servers not share a SERVERS directory. This section covers the following topics: • Upgrading Linux Installations with SOS Minor Revisions • Upgrading Linux Installations from SOS 6 to SOS 7 • Upgrading Windows Installations
Upgrading Linux Installations with SOS Minor Revisions
Use this procedure if you are updating the SOS 6.xx software to a new version of SOS 6, or if you are updating the SOS 7 software to a new version of SOS 7.
Software Installation and Licensing 20 SOS Administration Guide
NOTE: If you are upgrading from SOS 6 to SOS 7, skip this section and follow the instructions in Upgrading Linux Installations from SOS 6 to SOS 7, next. 1 Follow the instructions in “Downloading” to download the software. 2 Log in to the CAD tools software manager account. 3 Copy the installation .tar file to your ClioSoft installation directory, $CLIOSOFT_DIR. If your installation follows the ClioSoft recommendations, that directory will now resemble this example, with one or more existing directories for ClioSoft releases and a .tar file for the release that you are about to install: % ls $CLIOSOFT_DIR latest_sos@ -> sos_6.24.p1_linux SERVERS/ sos_6.25.p2_linux.tar sos_6.24.p1_linux/ sos_6.23.p1_linux/ ... In the example, we are preparing to upgrade from SOS release 6.24.p1 to release 6.25.p2. 4 Follow the instructions in “Installing the Software on Linux”. After you run the installation script, you will have a new directory for the new release at the same level as the latest_sos symbolic link and the SERVERS directory. 5 Delete the existing symbolic link: rm latest_sos 6 Update the symbolic link to latest_sos to point to the new release: ln -s sos_6.25.p2_linux latest_sos 7 Shut down and restart the SOS servers with the Shutdown and Startup buttons in the SOSAdmin application. For instructions, see “Shutting Down and Restarting Servers”. 8 If your installation directory scheme is different than the suggestion above, and $CLIOSOFT_DIR does not point to a symbolic link that you can update, tell your users to update $CLIOSOFT_DIR to point to the new installation root. 9 Advise your users to exit and restart their design tools and the SOS client software so that they can begin using the new version. To force an update to running clients: 1 Click Clients in the SOSAdmin window. 2 Click Select All in the Clients dialog box. 3 Click Exit Clients.
Upgrading Linux Installations from SOS 6 to SOS 7
When upgrading to the SOS 7 software, you will need to recreate all of your servers with the SOS 7 software and then import your SOS 6 projects. The import process
Software Installation and Licensing 21 SOS Administration Guide
converts your project data from the ClioSoft proprietary database format to a PostgreSQL database. Follow the steps in the next sections to upgrade to SOS 7. NOTE: If you are upgrading from an earlier version of SOS 7, follow the instructions in the previous section, “Upgrading Linux Installations with SOS Minor Revisions”.
Preparing to Upgrade to SOS 7 1 Follow the instructions in “Downloading” to download the software. 2 Log in to the CAD tools software manager account. 3 Advise your users to exit their design tools and the SOS client software. To force an update to running clients: 1 Click Clients in the SOSAdmin window. 2 Click Select All in the Clients dialog box. 3 Click Exit Clients. 4 Shut down all of the SOS servers with the Shutdown button in the SOSAdmin application. For instructions, see “Shutting Down and Restarting Servers”. 5 (Recommended) Back up all of the active projects.
Installing the SOS 7 Software 1 Copy the installation .tar file to your ClioSoft installation directory, $CLIOSOFT_DIR. If your installation follows the ClioSoft recommendations, that directory will now resemble this example, with one or more existing directories for ClioSoft releases and a .tar file for the release that you are about to install: % ls $CLIOSOFT_DIR latest_sos@ -> sos_6.24.p1_linux SERVERS/ sos_7.00.b4_linux5.tar sos_6.24.p1_linux/ sos_6.23.p1_linux/ ... In the example, we are preparing to upgrade from SOS release 6.24.p1 to release 7.00.b4. 2 Follow the instructions in “Installing the Software on Linux”. After you run the installation script, you will have a new directory for the new release at the same level as the latest_sos symbolic link and the SERVERS directory. 3 Delete the existing symbolic link: rm latest_sos 4 Update the symbolic link to latest_sos to point to the new release: ln -s sos_7.00.b4_linux5 latest_sos
Software Installation and Licensing 22 SOS Administration Guide
5 If your installation directory scheme is different than the suggestion above, and $CLIOSOFT_DIR does not point to a symbolic link that you can update, tell your users to update $CLIOSOFT_DIR to point to the new installation root.
Post-Installation Steps when Upgrading to SOS 7 1 Recreate your SOS primary and cache servers using the SOSAdmin software. See “Setting Up Primary and Cache Servers”. 2 Create new projects for your existing projects. You can import the SOS 6 project data while you create a new project. See “Defining a New Project”. NOTE: If you will run both the SOS 6 and SOS 7 software, these two major versions of SOS should not share the same SERVERS directory. The default SERVERS directory names are different for these software versions: SOS 6 uses $CLIOSOFT_DIR/ SERVERS and SOS 7 uses $CLIOSOFT_DIR/SERVERS7. This means that, if you do not set $SOS_SERVERS_DIR, SOS will automatically use different directory names. If you override those default locations by setting $SOS_SERVERS_DIR, users who run both versions of the software need to set that variable to the correct value before launching the SOS or SOSAdmin software.
Upgrading Windows Installations
1 Exit the SOS software and your design tools. 2 Install the software as for a new installation, as explained in “Installing the Software on Windows”.
Licensing
This section describes how to set up and manage SOS licenses. SOS uses FlexNet to manage software licensing. The SOS software contacts the FlexNet license server daemon, lmgrd, running on a license server host on your network. Typically, your organization will already have a license server host set up for your EDA tool software, and you can use that license server host with the SOS software. Version 11.10.1 of FlexNet is included with the SOS software. You can run the license server on Linux or Windows hosts. When a user starts SOS, the SOS software contacts the license daemon on the license server to obtain a license. Licenses are keyed to the host ID of the license server. NOTE: The SOS software uses its own server daemon sosd for communication between SOS servers and clients. This daemon is not a license daemon. Typically, the license daemon (lmgrd) runs on the license server host, which may be a host on your local area network or a remote host. This section covers the following topics: • License Options • Obtaining License Keys from ClioSoft • About the ClioSoft License File
Software Installation and Licensing 23 SOS Administration Guide
• Setting Up Named User Licensing • Setting the License Server Environment Variable • Configuring Licensing for Windows
License Options
ClioSoft licenses are user-based. ClioSoft offers two options for licensing the SOS software: 24-hour reserved licensing and named user licensing. The default license option is 24-hour reserved licensing. With this option, anyone may check out a license. The license remains checked out for 24 hours after the user exits all of their SOS clients. Named user licensing requires that you maintain a FlexNet options file, typically named users.lst,that contains a list of user IDs. (This file may also specify other FlexNet options.) Only the listed users may run the SOS software, even if unused licenses are available. You can modify the list at any time, but you cannot add more users to the users.lst file than the number of purchased licenses. Changing the list requires stopping and restarting the license daemon. FlexNet limits the frequency of changes to the users.lst file. Large organizations generally prefer the 24-hour reserved licensing option to avoid the need to maintain a users.lst file and restart the daemon frequently. These licenses have the suffix _ul (“user linger”). With either licensing option, a single license lets a user run any number of SOS clients.
Obtaining License Keys from ClioSoft
Follow these steps to obtain paid or evaluation license keys: 1 Log in to the license server host. 2 Run these commands to determine the MAC address (FlexNet host ID) and the system host name: For Linux: % lmhostid lmhostid - Copyright (c) 1989-2006 Macrovision Europe Ltd. and/or Macrovision Corporation. All Rights Reserved. The FlexNet host ID of this machine is "000a225fe20c" % hostname speedy.mycompany.com NOTE: The Linux hostid command does not report the MAC address. Use the lmhostid command on Linux to determine the MAC address. NOTE: If you did not update your path environment variable to include the ClioSoft bin directory, the system might not locate these commands. If that happens, see the instructions in “Post-Installation Steps for Linux (Full Installation)” and set the required ClioSoft environment variables.
Software Installation and Licensing 24 SOS Administration Guide
For Windows 7: 1 From the Start menu, choose All Programs > Accessories > Command Prompt. 2 Type ipconfig and review the command output to determine the IP address of your wired Ethernet adapter. 3 From the Start menu, choose All Programs, choose the release-specific folder for the SOS software, and then choose FlexNet Utilities. 4 Click the System Settings tab and confirm that you are viewing the information for your wired Ethernet adapter. Although you may use the host ID of any of the adapters for licensing, ClioSoft recommends that you use the host ID of the local (wired) Ethernet adapter. If you use the host ID of the wireless adapter, licensing will fail whenever the wireless adapter is disabled.
The Ethernet Address value is the FlexNet host ID for your Windows system. A typical value is 008048e575e6. The Computer/Hostname is the Windows host name. 3 Send the FlexNet host ID and the host name in an email message to [email protected]. Please include your contact information, including a telephone number, and the names of the ClioSoft products that you have purchased (or want to evaluate).
About the ClioSoft License File
ClioSoft Support will send you a license file named license.dat in this format: SERVER enter_hostname_here lmhostid_for_server VENDOR cliolmd optional_cliolmd_path optional_options_file_path USE_SERVER FEATURE clio_sos_ent_ul cliolmd SOS_vers exp_date count license_key \ DUP_GROUP=U FEATURE clio_sos_viadfII_ul cliolmd SOS_vers exp_date count \ license_key DUP_GROUP=U
Software Installation and Licensing 25 SOS Administration Guide
where
Entry in License File Description SERVER License server keyword enter_hostname_here Placeholder for the license server host name. Replace this string with the actual host name or IP address. All users need to be able to ping this host by using the specified name or address. lmhostid_for_server Host ID as reported by lmhostid VENDOR Vendor keyword cliolmd The name of the ClioSoft license daemon optional_cliolmd_path The path to the ClioSoft license daemon. This is optional if both of these situations are true: you use 24-hour reserved licensing and the account that will launch the lmgrd daemon has $CLIOSOFT_DIR/bin in its $PATH variable. optional_options_file_ The path to a FlexNet options file path USE_SERVER Keyword to tell FlexNet to use a license server host FEATURE Each FEATURE line licenses one ClioSoft product. Typically you will have two feature lines in your license file: one FEATURE line for the core SOS software and a second line for the SOS integration with your EDA tools (Cadence Virtuoso in the example above). The _ul suffix to the feature name indicates that these are “user linger” licenses that remain assigned to any single user for 24 hours. If this suffix is missing, the feature is licensed with named user licensing. SOS_vers The main SOS version number, such as 6.0. FlexNet uses this number to validate that the license file is compatible with your SOS software version. exp_date License expiration date count Number of users. The value shows how many named user licenses your organization has purchased. With named user licensing, if you define more than the authorized number of users, nobody will be able to check out a license. license_key License key for the feature USER_BASED Keyword for named user licensing. If you have this type of license, update the VENDOR line in the license file that ClioSoft sent you to specify a users.lst file that identifies the authorized users. See “Setting Up Named User Licensing”. DUP_GROUP=U Keyword that allows a user to open multiple sessions on multiple displays
For example: # ------# ClioSoft License File generated on: 15.January.2013 # ------# Customer Details
Software Installation and Licensing 26 SOS Administration Guide
# ------... SERVER enter_hostname_here 12345678901 VENDOR cliolmd USE_SERVER FEATURE clio_sos_ent_ul cliolmd 6.0 1-mar-2013 25 23456789012 \ DUP_GROUP=U FEATURE clio_sos_viadfII_ul cliolmd 6.0 1-mar-2013 25 34567890123 \ DUP_GROUP=U Your license file contains FEATURE lines for some or all of the following ClioSoft product options:
FEATURE line ClioSoft Product Feature clio_grdiff Standalone Visual Design Diff for the Cadence Virtuoso environment (without SOS) clio_sos The core design data collaboration platform clio_sos_eepack A package license that includes the Enterprise features of SOS, including Visual Design Diff. clio_sos_ent The higher-tier Enterprise version of SOS with features for larger enterprises, including Visual Design Diff. This license combines the features of clio_sos and clio_sos_eepack. clio_sos_viaADS Integration with Keysight Advanced Design System (ADS) clio_sos_viaCD Integration with Synopsys Custom Designer clio_sos_viadfII Integration with Cadence Virtuoso clio_sos_viaICstudio Integration with Mentor Pyxis clio_sos_viaLaker Integration with Synopsys Laker clio_vdd Standalone Visual Design Diff for the Cadence Virtuoso environment (without SOS)
Specifying a Port Number
The ClioSoft administrator should specify the port number on which the server communicates with the ClioSoft license daemon as the last item on the SERVER line in the license file: SERVER my_hostname lmhostid portnumber NOTE: If you set or change the port number in the license file, restart lmgrd to re-read the file. Each user can specify the port number in the value of the CLIOLMD_LICENSE_FILE environment variable: CLIOLMD_LICENSE_FILE = port@host To set $CLIOLMD_LICENSE_FILE, see “Setting the License Server Environment Variable”. If you do not specify the port number with the CLIOLMD_LICENSE_FILE environment variable, FlexNet will automatically attempt to communicate on port numbers 27000 through 27009, trying each port number in turn until the ClioSoft daemon responds.
Software Installation and Licensing 27 SOS Administration Guide
ClioSoft recommends that you specify the port number explicitly as described above, even if you use a port number within the default range, to speed up communication between the ClioSoft and FlexNet daemons.
Setting Up Named User Licensing
If your organization selected named user licensing, the license file that you receive from ClioSoft will resemble this example: # ------# ClioSoft License File generated on: 15.January.2013 # ------# Customer Details # ------... SERVER enter_hostname_here 123456678 VENDOR cliolmd USE_SERVER FEATURE clio_sos cliolmd 6.0 30-sep-2013 10 2345667788 USER_BASED \ DUP_GROUP=U FEATURE clio_sos_viadfII cliolmd 6.0 30-sep-2013 10 CD233554455 \ USER_BASED DUP_GROUP=U FEATURE clio_sos_eepack cliolmd 6.0 30-sep-2013 2 FC2323234555 \ USER_BASED DUP_GROUP=U You will need to update the VENDOR line before you install the license file. For named user licensing, the VENDOR line must specify the path to the users.lst file, a FlexNet options file that lists the authorized SOS users. This line also specifies the path to the ClioSoft license daemon executable, cliolmd, when you have named user licensing. NOTE:If the FEATURE lines in your license file do not contain the USER_BASED keyword, you have 24-hour licensing and you do not need to set up named user licensing. Here is an example VENDOR line: VENDOR cliolmd /server1/opt/clio/latest_sos/license/cliolmd ./users.lst Follow these steps to set up named user licensing: 1 Edit the VENDOR line in your license file and specify the correct paths to the ClioSoft license daemon cliolmd and the users.lst file. 2 Copy the sample users.lst file from the $CLIOSOFT_HOME/license directory, and open the file in a text editor. 3 Edit the GROUP SOS_USERS line and replace the placeholder names (user1, ...) with the login names of the authorized users. Optionally, you could define separate groups for each SOS feature. GROUP SOS_USERS tnguyen pjones gsingh rschultz dchen skatz
Software Installation and Licensing 28 SOS Administration Guide
4 Create INCLUDE lines for each FEATURE line in your license file. Typically this means one INCLUDE line for either the clio_sos or clio_sos_ent feature, and a second INCLUDE line for the integration with your CAD environment: INCLUDE clio_sos GROUP SOS_USERS INCLUDE clio_sos_viadfII GROUP SOS_USERS 5 Save the users.lst file to the location that you specified on the VENDOR line in your license file. If some users need access to different features, you can create multiple groups. For example, if only some of the users need access to the Cadence Virtuoso software, but all of the users run SOS in standalone mode, you might set up these two groups: GROUP SOS_USERS user1 user2 user3 user4 GROUP SOS_USERS_CDN user1 user2 INCLUDE clio_sos GROUP SOS_USERS INCLUDE clio_sos_viadfII GROUP SOS_USERS_CDN
Setting the License Server Environment Variable
FlexNet uses an environment variable to determine the license server host name, and optionally the port number. Every SOS user needs to set a license server environment variable.Cliosoft recommends that you set $CLIOLMD_LICENSE_FILE.You can also set $LM_LICENSE_FILE, but communication with the license daemon may be slower. In Linux, use the setenv or export command to set environment variables. On a Windows system, select My Computer > Properties, open the Advanced tab, click Environment Variable, and create the variable as a System variable. To specify both the server host name and port number, use this format (C shell): setenv CLIOLMD_LICENSE_FILE port@hostname For example, in the C shell: setenv CLIOLMD_LICENSE_FILE 21541@licserver01 The port number should match the value that you specified on the SERVER line in the license file. See “Specifying a Port Number”. To specify just the host name, and let FlexNet determine the correct port number, use this format: setenv CLIOLMD_LICENSE_FILE @hostname
Configuring Licensing for Linux
Starting or Restarting the License Daemon To start the ClioSoft license daemon: 1 Log in to the license server host as the ClioSoft administrator. 2 Start the license daemon: lmgrd -c path_to_license_file -l path_to_license_log_file
Software Installation and Licensing 29 SOS Administration Guide
3 After a few seconds, check the status of the license daemon: lmstat -a -c path_to_license_file If the lmstat command reports a problem, check the messages in the license log file that you specified with lmgrd. 4 (Recommended) Update the appropriate Linux startup file so that the ClioSoft license daemon starts automatically when the server restarts. Specify the full path to the lmgrd command in the startup file. If you change your ClioSoft license file or the users.lst file, you must stop and restart the ClioSoft license daemon to activate the changes. Stop the license daemon with the command lmdown -c path_to_license_file, and then restart the daemon with lmgrd.
Configuring Licensing for Windows
Specifying the License Server Host To specify the license server host: 1 From the Start menu, choose Control Panel. 2 In Windows 7, click System and Security, and then click System. 3 Click Advanced system settings to open the System Properties dialog box. 4 Click Environment Variables. 5 Click New under System variables. If you do not have permission to create system variables, click New under User variables instead. 6 For the Variable name, enter CLIOLMD_LICENSE_FILE. 7 For the Variable value, enter the PORT@HOST information for the license server. For example, if the license server is running on host licserver01 using port 21541, specify 21541@licserver01. 8 Click OK to create the variable, click OK again to close the Environment Variables dialog box, and finally click OK to close the System Properties dialog box.
Configuring the FlexNet License Service If you host the ClioSoft license daemon on the Windows system, you need to configure a Windows service for FlexNet on that system. If you host the license daemon on a Linux system, you can skip these steps. 1 Log in to the Windows system as a user with Administrator privileges.
Software Installation and Licensing 30 SOS Administration Guide
2 From the Start menu, choose All Programs, choose the release-specific folder for the SOS software, right-click FlexNet Utilities, and choose Run as administrator from the menu.
3 Select the Configuration using Services radio button. 4 Click the Config Services tab. 5 For Service Name, enter clio_sos. 6 For Path to the lmgrd.exe file, click Browse and locate the file under the license folder of your ClioSoft software folder. 7 For Path to the license file, specify the location of license.dat. By default, the Browse dialog box shows .lic files rather than .dat files; choose .dat files from the License Files list box so that you can choose the license.dat file. 8 For Path to the debug log file, specify the license.log file. ClioSoft recommends that you not store this file in the license folder. 9 Click Save Service.
Starting the FlexNet Service 1 From the Start menu, choose All Programs, choose the release-specific folder for the SOS software, right-click FlexNet Utilities, and choose Run as administrator from the menu. 2 Click the Start/Stop/Reread tab. 3 Highlight the clio_sos service and click Start Server. 4 Wait a few seconds and then click the Server Diags tab.
Software Installation and Licensing 31 SOS Administration Guide
5 Type the feature name clio_sos and click Perform Diagnostics. 6 If a problem is reported, check the license.log file.
Restarting the FlexNet Service After a Change in Licensing If you change your ClioSoft license file or the users.lst file, you must stop and restart the ClioSoft license service to activate the changes. 1 From the Start menu, choose All Programs, choose the release-specific folder for the SOS software, right-click FlexNet Utilities, and choose Run as administrator from the menu. 2 Click the Start/Stop/Reread tab. 3 Highlight the clio_sos service and click Stop Server. 4 After the service stops, click Start Server.
Verifying the Installation
To verify the software installation, confirm that you can start the SOS software. • For Linux, type sos at the command prompt in the terminal window where you set the ClioSoft environment variables. • For Windows, choose Start > SOS > sos. NOTE: To verify the license configuration, you need to create an SOS work area or start SOS within an existing work area. See the next chapter for instructions.
Software Installation and Licensing 32 SOS Administration Guide Integrating SOS with Your CAD System
Integration with Keysight ADS Integration with Cadence Virtuoso Integration with Mentor Pyxis Integration with Synopsys Custom Designer Integration with Synopsys Laker
Integration with Keysight ADS
Update the SOS client configuration file, sos.cfg, to include the template that supports ADS: $CLIOSOFT_DIR/adaptors/ads/sos.cfg. • If all projects use Keysight ADS, append the template to either the site customization file, $SOSD_CONFIG_DIR/sos.cfg, or the system default file, $CLIOSOFT_DIR/data/sos.cfg. • If some projects use other design tools, update the project-specific sos.cfg files in server_name.rep/project_name/setup for each ADS project. • For work areas on a Windows system, update the sos.win.cfg file instead of sos.cfg. For example: cat $CLIOSOFT_DIR/adaptors/ads/sos.cfg >> \path_to_repository/setup/sos.cfg NOTE: Each individual user needs to configure ADS to load the SOS add-on. For instructions, see Getting Started with SOS for ADS Designers.
Integration with Cadence Virtuoso
Integration of SOS with the Cadence Virtuoso software requires changes to three Virtuoso configuration files:
File Description .cdsinit Virtuoso startup file cdsLibMgr.il Cadence Library Manager startup file cdsinfo.tag Cadence information file that contains the Design Manager (DM) tool configuration
ClioSoft recommends that you include all three files, and the cds.lib file, in the SOS project. This lets the files be automatically copied or linked into each user’s work area directory, so that everyone has the correct versions of the files. A typical work area would have this structure: • docs (specifications and other documentation) • scripts • rtl (Verilog and VHDL files)
Software Installation and Licensing 33 SOS Administration Guide
• testbenches (regression tests and test data) • cds (parent directory for Cadence libraries) • proj_lib1 (one of the project libraries) • proj_lib2 (another project library) • scratch_lib (a library for the user’s temporary work) The .cdsinit, cdsLibMgr.il, and cds.lib file, would be stored in the cds directory in this example project structure. Create a cdsinfo.tag file in each Cadence library directory. The next sections explain the changes that each file requires, and the best practice recommendations for setting up your cds.lib file.
.cdsinit Add these lines at the end of the .cdsinit file: let( (clioDir) clioDir = getShellEnvVar("CLIOSOFT_DIR") load((strcat clioDir "/scripts/cds_sosviadfII.il")) ) NOTE: To ensure that all users can run SOS, make this change to the site (global) .cdsinit file, or include the change in the .cdsinit file in the project work area directory.
cdsLibMgr.il Add these lines to the cdsLibMgr.il file. These commands load the SOS menus when the Cadence Library Manager starts. let( (clioDir) clioDir = getShellEnvVar("CLIOSOFT_DIR") load((strcat clioDir "/scripts/cdsLibMgr.il")) ) cdsinfo.tag The cdsinfo.tag file tells Virtuoso which Design Management (DM) system to use, if any. Each library directory should contain a cdsinfo.tag file with the correct settings for that library: • Project libraries that you manage with SOS need to specify SOS as the DM system. Include this line in the file: DMTYPE sos • Unmanaged reference or scratch libraries should not specify any DM system. Include this line in the file: DMTYPE none There should be no other DMTYPE settings in the cdsinfo.tag files.
Software Installation and Licensing 34 SOS Administration Guide
cds.lib Each user’s personal cds.lib file should be an unmanaged file (outside SOS revision control) in the cds directory of their work area. All users should include a common project.lib file in their personal cds.lib file: INCLUDE ./project.lib The project.lib file is managed in SOS. This means that all users get the same definitions for the project working and reference libraries. Definitions for the project working libraries use relative pathnames, because each user must refer to the library in their work area. Definitions for reference libraries use full pathnames. Here is an example: # Reference libs not managed by SOS DEFINE ref_lib1 /projects/common/reflibs/ref_lib1 DEFINE ref_lib2 /projects/common/reflibs/ref_lib2 DEFINE ref_lib3 /projects/common/reflibs/ref_lib3 DEFINE pdk_lib /projects/common/pdks/pdk_lib
# Project libraries DEFINE proj_lib1 ./proj_lib1 DEFINE proj_lib2 ./proj_lib2 Checking Your Startup File Changes 1 Launch Virtuoso and open any schematic, symbol, or layout cellview. 2 Click the Design Manager menu and look for the Check Out, Check In, and Manage Hierarchy commands.
If those commands appear, you have updated your startup files correctly. 3 Exit Virtuoso.
Integration with Mentor Pyxis
To set up a user’s environment to use SOS with the Mentor Pyxis software release 10.2_3 or later: 1 Set these environment variables:
Software Installation and Licensing 35 SOS Administration Guide
setenv MGC_HOME mentor-installation-dir setenv MGLS_LICENSE_FILE port@host setenv AMPLE_PATH $CLIOSOFT_DIR/adaptors/dmgr/userware 2 Add $MGC_HOME/bin to your path. To add an existing MGC project to SOS revision control and set up the project administrator’s work area: 1 Create a new SOS work area. 2 Copy the MGC project files to the new work area. 3 From the work area directory, start Pyxis Project Manager. The Revision Control menu should appear at the top of the window. 4 Open the project by selecting File > Open Hierarchy. 5 Add the project to revision control by selecting the project on the left side of the window and then selecting Revision Control > Add Project. ClioSoft recommends that you create SOS projects for each MGC project, but this is not a requirement. You can add multiple MGC projects to the same SOS project.
Integration with Synopsys Custom Designer
Follow these steps to integrate SOS with the Synopsys Custom Designer software: 1 Set the $SYNOPSYS_CUSTOM_SITE environment variable. This variable points to the directory that contains the Synopsys third-party software integration files. This directory is normally readable by all users but writable only by the administrator. ClioSoft recommends that you create this directory in the installation directory for either the SOS or the Synopsys software. setenv SYNOPSYS_CUSTOM_SITE path_to_directory 2 Create the images subdirectory under $SYNOPSYS_CUSTOM_SITE. 3 Create the SOS symbolic link in the images directory under $SYNOPSYS_CUSTOM_SITE.This link lets the Custom Designer software find the SOS icons to display in the Library Manager. These icons show the status of objects in the SOS project (checked in, checked out, and so forth). mkdir $SYNOPSYS_CUSTOM_SITE/images ln -s $CLIOSOFT_DIR/adaptors/cdesigner/images/sos \ $SYNOPSYS_CUSTOM_SITE/images/sos 4 Update the SOS client configuration file, sos.cfg, with the rules for handling the related files that comprise a cellview together as a single package. If all projects will use Synopsys Custom Designer, you can update the site customization file $SOSD_CONFIG_DIR/sos.cfg or the system default file, $CLIOSOFT_DIR/data/sos.cfg. If some projects use other design tools, update the project-specific file, server_name.rep/project_name/setup/sos.cfg. The template with the required changes is: $CLIOSOFT_DIR/adaptors/cdesigner/sos.cfg.
Software Installation and Licensing 36 SOS Administration Guide
For example: cat $CLIOSOFT_DIR/adaptors/cdesigner/sos.cfg >> \ path_to_repository/setup/sos.cfg 5 Update the $SYNOPSYS_CUSTOM_SITE/.cdesigner.tcl file. This file contains Custom Designer customizations for third-party tools. You can have many custom integrations being loaded from the same file. Append $CLIOSOFT_DIR/adaptors/cdesigner/.cdesigner.tcl to the $SYNOPSYS_CUSTOM_SITE/.cdesigner.tcl file. For example: cat $CLIOSOFT_DIR/adaptors/cdesigner/.cdesigner.tcl >> \ $SYNOPSYS_CUSTOM_SITE/.cdesigner.tcl Integration with Synopsys Laker
To integrate SOS with the Synopsys Laker software: 1 If the file laker_install_path/integration/SOS/integ.tcl is not already installed, run these commands: mkdir laker_install_path/integration/SOS cp $CLIOSOFT_DIR/scripts/sos_laker_main_menu.tcl \ laker_install_path/integration/SOS/integ.tcl Recent versions of the Laker software have this file pre-installed. 2 Update the laker.rc file to enable SOS data management by including or editing these lines: [DataManagement] DMAutoCheckOutCV = Prompt DMAutoCheckInCV = Never DMAutoCheckOutInFile = Prompt DMToolType = SOS [LeoPreference] MCellVersionControl = TRUE
Installing and Configuring the SOS Web Client
The SOS Web interface lets users connect to SOS projects with a Web browser and perform common project management tasks. The Java-based Web server is included in the SOS software distribution. For installation and configuration instructions, see $CLIOSOFT_DIR/web/README. NOTE: By default, the Web interface includes commands for modifying objects, such as the check out command. To restrict the Web interface to read-only mode, set the environment variable SOS_WEB_READONLY to 1 before starting the Web server.
Software Installation and Licensing 37 CHAPTER 3SETTING UP SOS SERVERS AND PROJECTS
This chapter explains how to set up SOS servers and SOS projects in the following sections: • About SOS Servers, Clients, Projects, and Work Areas • Using the SOSAdmin Application • Setting Up Primary and Cache Servers • Creating Projects
Setting Up SOS Servers and Projects 38 SOS Administration Guide About SOS Servers, Clients, Projects, and Work Areas
All of the libraries, cellviews, and other files associated with a design are stored in a central SOS project repository (a project), which is a PostgreSQL relational database. Each project has an associated primary SOS server. This server software daemon manages access to the data. The server name is a symbolic name that clients use to connect to a project. The process of setting up a server defines a primary server daemon and optionally a cache server daemon. These daemons are processes running on a host machine. NOTE: In this manual, the term server refers to an SOS software daemon, not the host machine on which that daemon runs. Designers run the SOS client software together with their EDA design tools. The SOS server communicates with the clients through a cache server to provide users with access to the design data. Each designer has their own “sandbox” or work area that contains project libraries and cellviews that are shared between everyone working on a project. A designer’s work area contains writable copies of the files that they have checked out of the project to edit, plus read-only copies of the other project files. This means that designers do not need to create their own editable “scratch” copies of the project libraries. Figure 1 shows the simple case of an SOS project and its primary server, with two users. Both users run the SOS client software and work with the project files in their work areas. Figure 1: The Simplest Case: SOS Server with Two Clients
For optimal performance, SOS primary servers should always have a cache server that handles the clients’ requests to check files into and out of the project. This is called the local cache server: “local” in the sense that both servers are located at the same geographic location, and usually run on the same host computer. Figure 2 shows this more realistic simple case. Figure 2: A More Realistic Simple Case
Setting Up SOS Servers and Projects 39 SOS Administration Guide
Most large design teams are spread out across multiple sites, often in more than one country. Figure 3 illustrates this arrangement. For multi-site installations, there is usually a primary SOS server at the main development site and an SOS cache server at every site. This arrangement gives every user access to all of the project’s files, as though they worked at the same facility. For the design team shown in Figure 3, when Sally (a designer in San Jose) checks in a new cellview, her new cellview gets copied to both the primary server in San Jose and the cache server in Shanghai. The designers in Shanghai can begin using Sally’s new cellview immediately. Figure 3: Cache Server for a Remote Design Team
You can configure the cache server to be automatically updated immediately with changed files from the primary server, updated at a specified frequency, or updated on demand whenever a local user needs a file. Metadata about changes is always synchronized between the primary and cache servers.
Maximizing Performance
The SOS software performs very little computation but is “disk bound” because it reads and writes many files frequently. The key to maximizing performance is to improve access to files on disk: • If you use network-attached storage (NAS), which is the most common situation, choose high-performance hardware. If there is high latency between the NAS and the SOS primary and database servers, communication with the PostgreSQL database will not be optimal and users may experience delays. • For the best possible performance, store the project repository and cache on a local disk on the server host system, rather than using network-attached storage. • Use a separate SOS server daemon for each SOS project.
Setting Up SOS Servers and Projects 40 SOS Administration Guide
• Have users create their work areas on a local disk, not a network disk. This also improves the performance of your design tools.
Planning for Multiple Projects and Sites
When planning the hardware and software for multiple projects and multiple work facilities, keep these best practices in mind: • Each primary server should support only a few, or (for maximum performance) just one project. • Set up a cache server for each project at each site. • The primary server for a project should be hosted at the site with the largest number of users.
Organizing Project Data on File Servers
SOS stores project data in three locations: • The main server repository directory, under which all of the data for all of the projects on the server gets stored • The project cache •User work areas Typically, all of the data is located on a network storage device. Data directories are organized by data type: all of the repositories for all of the projects on the server are stored under a single .rep directory (under repositories in the figure), and the cache and work area subdirectories for each project can be similarly organized under a main directory (cache and workareas in the figure). The
Setting Up SOS Servers and Projects 41 SOS Administration Guide
figure shows the directories for an organization with two SOS servers (trinity and neo). Figure 4: Data-Type-Specific Directories
This approach lets you isolate the repository on a separate file server or mount point, protecting both the server and the repository from performance and disk space issues caused by users’ simulation and verification runs. The cache and work area directories would typically be stored on a second file server or mount point, although you may choose to use a separate file server for each. The .rep directory for each server contains a pg_data subdirectory for the PostgreSQL database, and separate subdirectories for each project’s configuration files.
Data Security
To encrypt communication and file transfers between servers, select Use SSL in the New Server dialog box when you create the servers. You can also enable this option for existing servers. See To restrict access to the project data, you can configure the servers to require client authentication. See “Configuring Client Authentication”.
Setting Up SOS Servers and Projects 42 SOS Administration Guide Using the SOSAdmin Application
You use the SOSAdmin application to define and manage SOS servers and their projects. To start the SOSAdmin application, log in to the administrator’s account and run the sosadmin command. Figure 5: SOSAdmin Window
NOTE: The SOSAdmin application also has a command line interface. The syntax is: sosadmin command [arguments] For a list of commands, type sosadmin help. For detailed help about a particular command, type sosadmin help command. The examples in this manual use the SOSAdmin application, not the command line. The Running column shows the status of each server: Table 4 Server Status Values Running Column Description (SOS software version number) The server is running normally. no The server is not running. (blank) No cache server is defined for this primary server. ?? The server is defined, but SOSAdmin has not yet determined the server status.
The other columns show the information that you enter when you define a server. See “Setting Up Primary and Cache Servers”.
Setting Up SOS Servers and Projects 43 SOS Administration Guide
The next table describes the command buttons in the SOSAdmin window: Table 5 SOSAdmin Window Commands Command Description New Create a new SOS primary or cache server. See “Setting Up Primary and Cache Servers”. Edit Update the settings for an SOS server. Delete Permanently delete an SOS server. Deleting a server does not delete the project repository. Startup Start an SOS server that is not running. Shutdown Stop a running SOS server. Reread Config Read changes in the server configuration file. See “Configuring Projects with sosd.cfg”. Ping Check the status of the selected primary and cache servers. Ping All Check the status of all of the servers and update the status of the Running columns. Projects Create or manage projects. See “Creating Projects”. Project Map Define servers for reference projects whose files may be used in other projects. See “Defining Reference Projects”. Clients See who is connected, send messages to connected clients before shutting down a server, close connections to the clients, or exit the clients.
Setting Up Primary and Cache Servers
This section explains how to set up new servers. Before you begin, log in as the administrative user. The user who creates a server becomes the owner of the server and all of its projects. Only the owner may start, shut down, edit, or delete the server.
Configuring a Primary Server and its Local Cache Server
ClioSoft recommends that you set up a cache server for the primary site, even if you run both servers on the same host. Follow these steps to set up both servers: 1 In the SOSAdmin window, click New.
Setting Up SOS Servers and Projects 44 SOS Administration Guide
The New Server dialog box appears.
2 Use these recommendations to configure the new server: 1 Enter a Symbolic name for the server that identifies this design project. Use the same name when you later define the SOS project managed by this server. 2 Confirm that Set up a new primary server is selected and enter the host name for the new server. This host name will only be used by clients at this site to connect to the server. Clients at the remote site connect to the server that is defined at the remote site, and there they may need to specify a fully qualified host name or IP address. 3 For the Host Port, enter a port number between 5000 and 50000. You can choose any values that your local network administrator does not block. Do not use port numbers that other SOS servers are using, or port numbers that other processes on the host machine are using. Click Recommend to automatically choose valid, available port numbers. (If you started SOSAdmin on a different host, the recommendation might not be correct.) 4 Click Browse opposite Repository Path and specify the parent directory for the project repository. 5 Optionally, select Use SSL to encrypt communication between the servers. For instructions, see Configuring SSL. 6 Choose Yes for Client Authentication Required if you want project users to enter their user name and password each time they start a session with the design tools and SOS software. Most organizations do not require this level of
Setting Up SOS Servers and Projects 45 SOS Administration Guide
security. For information about configuring client authentication, see “Configuring Client Authentication”. 7 Confirm that Set up a new cache server is selected, and enter the host name. If you expect the load on the servers to be very heavy, specify a different host name. Otherwise, set up the cache server on the same host as the primary server host. 8 For the Cache Command Port, enter a port number between 5000 and 50000. Do not use the same values that you selected for the primary server port, or ports used by any other servers running on this host. Click Recommend to automatically choose valid, available port numbers. 9 Click Browse and select or create a directory for the cache files. For optimal performance this should be a directory on a local disk, but in most cases you will need to select a Network Attached Storage disk. If you plan to use links to cache work areas, the path should be a full pathname that all other users can also access by using the exact same pathname. 10Set an appropriate value for Update. ClioSoft recommends these choices: • If you have only one site, choose On Demand. • If you have multiple sites in widely-separated time zones, choose Every and specify an interval of 60 minutes. • If you have multiple sites in nearby time zones, choose Immediate. 3 Click OK to create the primary and cache servers. 4 In the SOSAdmin window, click Startup, wait a few seconds for this dialog box to appear, and click Yes.
Setting Up SOS Servers and Projects 46 SOS Administration Guide
5 Starting a server on a remote host may require SSH authentication. If prompted, enter the network administration password.
6 In the SSH terminal window, type yes to connect securely to the server host. 7 Wait a few seconds and click Ping in the SOSAdmin window to check the server status. Also check for messages in the terminal window where you started SOSAdmin. If the Ping command reports that it was unable to connect to the server then wait for a few more seconds and try again. If the server fails to start, check the primary server log file (server.log) and cache server log file (srv_cache.log) for messages. By default, these logs are located here: $CLIOSOFT_DIR/SERVERS/LOCAL/server_name However, if you have set $SOS_SERVERS_DIR, the log files are located here: $SOS_SERVERS_DIR/LOCAL/server_name The Ping command will fail if another process is using the port. If you suspect this problem, click Edit, change the port number, and try to start the server again. You can use the ps command to check the status of the server daemon processes. The primary server daemon process is sosd -primary, and the cache daemon process is sosd -cache. Next Steps: • If remote sites need to access this server, set up their remote cache servers now. • Next, create the SOS project that this server will manage. See “Creating Projects”.
Setting Up SOS Servers and Projects 47 SOS Administration Guide Setting Up a Remote Cache Server
1 In the SOSAdmin window, click New. The New Server dialog box appears.
2 For the Symbolic name, use the primary server name. 3 Select Use an existing primary server and specify the Host Name and its Host Port. The values must match the host name and host port number of the primary server that you set up at the primary site. This site should be able to ping the host at the primary site by using the given name. If you cannot access the primary server host by name, specify the IP address instead. 4 Optionally, select Use SSL to encrypt communication between the servers. For instructions, see Configuring SSL. 5 Choose Set up a new cache server. 6 Set the cache server options as described in the previous section, “Configuring a Primary Server and its Local Cache Server”. When you finish, click OK. 7 Highlight the new server name in the SOSAdmin window and click Startup. 8 Click Yes to start the cache server. 9 Wait a few seconds and click Ping in the SOSAdmin window to check the server status. 10Update the project map to include the new cache server: 1 Click Project Map. 2 In the Project > Server Mapping dialog box, click Automatic to update the map and then click Dismiss.
Setting Up SOS Servers and Projects 48 SOS Administration Guide Accessing Linux Servers from Windows Clients
ClioSoft recommends that you store the SERVERS directory on a shared drive that is accessible from both Windows and Linux systems. For each Windows user, set the environment variable SOS_SERVERS_DIR to this shared directory. This lets all users see all of the defined servers, or any configuration changes to an existing server. If using a shared drive for the SERVERS directory is not possible, use the SOSAdmin application on each Windows client system to specify the primary server by following these steps: 1 In the SOSAdmin window, click New. 2 For the Symbolic name, use the primary server name. 3 Select Use an existing primary server and specify the Host Name and its Command Port. If you cannot access the primary server host by name, specify the IP address. 4 Optionally, select Use an existing cache server and specify the Host Name and its Command Port. For a single-user installation, do not use a cache server. 5 Click OK when you finish setting up the server. 6 Wait a few seconds and click Ping in the SOSAdmin window to check the server status.
Starting the SOS Servers Automatically
Use these procedures to start the SOS servers automatically whenever the server host reboots.
Linux For Linux hosts, add these lines to /etc/rc.local: #!/bin/sh # Start SOS Servers CLIOSOFT_DIR=path_to_SOS_software export CLIOSOFT_DIR echo echo "Starting SOS Server server_name" echo su owner_of_sos_server -c "$CLIOSOFT_DIR/bin/sosadmin startup server_name" >/dev/null 2>&1 exit 0 Replace path_to_SOS_software, owner_of_sos_server, and server_name with the correct values for your situation.
Windows
NOTE: It is very uncommon to run the SOS server daemons on Windows.
Setting Up SOS Servers and Projects 49 SOS Administration Guide
The daemons run as Windows services. Follow these steps to configure those services to start automatically. 1 From the Control Panel, click Administrative Tools and then click Services. 2 Find the SOS service in the list. It will be named sosd SOS_SERVER_NAME or sosd_cache SOS_SERVER_NAME. 3 Set that service to start up automatically.
Configuring SSL
You can configure SOS to use SSL for secure communication between primary and cache servers.
Prerequisites You will need: • A CA certificate • A private key file • A pass phrase.
Configuring the Primary Server 1 Select Use SSL in the New Server or Edit Server dialog box. 2 Click Browse opposite Certificate File and specify the path to the certificate file. 3 If the certificate is password-protected, enter the password in the Cert Password field. Otherwise leave this field blank. 4 Click Browse opposite Private Key and specify the path to the private key file. 5 For PassPhrase, enter an 8-32 character pass phrase.
Configuring the Cache Server at a Remote Site 1 Select Use SSL and Same as Primary. 2 Enter the same pass phrase in the PassPhrase field.
Configuring Client Authentication
You can require users to authenticate with their Linux user name and password when they start the SOS or SOSAdmin client software. Client authentication uses the open-source Pluggable Authentication Module (PAM) software. NOTE: Authentication of Windows clients to a Linux server is supported. Authentication is not supported for servers running on Windows.
Setting Up SOS Servers and Projects 50 SOS Administration Guide
Configuring PAM for Linux SOS Primary server daemons will use the service cliosoft for PAM authentication. For help configuring PAM on your Linux host, see the documentation available on the Internet. These are the basic steps: 1 Log in as root on the primary server host. 2 cd /etc/pam.d 3 cp su cliosoft
Configuring the SOS Software for Client Authentication Follow these steps to enable client authentication in the SOS software: 1 Enable PAM authentication on the server host. Use the instructions in the previous section, or follow the instructions for the version of PAM that you have installed on the host. 2 Shut down the SOS server. 3 In the New Server or the Edit Server Configuration dialog box, choose Yes for Client Authentication Required. 4 Restart the server.
Connecting Using Authentication The first time a user tries to use SOS during a session, they are prompted to enter credentials in the SOS Authentication dialog box.
If a user does not have an X display and the SOS process is not already running, the user must follow these steps to authenticate from the command line: 1 Start SOS without an X display: sos -nowin 2 When prompted, enter a user name and password on the command line. 3 Background the sos process:
Setting Up SOS Servers and Projects 51 SOS Administration Guide Creating Projects
• Defining a New Project • Adding Files to a Project
Defining a New Project
The steps for defining a new project depend on whether you are importing file system data or data from another revision control system. Follow the steps in the next section if your data is not already stored in a revision control system. If your data is already stored in a different revision control system, skip ahead to Migrating Data from Other Revision Control Systems Into a New Project instead.
Defining a New Project with File System Data Follow this procedure to import file system data into a new project. 1 Highlight the primary server in the SOSAdmin window and click Projects. The Projects window for the server opens.
NOTE: The Import command lets you restore a project that you archived with the Export command. To migrate an SOS 6.xx project to the current release, continue with these instructions and use the Import option in the Create a New Project dialog box.
Setting Up SOS Servers and Projects 52 SOS Administration Guide
2 Click New. The Create a New Project dialog box opens.
3 For the Name of the Project, use the same name as the server to simplify project administration. 4 (Optional) Enter the account names for the project administrators, separated by commas. If you leave this field blank, the default project administrator is the owner of the server. 5 (Optional) Enter Comments to describe the project. 6 (Optional) To migrate an SOS 6.xx repository to SOS 7.0, select Import an SOS 6 repository and browse to the repository directory. Repository directories have the .rep name suffix. 7 Click Ok to create the project and then click Dismiss to close the Info dialog box that opens.
Migrating Data from Other Revision Control Systems Into a New Project If your existing design data is already under Linux revision control, you can use the ClioSoft utilities to import the data into a new project. The revision control systems listed in the table are supported: Table 6 Utilities for Importing Data Under Revision Control Revision Control Systems ClioSoft Import Utility RCS rcs_import CVS cvs_import SVN svn_import
Setting Up SOS Servers and Projects 53 SOS Administration Guide
Table 6 Utilities for Importing Data Under Revision Control Revision Control Systems ClioSoft Import Utility VersionSync vs_import DesignSync dssc_import.pl Type any of the import commands with no arguments to see a usage message.
Adding Files to a Project
With SOS, each user works from copies of the project files in their personal work area directory. Because the SOS repository is a database, adding files to a project does not mean copying them to the directory that contains the project database. Instead, as the project administrator, you need to create the administrator’s SOS work area directory and then fill that directory with the original (version 1) files for the project. These files will include: • The existing design data that you want to manage in this project • Startup and configuration files for your design tools, so that each user gets copies of those files in their own work area directory. (Designers start both their design tools and the SOS software from their work area directory.) • Documentation files and any other files that you wish to manage with SOS Next, working in SOS, you add the files to the SOS project. The procedure for adding files is different for Virtuoso and non-Virtuoso data. See these topics: • “Creating a Work Area for a New Project” • “Adding New Virtuoso Cellviews to SOS Version Control” • “Adding New Files to SOS (Non-Virtuoso Data)”
Creating a Work Area for a New Project Although it is not a requirement, you will often want to create all of your users’ work area directories under the same parent directory on the project file server. Choose the location of the administrator’s work area directory with that consideration in mind. Here is an example directory structure: /server/ourchip/adsl_project/workareas bob cadmgr fred lynh First, you would create the cadmgr directory. Later, you would add work area directories for each user. Follow these guidelines to choose the location for work area directories: • Never use your home directory as a work area directory, because you cannot create new work area directories under another work area directory (so you would be limited to a single work area).
Setting Up SOS Servers and Projects 54 SOS Administration Guide
• You can create work area directories in subdirectories of users’ home directories, or you can follow the previous example and create them as subdirectories under a single project-specific directory. Follow these steps to create the administrator’s work area directory: 1 From the Linux command line, create a new directory. For example: % cd /server/ourchip/adsl_project/workareas % mkdir cadmgr % cd cadmgr 2 Copy any necessary startup files for your design tools into the new directory. See “Integrating SOS with Your CAD System” for best practices for Cadence Virtuoso and the other design tools that SOS supports. 3 Copy the initial set of design files into the administrator’s work area directory. The owner of the files must be the project administrator. 4 From that directory, enter the Linux command sos to start SOS. If the SOS Login dialog box appears, enter the Linux account name and password for this account (cadmgr in the example). 5 In the SOS window, choose File > New Workarea.
6 Set the options in the dialog box as follows: 1 Click the arrows next to the Server Name and Project Name fields, and choose the correct values.
Setting Up SOS Servers and Projects 55 SOS Administration Guide
2 For Workarea Dir, choose the current directory. 3 Leave Project Root blank, unless you want to create a work area that contains only one subdirectory of the project directory. 4 For Keep Files in Workarea as, choose Links to Smart Cache to minimize the amount of disk space consumed by your copies of the libraries. For information about the other choices, see the SOS User Guide. 5 If necessary, click to select the Branches and Snapshots options under Revision Search Order to populate the list of choices, and create the recommended revision search order in the box at the right. The default Revision Search Order (RSO) is main, which means to get the latest revisions. 7 Click OK to create your new work area. NOTE: The SOS software creates a .SOS directory in the work area. Never delete or modify any files in this directory; doing so may destroy the integrity of your work area.
Adding New Virtuoso Cellviews to SOS Version Control
NOTE: To add new Virtuoso cellviews to a project, you must work in Virtuoso. The SOS integration with Virtuoso automatically handles the relationships between the multiple files that comprise a cellview. To add files to a project with other design tools, you can work in either SOS or your design tools. If you are not using Virtuoso, see “Adding New Files to SOS (Non-Virtuoso Data)”. Follow these steps to add Virtuoso libraries, cellviews, and other files to SOS version control: 1 If you have not already added the cellviews to a Virtuoso library, add them now. 2 From the Library Manager, right-click a new, unmanaged cellview or library and choose Check In.
Setting Up SOS Servers and Projects 56 SOS Administration Guide
3 Enter a comment in the Description field and click OK.
Setting Up SOS Servers and Projects 57 SOS Administration Guide
Adding New Files to SOS (Non-Virtuoso Data) After you create the new work area, the Hierarchy tree in the SOS window updates to show the directory structure. Initially the files are “unmanaged”; that is, they are not under SOS version control. The next step is to add all of the files to the project. 1 In the Hierarchy tree, highlight the folder at the top (the “dot” folder in the picture).
2 Choose Select > All Unmanaged Files Below. Or, highlight the specific folders and files that you want to add to the project.
Setting Up SOS Servers and Projects 58 SOS Administration Guide
3 Select Tree > Create File/Dir.
To let SOS choose the appropriate default values for different types of data, do not choose a value for Revision control method. 4 Click Create All.
Setting Up SOS Servers and Projects 59 CHAPTER 4SERVER AND PROJECT ADMINISTRATION
This chapter explains how to administer SOS servers and SOS projects in the following sections. • Creating and Restoring Backups and Archives • Managing Projects and Servers • Using Shared Work Areas • SOSAdmin Command Line Quick Reference
Creating and Restoring Backups and Archives
Ensure that your daily and periodic backups include the server repository (.rep) directory. Also back up the user work area directories, to protect files that are unmanaged or checked out. SOS can recreate the cache directories from a restored backup, so it is not necessary to back up the caches. Follow these procedures to archive a project or restore a project from an archive. Do not use the native PostgreSQL backup features to back up SOS repositories.
Archiving a Project
1 From the Projects dialog box, with the server running, click Archive. The Archive Project dialog box opens.
Server and Project Administration 60 SOS Administration Guide
2 Enter a location for the exported data and click Archive in the dialog box.
3 Review the messages from SOS and PostgreSQL for any issues and click Dismiss to dismiss the dialog box. The Archive command generates three files for the project:
File Name Contents projectname_sosd_cfg.tgz Server configuration options, from the sosd.cfg. file projectname_sosd_DB.sql.gz PostgreSQL database file README_Export_projectname Log file from the export operation
Restoring an Archive
The archive files that you create with the Archive command contain all of the information needed to restore a project to the same SOS server or a different server. 1 Open the Projects dialog box for the destination SOS server. 2 If you are replacing the active project with an archived version, click Delete and delete the that project. 3 Click Restore. 4 Enter the project name and the path to the exported files and click Restore.
Server and Project Administration 61 SOS Administration Guide
5 Review the messages from SOS and PostgreSQL for any issues and click Dismiss to dismiss the dialog box.
Managing Projects and Servers
This section covers the following topics: • Shutting Down and Restarting Servers • Restarting and Messaging the Clients • Locking and Unlocking Projects • Moving Projects • Deleting Projects and Servers • Reducing Disk Space Usage Also see Working with Snapshots in the SOS User Guide.
Shutting Down and Restarting Servers
To shut down a server, highlight the server in the SOSAdmin window and click Shutdown. To restart the server, click Startup.
You can use the scripts start_all_servers.sh and stop_all_servers.sh in the $CLIOSOFT_DIR/bin directory to start or stop all of the servers.
Server and Project Administration 62 SOS Administration Guide Restarting and Messaging the Clients
You can use the Clients window to send messages to connected clients announcing shutdowns or maintenance. You can also use the Clients window to exit all running clients and force them to restart after a software upgrade. To open the Clients window, highlight the server in the SOSAdmin window and click Clients. Then select the clients that you want to manage, and click Send Msg or Exit Clients. Figure 6: Clients Window
NOTE: The Clients window is available to the server owner only, on the primary server only.
Server and Project Administration 63 SOS Administration Guide Locking and Unlocking Projects
Locking a project prevents users from adding, changing, or modifying project files. You should lock a project before performing important, archival backups. You may also want to lock a project when it is ready for tapeout. It is not necessary to lock a project before performing regular daily backups, or before taking snapshots.To lock a project, you must be an administrative user or the user who created the server. To lock or unlock a project: 1 In the SOSAdmin window, highlight the server and click Projects. Note the Lock Status of the projects:
2 In the Projects window, highlight the project and click Lock/Unlock.
3 Choose an option and click OK.
Server and Project Administration 64 SOS Administration Guide Moving Projects
Moving a project can involve either reassigning the project to a different server, physically moving the repository to a new path, or both. To reassign a project to another SOS server, use the Export and Import commands in the Projects dialog box to create a project archive and restore the archive to the new server. See “Creating and Restoring Backups and Archives”. To move the database and options files for a server and all of its projects to a new file system, follow these steps: 1 In the SOSAdmin window, highlight the server, click Shutdown, and click Yes to shut down the server. 2 Using operating system commands, move the .rep directory for the server to the new file system. 3 Click Edit and update the Repository Path to match the new location. Click OK to apply the changes. 4 Restart the server with the Startup command.
Deleting Projects and Servers
1 Shut down the server. 2 In the SOSAdmin window, highlight the server that you have shut down and click Projects. 3 Highlight the project and click Delete. 4 To also delete the server for the project, highlight the server in the SOSAdmin window and click Delete. Deleting a project in SOS removes the project definition from the server. To delete the project files, use operating system commands.
Reducing Disk Space Usage
By default, the cache stores the number of revisions of each object that you specified when you defined the cache server. If you use work areas with the Links to Smart Cache option, the cache might contain more than the specified number of revisions. Revisions get purged when the use count on a revision becomes zero. However, the use counts may not get set to zero when users manually delete their work areas. This situation can also occur if the file system for the cache becomes full. In either case, some older versions of files may remain on the cache server indefinitely. To reduce disk space usage, periodically clean up the cache for each project. Do this while the load on the cache server is low, because server performance will be slow during the cache cleanup operation. 1 While the server is running, in the SOSAdmin window, highlight the server that you have shut down and click Projects. 2 Highlight the project and click Cache Cleanup.
Server and Project Administration 65 SOS Administration Guide Using Shared Work Areas
Typically each user has their own private work area. However, more than one user may share a work area. This approach often works well for small groups working in close collaboration, such as a team of custom layout engineers. One key advantage of this approach is that everyone’s changes are immediately visible when a user saves a file. Shared work areas are supported with the Local Copies and Links to Smart Cache options in the New workarea dialog box:
Setting Up Shared Work Areas
To set up a shared work area: 1 If you want users to have full write access to the files, set the value of umask in your Linux environment to 000 or 00?. This ensures that the work area directory receives the correct permissions in the next step. 2 Create the work area directory and set the directory permissions so that the group name is inherited down through the directory hierarchy: mkdir work_area_directory_name chmod g+s work_area_directory_name These permission settings handle situations where users have a different default group. Newly-added files belong to the same group as the work area directory regardless of the group settings of the user who creates the files. 3 Create and populate the work area in SOS, as explained in “Creating a Work Area for a New Project”. 4 Move (cd) to the .SOS directory in the new work area. 5 Create a file named SHARED and open the file in a text editor. 6 Enter a keyword in the file to specify the access to grant to users of the shared work area: Table 7 Shared Work Area Access Keywords Keyword Type of Access for Users full Users have full read and write access to the files in the work area. They can perform all operations that the project options allow them to perform. UMASK setting required
Server and Project Administration 66 SOS Administration Guide
Table 7 Shared Work Area Access Keywords Keyword Type of Access for Users attr Users can change file attributes, tags, and labels. The owner of the work area must start the SOS client software. info Users can run queries on the work area to determine revision number and file status. The owner of the work area must start the SOS client software.
To use a shared work area with full access, users need to set their umask to 000 or 00? and then connect to the work area.
Limitations of Shared Work Areas
• Only one user can have the SOS GUI open. • All commands are executed by the one SOS process that is running in the work area. If multiple users are working at the same time, they may experience delays while their commands are queued. • Triggers executed in a shared work area will be executed as the first user who started the SOS process in the work area. • In a shared work area, project administrators can only discard another user’s checkouts by following the steps below: 1 Rename or delete the checked out object. (If the object is a package, rename or delete a file in the package). 2 Run this command: soscmd discardco -ED object_name
SOSAdmin Command Line Quick Reference
With no arguments, the sosadmin command opens the SOSAdmin graphical user interface. To use the command-line interface, add the arguments shown in the next table to the command line. Table 8 Arguments to the sosadmin Command Command Description clients List the clients that are connected to the server, send commands to clients, close connections to the clients, or exit the clients. create Create a new server. createproject Create a new project for a specified SOS server. getcfg Print the configuration file for a project. help Print help. info Get information about the SOS server. list List the defined servers. lockproject Place a lock on the repository. unlockproject Remove the lock on the repository.
Server and Project Administration 67 SOS Administration Guide
Table 8 Arguments to the sosadmin Command Command Description ping Test if the server is running. projects List projects managed by the server. purgeaudit Purges the audit_trail.log file for a project up to the specified time period. putcfg Install a new configuration file for a project. query Get work area and project-specific information without having a work area. readcfg Re-read the server configuration files. shell Run a program or script on the server. shutdown Shut down the server. startup Start the server. For more information on any command type: sosadmin help command_name For example, to list all of the defined servers: sosadmin list To check whether the server PRJ_SRV is running: sosadmin ping PRJ_SRV
Server and Project Administration 68 CHAPTER 5CONFIGURING PROJECTS WITH SOSD.CFG
This chapter explains how to configure SOS projects with the server configuration file, sosd.cfg, in the following sections. • Overview of the Server Configuration File • Working With Configuration Files • Setting Project Access Controls • Setting the Default Revision Search Order, Populate, Branch, and Work Area UMASK Options • Defining Reference Projects • Integrating SOS Projects with Change Request Tracking Systems
Configuring Projects with sosd.cfg 69 SOS Administration Guide Overview of the Server Configuration File
You can configure a project by editing the server configuration file, sosd.cfg. You can configure these options: • Access control for files and directories. See “Setting Project Access Controls”. • Definitions of groups of users, and their privileges. See “Groups”. • Default Revision Search Order, Populate, Branch, and user umask settings. See “Setting the Default Revision Search Order, Populate, Branch, and Work Area UMASK Options”. • Reference projects, which contain IP that project users may reference. See “Defining Reference Projects” • Integration of SOS with issue tracking systems. See “Integrating SOS Projects with Change Request Tracking Systems”.
Selecting the Server Configuration File to Read
The software only reads one copy of sosd.cfg, and sets all of the server configuration options based on the values in that one file: 1 If the project defaults file server_name.rep/project_name/setup/sosd.cfg exists, the software sets all of the server configuration options based on the values in this file. 2 Otherwise, the software looks for the site-specific configuration file $SOSD_CONFIG_DIR/sosd.cfg and, if it exists, sets all of the server configuration options based on the values in this file. 3 If neither of the previous files exists, the software reads the server configuration from the system default configuration file $CLIOSOFT_DIR/data/sosd.cfg.
Working With Configuration Files
This section applies to both the server configuration file sosd.cfg, described in this chapter, and the client configuration file sos.cfg, described in Chapter 6, “Customizing the SOS Client and the User Interface” on page 91. This section covers these topics: • Configuration File Locations • Configuration File Format • Customizing Configuration Files with SOSAdmin
Configuration File Locations
The server configuration file is named sosd.cfg. The client configuration file, described in Chapter 6, “Customizing the SOS Client and the User Interface” on page 91, is named sos.cfg. There are three locations for the server and client configuration files:
Configuring Projects with sosd.cfg 70 SOS Administration Guide
• The system default configuration files are in $CLIOSOFT_DIR/data. Do not modify these files. • Site-specific configuration files, if you create them, are located in the directory specified by $SOSD_CONFIG_DIR. This variable must be set before the primary server starts up. The primary server will read the sosd.cfg file from that directory and supply the sos.cfg file to the connected clients. Each site (location) may set a different value for $SOSD_CONFIG_DIR. You can choose to have that variable resolve to the same directory (on a shared file system) for all sites, or you can point the variable to a directory on a local file system that contains site-specific configuration files. The client software does not need read access to this directory, and only the server hosts (not the client systems) need to resolve this variable value. • Each project may also have its own project-specific sosd.cfg and sos.cfg files under server_name.rep/project_name/setup. Settings in the project configuration files override the system or site configuration files. NOTE: For Windows, the configuration files are named sosd.win.cfg and sos.win.cfg. Use the SOSAdmin application to edit and install configuration files, or to select a template for a configuration file. See “Working With Configuration Files”. You can also use SOSAdmin to retrieve templates for the configuration files.
Configuration File Format
Configuration files are case-sensitive. All keywords in sosd.cfg are in upper-case. All keywords in sos.cfg are lower-case. Configuration files may contain comments. A pair of forward slash or hyphen characters starts a comment, which continues to the end of the line: // This is a comment line. -- So is this. ADMIN larry, moe, curly; -- This comment begins in the middle of the line. Line breaks and white space have no significance, except in the shell command that follows the value, exec_before, and exec_after keywords in the client configuration file, sos.cfg.
Configuring Projects with sosd.cfg 71 SOS Administration Guide Configuration File Templates
You can download templates for server and client configuration files through the SOSAdmin application. This table lists the server configuration file templates. Table 9 Server Configuration File Templates Template Features functional_groups Examples of organizing users into functional groups such as analog design engineers, layout engineers, and RTL engineers. Examples of defining access permissions so that users can only modify the cells and files that their group owns. predefined_rso_and_populate Examples for setting the default Revision Search Order and specifying which directories to automatically populate for new work areas. redefine_member_privilege Example for specifying which commands a user may run. use_reference_projects Examples for specifying reference projects and their default Revision Search Order. use_trac_issue_tracking Example for configuring SOS to communicate with a TRAC issue-tracking system server.
This table lists the client configuration file templates. Table 10 Client Configuration File Templates Template Features add_exclude_patterns Example for adding new file suffix patterns to the exclude files list. email_notification Example of a trigger for generating email notifications when files are checked in, checked out, or have their tags modified. set_group_by_cadence_view_name Example of a trigger for setting the group ownership of newly-created or added DFII cellviews based on their view name.
Customizing Configuration Files with SOSAdmin
Any user with project administration privileges may customize the project configuration files. Follow these steps to perform these tasks with client or server configuration files: • Retrieve a copy of the current file for editing. • Create or update a file from a template. • Install a new or updated project configuration file. 1 Highlight the primary server in the SOSAdmin window and click Projects. The Projects window for the server opens.
Configuring Projects with sosd.cfg 72 SOS Administration Guide
2 Highlight the project in the Projects window and click Customize.
3 For Select config file, choose Server or Client. 4 Select your operating system and click Get. 5 Do one of the following: • To edit the existing configuration file, click Select. • To retrieve a copy of a template configuration file, choose Get a template, highlight a template, and click Select. 6 Specify a destination folder and file name. 7 Edit the file with a text editor. For information about the file format, see “Configuration File Format”. 8 From the Projects window, click Customize again. 9 Click Put, browse to the file that you edited, and click Open. 10Dismiss the Projects window. Changes to sos.cfg take effect when users restart their client software. NOTE: Project administrators with Linux write access to the project configuration files may edit the files directly instead of following the previous procedure. After editing the sosd.cfg file, highlight the server in the SOSAdmin window and click Reread Config to apply the changes. ClioSoft recommends that you not modify the system default configuration files in $CLIOSOFT_DIR/data. To override the system default configuration with site-specific defaults for all projects, follow these steps: 1 Create a directory in which to place the modified configuration file. 2 Follow the previous procedure to retrieve a template file, and copy the template to that directory. 3 Set the environment variable $SOSD_CONFIG_DIR for the account that runs the SOS servers to point to that directory. 4 Restart the servers.
Configuring Projects with sosd.cfg 73 SOS Administration Guide Setting Project Access Controls
Access controls let you specify which files a user can view or edit, and which commands they can run. By default, all users have read and write access to everything. Basic access control features that you can set up in the configuration files include: • Restricting access to a project to a specified list of hosts or IP subnets, through the SOSAdmin application. See “Host-Based Access Control in SOSAdmin”. • Assigning users to SOS groups, and restricting read and write access to the project files by referencing those groups in the global and project configuration files. See “Configuration File Example for Access Control” and the sections that follow. You can also configure SOS to implement more complex access control requirements like these examples • Do not allow users to check in files after midnight. • Only allow the project lead to run certain commands. • Send email to the project lead if someone checks out certain files. These more complex access controls use triggers in the client configuration file to execute a Linux script on the client system. When users attempt to perform an operation, such as checking out a file, the script is triggered and the operation may be allowed, blocked, or modified. You can set up triggers to run before or after each SOS operation. For more information, see “Using Triggers”. To change the access controls on existing files, use the Modify Attrs > Source File/ Dir command in the SOS application.
Configuring Projects with sosd.cfg 74 SOS Administration Guide Host-Based Access Control in SOSAdmin
You can use the SOSAdmin application to specify host or IP address-based access control rules. These rules let you grant or deny access to the server based on the host name or IP address. Use the Access Control box in the Edit Server Configuration Dialog Box to set the rules.
The syntax for the rules is similar to the syntax for the xhost command in the X Windows system. A plus sign (+) grants access and a minus sign (-) denies access. You can specify host names, IP addresses, or subnet ranges (with wildcards). The default rule is simply +, and all hosts have access. In the previous example, all hosts have access except for training and demo.cliosoft.com. The next example denies access to all hosts by default, and then specifies the allowed IP addresses: - +128.64.139.* -128.64.139.100 -training.cliosoft.com The rules above specify: 1 Deny access to all hosts. 2 Grant access to all hosts on the subnet 128.64.139. 3 Deny access to the IP address 128.64.139.100 and the host training.cliosoft.com.
Configuring Projects with sosd.cfg 75 SOS Administration Guide Configuration File Example for Access Control
Several keywords in the configuration file let you specify which users have access to which files, and which commands they may run. See the sections following this example for details about the keywords: // sosd.cfg ======// OPEN_WORLD yes; -- Define world as all users who can access the server -- If not specified project defaults to 'yes'. // OPEN_WORLD no; -- Define world as only users declared as admins, members, -- guests, or some other role in this project configuration file.
-- **** Global definitions (BEGIN) **** -- ADMIN edaman_us, edaman_jp; MEMBER mikef, aartg, wallyr; GUEST rajeevm;
-- Define VERIF_ENGR as a role that only allows labelling revs ROLE VERIF_ENGR { COMMAND definetag, tag, snapshot; } -- Verfication engineers for the entire project VERIF_ENGR johnc, richarg;
-- Default Access Control for the project. ACL { READ world; -- can be owner, group or world WRITE group; -- can be owner, group or world MODIFY_ACL yes; -- can be yes or no } -- **** Global definitions (END) **** --
-- **** Group definitions (BEGIN) **** -- -- Group "design" definitions follow GROUP design { -- Members of group "design". MEMBER stevej, billg; -- Verification engineers for this group VERIF_ENGR narayanm; } -- Group "layout" definitions follow GROUP layout {
Configuring Projects with sosd.cfg 76 SOS Administration Guide
-- Members of group "layout". MEMBER picasso, vangogh; -- Verification engineers for this group VERIF_ENGR renoir; -- Define the default Access Control for 'layout' ACL { READ world; -- can be owner, group or world WRITE owner; -- can be owner, group or world MODIFY_ACL yes; -- can be yes or no } } -- **** Group definitions (END) **** -- -- **** User specific definitions (BEGIN) **** -- USER mikef { -- Define the default group for 'mikef' to 'layout' -- 'layout' must be defined before this. DEFAULT_GROUP layout; }
USER wallyr { -- Define the default group for 'wallyr' to 'all_my_groups' -- All groups that wallyr is a member of will get equal rights -- over files owned by wallyr and group set to all_my_groups DEFAULT_GROUP all_my_groups; } -- **** Default Group definitions (END) **** -- Global and Default Access Controls
Use the OPEN_WORLD keyword to restrict access to a project (or to all projects) to only the users specified in each individual project configuration file: OPEN_WORLD no; The default is yes. Use the default Access Control List (ACL block) to further define global permissions. ACL definitions in sosd.cfg set the access controls for newly-created files that users check in to SOS. Changing these definitions does not affect the access controls of existing files. Every object in the project has a READ access and WRITE access property. • READ access lets designers populate their work area with the files and run commands such as history or diff that do not require write access. • WRITE access lets designers check out and modify project files with SOS commands and update metadata with commands such as tag, snapshot, and modattr.
Configuring Projects with sosd.cfg 77 SOS Administration Guide
• MODIFY_ACL controls whether users can modify the access controls on files and directories that they create. The default access controls are: OPEN_WORLD yes; ACL { READ world; -- can be owner, group or world WRITE world; -- can be owner, group or world MODIFY_ACL yes; -- can be yes or no, must be yes for Virtuoso } NOTE: The world setting in the configuration file corresponds to the All option in the SOS graphical user interface. If a file has READ and WRITE set to world, and OPEN_WORLD is yes, anyone in your organization can populate their work area with the file, check it out, modify it, and check it back in. If OPEN_WORLD is set to no, only the user names listed in sosd.cfg can perform those operations; other users in the company cannot populate their work areas with even a read-only copy of the file.
Access Control Best Practices for Virtuoso Data
A Virtuoso cell has subdirectories for each view. Typically, designers create the symbol and schematic views first, and later the layout engineer creates the layout view. Administrators often define DESIGN and LAYOUT groups and set the ACL permissions to restrict write permission to group members only. However, members of both groups need write permission for the cell directories that contain the views. Otherwise, because the designers created the directory, layout engineers will not be able to write the layout view into the directory. To avoid this problem, the SOS integration with Virtuoso automatically changes the permissions of the cell and library directories to be writable for world. Setting MODIFY_ACL to no blocks this feature of the Virtuoso integration. Therefore, if you do have separate DESIGN and LAYOUT groups, be sure to set MODIFY_ACL to yes.
Roles
Roles control a user’s access permissions and optionally limit the commands that the user can run. You assign users to roles by specifying lists of users for each role. In the project configuration file, you can give a user the same role in all groups for a project, or you can give a particular user different roles in different groups. The predefined roles are:
Role Description and Default Command Privileges ADMIN ADMIN users have full control. They can read, write, delete, and change the ownership of any file regardless of its permissions. MEMBER MEMBER users can read and write files, unless the individual file has more restrictive permissions. GUEST GUEST users can read data unless the individual file has more restrictive permissions, but they cannot make changes.
Configuring Projects with sosd.cfg 78 SOS Administration Guide
For example: ADMIN edaman_us, edaman_jp; MEMBER gwong, dfisk, gsingh; GUEST sjones; In sosd.cfg, you can override the default command privileges listed in the previous table for the default roles. You can also define new roles and specify which commands users in that role may run, as in this example: ROLE VERIF_ENGR { COMMAND definetag, tag, snapshot; } In this example, users with the role VERIF_ENGR can only run the three commands specified; they cannot create or modify files. To assign a user to a user-defined role, use this syntax: ROLE_NAME user1, user2, ...; For example: VERIF_ENGR sally, phuong, ricardo; Commands that May Be Assigned to Roles The table lists the keywords that correspond to the SOS commands and options that you may allow for roles. For example, the co-C keyword represents the co command with the -C option. Only the command and option combinations in the table are supported as keywords. Column 3 lists the commands that by default are only available to ADMIN users. You can use roles to allow selected regular users to run selected administrative commands. For more information about these commands, type soscmd help to see the online help. Table 11 SOS Commands Available for User-Defined Roles Command Enabled Only for Keywords Description the Admin Role addreference Add objects from reference SOS projects No ci Check in No co Check out No co-C Concurrent check out No co-b Check out on a branch No create Create No definetag Define a tag No definebranch Define a branch No delete Delete No delete-F Force delete Yes deleterev Delete a revision Yes discardco Discard/cancel check out No discardco-ED Discard check out by all Yes modifyattrs Modify attributes No move Move No
Configuring Projects with sosd.cfg 79 SOS Administration Guide
Table 11 SOS Commands Available for User-Defined Roles (continued) Command Enabled Only for Keywords Description the Admin Role populate Populate the specified directory No rename Rename a object No retirebranch Retire a branch Yes retirebranch-A Activate a retired branch Yes retiresnapshot Retire a snapshot Yes retiresnapshot-A Activate a retired snapshot Yes retiretag Retire a tag Yes retiretag-A Activate a retired tag Yes snapshot Assign a snapshot No snapshot-F Overwrite existing Snapshot Yes tag Assign a tag No tag-B Undo a tag assignment No termbranch Terminate a branch No termbranch-unT Reopen a branch Yes override- Grants administrator privileges to any Yes permission user with this role. This means that the user may change file ownership or group assignments, and perform other administrative tasks. These are the privileges granted to the ADMIN role by default. You can use override- permission to assign administrative privileges to other roles. This is the only command keyword that does not correspond to an SOS command.
Groups
You control the permissions on files that users create by assigning the users to groups. Each group typically contains users who work on related parts of the design. For example, you might define separate groups for design engineers and layout engineers. Users may belong to one or more groups, and should be assigned to a default group. NOTE: Linux group permissions do not affect SOS access control. SOS user groups are similar to Linux user permission groups, but you define the groups in the configuration file. The GROUP keyword begins a group definition. The syntax is: GROUP groupname { MEMBER user1, user2, ...; USER_DEFINED_ROLE user3, user4, ...; ACL { READ owner | group | world;
Configuring Projects with sosd.cfg 80 SOS Administration Guide
WRITE owner | group | world; MODIFY_ACL yes | no; } } where groupname is the name you assign to the group and userN represents a Linux or Windows user name. The ACL block is optional if you want the group to inherit the default Access Control List settings. If you have defined additional roles, you can specify which users have that role for the group. These settings control the default values that appear when users create new files or directories under SOS revision control.The next figure shows the default access controls for an example user engr who belongs to the group schematic. Any user can populate the designs that engr adds to the project, but only other members of the schematic group may modify those designs. Figure 7: Access Control Options
Users can override the default access control values when they add files to revision control, unless MODIFY_ACL for the group that the user selected (schematic in the previous figure) is set to no. Likewise, users can modify file and directory access controls with the Modify Attrs > Source File/Dir command in the SOS application unless MODIFY_ACL for the selected group is set to no.
Default Groups for Individual Users When a user creates a file, that file is assigned to the user’s default group (unless the user overrides that choice and picks another group), which in turn determines the access controls on the file. You assign users to a default group with the USER keyword in the sosd.cfg file. The syntax is: USER username { DEFAULT_GROUP groupname | all_my_groups; } where username is a Linux or Windows user name and groupname is a group defined earlier in the configuration file. If you specify a groupname, files that the user creates get assigned to that group. If you specify all_my_groups, files that the user creates receive the most restrictive permissions for all of the groups to which the user belongs. By default, if there is no USER entry for a user, that user’s default group is the first group in the configuration file in which the user appears. Users can override their default group assignment in two ways: • By specifying the group in the Project Preferences dialog box (File > Project Preferences in the SOS client). This setting takes precedence during the current SOS session.
Configuring Projects with sosd.cfg 81 SOS Administration Guide
• By setting the $SOS_DEFAULT_GROUP environment variable. If there is only one project, set the value to match the group name. If there are also reference projects, users can specify default groups for each project by using this format for the variable value: group@proj1:group@proj2:group@proj3. For example: setenv SOS_DEFAULT_GROUP schematic@demo:design@reference_libs:consumer@ip_catalog Example: Overlapping Design and Layout Groups Suppose that one set of Virtuoso users creates layouts and a second set of users creates symbols and schematics, with a few engineers belonging to both groups. Sometimes administrators need to check in libraries. The administrators want to ensure that only users from the layout group can edit layouts, and that only users from the design group can edit schematics and symbols. Here is how you would define these groups in sosd.cfg: -- Are users outside the config file allowed to access this project? -- OPEN_WORLD yes | no
-- List of administrators for the project ADMIN admin1, admin2;
-- Define the ACLs that must be used for new objects. -- Read means users can populate the workarea with files. -- Write involves all other action such as CO, CI, Tag etc. ACL {
READ world; WRITE group; }
-- Define groups and define members of each group -- Members belonging to both groups can edit objects from -- both groups.
GROUP design { MEMBER userl, user2; }
GROUP layout { MEMBER user2, user3, user4; } To ensure that files that these users create get assigned to the correct group, and therefore have the correct permissions, you could use the create command in a trigger to set the Group attribute.
Configuring Projects with sosd.cfg 82 SOS Administration Guide Managing umask and Linux Permissions
This section discusses the Linux permissions on SOS files, umask settings, and related security issues. Note that SOS ignores users’ umask settings for files in the repository and cache directories.
SOS Repository Files The source files in the repository have Linux read and write access for the administrator who started the server only. Do not change those Linux permissions.
SOS Cache Files By default, files in the SOS cache are readable by anyone, including users who do not belong to the admin group that created the servers, because the default umask is 022. All users may make links to the cache. Although the default directory permissions prevent users outside the group from listing the directory contents, it is possible for a malicious user to guess the names and access the files. To restrict access to Linux permission group members, set the umask to 027 by setting this environment variable before you start up the cache server: setenv SOSD_USE_UMASK 027 If you set this variable, SOS ignores the umask setting of the administrator who started up the server.
User Work Areas In user work areas, files get created with each user’s umask settings. For security, use values of 027 (group read access) or 077 (user access only).
Setting the Default Revision Search Order, Populate, Branch, and Work Area UMASK Options
You can set group, project, and user-level defaults in the server configuration file (sosd.cfg) for: • The Revision Search Order (RSO) • Which directories to populate in new work areas • Which branch to use for checkouts • The umask value for files and directories in user work areas
Revision Search Order
Use the RSO keyword to set the default Revision Search Order: RSO { DEFAULT "name1", "name2", ...; MODIFY yes | no; }
Configuring Projects with sosd.cfg 83 SOS Administration Guide
where nameN is a tag, snapshot, or branch name and MODIFY controls whether the user may override the default revision search order in their own work area. For example: RSO { DEFAULT "verified", "main"; MODIFY yes; } Directories to Populate
Use the POPULATE keyword to automatically populate specified directories when a user creates a new work area and selects the Populate paths predefined in server configuration option: POPULATE "directory_name", "directory_name2", ...; For example: POPULATE "./cds", "./docs", "specs"; NOTE: The Populate paths predefined in server configuration option is selected by default when you run the New Workarea command.
Branch Options for Files and Directories
Use the BRANCH keyword to set the default branch for checkouts: BRANCH { DEFAULT branch_name; DIRECTORY yes | no; MODIFY yes | no; } where branch_name is the name of the branch, DIRECTORY controls whether directories are branched when users add, delete, move, or rename a file, and MODIFY controls whether users can change the default branch in their own work area. For example: BRANCH { DEFAULT low_power; DIRECTORY no; MODIFY yes; } SOS manages directories as files. Directories are checked out and checked in to create new versions of the directory when you add, delete, or rename an object in the directory. Moving a file deletes it from one directory and adds the file to another directory. If you elect to branch directories (DIRECTORY yes;), when you add or delete files while working on a branch, the change will not be visible on the main branch.
Configuring Projects with sosd.cfg 84 SOS Administration Guide
Typically you do want those changes to be visible on the main branch, so the default and recommended value for DIRECTORY is no. Be aware that SOS does not have a graphical utility for managing and representing merging of branched directories, to handle situations in which changes have been made to a directory in both a branch and the main branch.
UMASK Settings for Work Areas
Use the UMASK keyword to set the umask for work areas: UMASK value; where value is the numeric umask such as 022 or 027. The SOS client uses this umask to assign permissions to files and directories in the work area, overriding the user’s Linux umask value. This setting changes the umask for the SOS client only. Other programs will still use the user’s Linux umask setting. For example, if a user creates a new cellview in Virtuoso, the files in the new cellview get created with the user’s default umask setting, not the UMASK keyword value in the sosd.cfg file.
Defining Reference Projects
SOS projects can access files in other projects if you add the projects to the reference project map. Reference projects might include other active projects, third-party IP libraries, and your own organization’s IP libraries. Reference projects may be managed by another server at another site. Typically a designer only has read access to data in other projects, but you can set up less restrictive access controls. Projects may reference everything in a reference project, a single directory out of several, or perhaps reference only a single file or package. Users can identify reference project folders by the icon in the SOS window. Files have the icon For example, in the project at the right, the analog_parts and basic libraries are reference libraries.
Setting Up Projects for Referencing
To set up reference mapping among projects, you work with both the SOSAdmin application and the project server configuration (sosd.cfg) files.
Configuring Projects with sosd.cfg 85 SOS Administration Guide
1 From the SOSAdmin window, click Project Map. The Project -> Server Mapping dialog box opens.
The example shows two reference projects, both hosted on a server named REFERENCE. 2 Do one of the following: • To add a single project to the reference map, click Add and choose the server and project from the Add Project Map dialog box. • To add all projects to the reference map, click Automatic. You can later delete individual projects with the Delete command. Repeat this step at all sites that will use the reference project. Updates will fail at sites that skip this step. 3 For each project that will make use of data in a reference project, edit the project server configuration (sosd.cfg) file and add REFERENCE_PROJECT blocks for each project that will be referenced. See “Syntax of the REFERENCE_PROJECT Block”, next. 4 For each project with an updated configuration file, highlight the server in SOSAdmin and click Reread Config.
Adding References
1 Launch the SOS application and connect to the project work area. 2 In the Hierarchy tree, highlight the directory where you want to create a reference to a file or folder in the external project.
Configuring Projects with sosd.cfg 86 SOS Administration Guide
3 Select Tree > Add Reference.
4 Choose the reference project from the Project list and click Browse to choose a file or directory in the reference project. 5 Optionally, click Browse opposite Use Object RSO and select one or more tags, branches, or snapshots to identify the desired revision of the referenced file or directory. Otherwise, leave Use default project RSO selected, and SOS will use your current RSO to select a revision of the reference file or directory. To update the reference-specific RSO later, use the Tree > Set Node RSO command. See the next section for details. 6 Optionally, specify an Alias to use within the current project for the referenced directory or file. Click Ok. Repeat the Add Reference command for each reference directory or file.
Configuring Projects with sosd.cfg 87 SOS Administration Guide Specifying the RSO for a Reference
When you create a reference, or afterwards with the Tree > Set Node RSO command, you can specify the RSO for the reference. Specifying an RSO creates a new revision of the parent directory. If you roll back the project to a previous snapshot, you select the revision of the reference object that was used in that snapshot. To set or update the RSO for a reference: 1 Select Tree > Set Node RSO.
2 Do one of the following: • Select Use Object RSO when you want to override the project Revision Search Order for the referenced object and its children. Select one or more tags, branches, or snapshots to identify a version. • Select Use default project RSO to choose the reference object version based on the default project Revision Search Order, instead of using a custom RSO for this particular reference.
Syntax of the REFERENCE_PROJECT Block
The REFERENCE_PROJECT blocks in a project server configuration file specify whether project users can change files in the reference project and which versions of files to retrieve from the reference project. Create a REFERENCE_PROJECT block for every project that the current project needs to reference. (A project may contain one or more libraries.) Be sure to reread the configuration after you make the changes. The syntax is: REFERENCE_PROJECT SOS_PROJECT_NAME {
Configuring Projects with sosd.cfg 88 SOS Administration Guide
RSO { DEFAULT "list_of_labels"; MODIFY yes | no; } MODIFY yes | no | attr; BRANCH { DEFAULT BRANCH_NAME; DIRECTORY yes | no; MODIFY yes | no; } } where: • sos_project_name is the name of the reference project. •For RSO: • DEFAULT list_of_labels is a comma-separated list of tags, branches, and snapshots to define the revision search order. • MODIFY controls whether users may change this default RSO. • MODIFY at the top-level of the block controls whether users can check objects in and out of the project, or whether they can only change attributes like tags and snapshots. This is useful when a user might be a member of both the design project and the reference project, to prevent the user from accidentally modifying a reference object while working on the primary project. •For BRANCH: • branch_name is a branch name from the reference project, into which checked-out items will be placed. • DIRECTORY controls whether to branch checked-out directories. • MODIFY controls whether users can change the branch name. You can omit any of the three sections to accept the default settings. This example defines a read-only reference project: REFERENCE_PROJECT reference_IP_libs { MODIFY no; RSO { DEFAULT "Release_A1"; MODIFY no; } } The next example defines an editable reference project: REFERENCE_PROJECT reference_IP_libs { MODIFY yes; RSO { DEFAULT "low_power", "Release_A1";
Configuring Projects with sosd.cfg 89 SOS Administration Guide
MODIFY yes; } BRANCH { DEFAULT "low_power"; DIRECTORY yes; MODIFY no; } }
Integrating SOS Projects with Change Request Tracking Systems
SOS supports integration with third-party change request tracking software. Users can associate operations like file check-ins with issue IDs in the tracking software.
Supported Tracking Systems
SOS supports the following issue tracking and project management systems: • Bugzilla 3.4 and later See the README file under $CLIOSOFT_DIR/cr_scripts/bugzilla. For more information on Bugzilla, see http://www.bugzilla.org/. •TRAC See the README file under $CLIOSOFT_DIR/cr_scripts/trac. For more information on TRAC, see http://trac.edgewall.org/. • Fusion Forge See the README file under $CLIOSOFT_DIR/cr_scripts/fforge/. For more information on Fusion Forge, see http://www.fusionforge.org/. • Atlassian JIRA The files and documentation for the JIRA integration with SOS are available at http://cliosoft.zendesk.com/entries/24847747-SOS-integration-with-jira
Configuring Projects with sosd.cfg 90 CHAPTER 6CUSTOMIZING THE SOS CLIENT AND THE USER INTERFACE
This chapter explains how to customize the SOS client software and the SOS user interface with the sos.cfg configuration file, Sos.ad X resource file, and .sosrc startup files, and with environment variables, in the following sections: • About the sos.cfg File • About Attributes and Triggers • Defining and Using Attributes • Using Triggers • Specifying Exclude, Cleanup, and Local Copy Files • Setting UDMA Rules for Automatic Cellview Packaging • Using X Resources • Specifying SOS Tcl Commands in .sosrc Also see • “Working With Configuration Files”, which contains information about both the server and the client configuration files. • “Setting Preferences” in the SOS User Guide.
Customizing the SOS Client and the User Interface 91 SOS Administration Guide About the sos.cfg File
Unlike how SOS processes the server configuration file sosd.cfg, for the client configuration file sos.cfg, each individual trigger and option gets set to the last value that the software encounters while reading the configuration files. The software reads one or more sos.cfg files in this order: 1 First, SOS reads the settings from the system default file, $CLIOSOFT_DIR/data/sos.cfg. Settings that are commented out in the system default file reflect the built-in default values for the software. 2 Next, SOS reads the site-specific configuration file $SOSD_CONFIG_DIR/sos.cfg (if it exists) and updates the configuration with any changes. The $SOSD_CONFIG_DIR/sos.cfg file gets transferred to all clients, including clients at remote sites. Systems running the client software do not need to set $SOSD_CONFIG_DIR. 3 Finally, SOS reads the project-specific configuration file server_name.rep/project_name/setup/sos.cfg (if it exists) and updates the configuration with any changes. The .sosrc file and the X resource files are handled the same way: the software may read several copies of the file, and the last value that the software reads takes precedence. Also see “Configuration File Locations”. NOTE: The following settings in sos.cfg are additive (the software adds all of the values in all of the configuration files to the list of values): • exclude • cleanup • localcopy On Windows, the client configuration file is named sos.win.cfg.
About Attributes and Triggers
An attribute is information about an object that is under SOS revision control. A trigger defines a set of Linux commands and/or scripts to be executed and the attributes to be recorded when you perform an SOS operation like checking in a file.
Customizing the SOS Client and the User Interface 92 SOS Administration Guide Defining and Using Attributes
An attribute is information associated with an object, or with a particular revision of an object. For example, you may want to keep track of the number of lines in a file, the amount of time the design team spent on a fix, the number of changes that the team made, or the number of nets or component. Attributes let you record this information in the project. There are two types of attributes: • Revision attributes have values for each revision of an object. Some examples of default revision attributes are Log, CheckInTime, CheckOutTime, and CheckedOutBy. Project administrators can add custom revision attributes by editing the sos.cfg file. • Object attributes do not change their values with each revision of an object. They carry information such as access permissions and ownership. Some examples of object attributes are WriteAccess, ReadAccess, Owner, and Group. Users cannot create custom object attributes, but you can set and change the values of the three predefined object attributes User1, User2, and User3. You can calculate attribute values by running scripts or by prompting for user input. Use the Project > Plot Attributes command to generate plots of attribute values over time.
Declaring Attributes
You declare attributes in the project configuration file, project_directory/setup/sos.cfg. The syntax for declaring an attribute is: attribute attribute_name { type type_name; label label_name; mode attribute_category; display {yes | no}; export {yes | no}; prompt {yes | no}; value shell_command required {yes | no}; }
Customizing the SOS Client and the User Interface 93 SOS Administration Guide
Table 12 Attribute Declaration Fields Field Description and Default type The data type of the attribute value. The legal types are: • string (the default type) • text (a multi-line string) • integer • real • boolean • A user-defined enumerated type or a dynamically- generated list label A string used as the attribute name in the SOS window. This string is used to label the column if the attribute is displayed in the window. By default, attribute_name is used as the label. mode The attribute category. The categories are: • set: These attributes do not have integer values, so they cannot be plotted. The value of such attributes have no relationship between each version of the same file. Attributes like change_summary and chkout_path are in this category. This is the default value. • status: These attributes must have a numeric value, so the type must be integer, real, boolean, or enum. You can plot these attributes over time as line graphs. They provide status information about each revision of a file. Attributes like line_count and size are in this category. • cumulative: Attributes of this category, if plotted over time, are shown as bar charts (histograms). For example, a bar chart might show the number of changes in a certain time interval, or the number of bugs fixed for a set of files over a specified period of time. An attribute like num_changes is in this category. display Controls whether the attribute may be displayed in the SOS user interface by setting the appropriate X resources. Choose yes to make the attribute available to display. Choose no otherwise. The default is yes. Attributes of type text cannot be displayed in the SOS window, so choose string or define an enumerated type if you need to display a string of text in the window. Choose yes in typical cases or choose no if you want to minimize the amount of memory that SOS uses, and you don’t want to display it.
Customizing the SOS Client and the User Interface 94 SOS Administration Guide
Table 12 Attribute Declaration Fields Field Description and Default export Controls whether to export the attribute as an environment variable in SOS shells. Choose yes to make the attribute available as an environment variable. Choose no otherwise. The default is yes. For example, since the line_count attribute is exported, the environment variable SOS_line_count gives you access to the attribute value in scripts. prompt Controls whether to prompt the user to enter the attribute value whenever a trigger specifies the attribute. Choose yes to prompt for a value. Choose no otherwise. The default is no. You can override this choice inside a trigger definition. For example, if a trigger for the check in command specifies an attribute value, the Check In dialog box will contain a field for specifying the value. value The shell commands to execute to get the value of the attribute. All of the text following the keyword value is passed to /bin/sh, and the value of stdout becomes the attribute value. Use the backslash ( \ ) to continue the shell command to the next line. You can override the value of value in a trigger definition. If you set prompt to yes and also set value, SOS uses the calculated value if the user does not specify a value on the command line. required Controls whether users are required to enter a value for the attribute. Choose yes to make the value required. The default is no. You can override this choice inside a trigger definition. For example, if you use an issue tracking system with SOS, you might make the issue ID attribute required.
NOTE: By convention, names for predefined attributes begin with an uppercase letter. User-defined attributes (including attributes that ClioSoft has defined in the global sos.cfg file) should begin with a lowercase letter. You can also declare enumerated types for attributes. The syntax is: enum type_name { value1, [value2], .... } Each enumerated value must be a string without any embedded spaces or special characters. For example, you could define an attribute called fix_for to track which customer needs a particular fix. Here is how you would define the type and the attribute itself: -- List of customers enum customers { All,
Customizing the SOS Client and the User Interface 95 SOS Administration Guide
Larry, Moe, Curly } -- Fix for a specific customer attribute fix_for { type customers; label "Fix for Customer"; mode set; value echo "All" display yes; export yes; prompt yes; } Both enum and list attributes let the user pick a value from a limited set of choices. An enum is a predefined list of items whose values cannot contain spaces. A list is dynamically generated when, for example, a program or script opens the Check In dialog box, and the values may contain spaces. Here is an example for a list attribute: list issue_type { value $CLIOSOFT_DIR/scripts/cr_list_my_issues.tcl } attribute issue_id { type issue_type; label "IssueID"; mode set; export yes; display yes; prompt yes; } The default client configuration file $CLIOSOFT_DIR/data/sos.cfg contains examples of enumerated attribute types. Here is an example of an attribute with a required value: -- Trac Issue ID attribute attribute issue_id { type issue_type; label "Trac Issue ID"; mode set; export yes; display yes; prompt yes; required yes; }
Customizing the SOS Client and the User Interface 96 SOS Administration Guide Monitoring Status and Progress with Attributes and Triggers
You can define attributes to track the progress of your project. You can record an attribute automatically by having the check in command trigger a script to calculate the attribute value. For example, the attributes defined in the default configuration file automatically record file size, line count, and number of changes when a file is checked in. You can also configure SOS to prompt you for the value of an attribute. For example, you may want to record the amount of time spent on each file. You can then plot these attributes over time for any set of files with the Project > Plot Attributes command in the SOS window. These plots can give you some concrete measure of your progress. This data can also provide you with useful insight for planning future projects.
Predefined Attributes
The attributes listed in the table are predefined for all objects. Attributes beginning with upper-case letters and using medial capitals (for example, CheckInTime) are predefined in the SOS software. By convention, attributes that begin with lower-case letters are defined in the default client configuration file, $CLIOSOFT_DIR/data/sos.cfg. Table 13 Predefined Attributes Attribute Value and Description change_summary A one-line summary of the changes made to a revision of the file. SOS uses the first line of the Log attribute as the value. CheckedInBy The login id of the user who checked in this revision. Nobody can change this value. CheckedOutBy The login ID of the person who has this revision of the file checked out. If the file is not checked out, this attribute has no value. CheckInTime The time when the selected revision was last checked in. CheckInTime The time when this revision of the file was checked in. CheckOutTime The time when the file was checked out. If the file is not checked out, this attribute has no value. Checksum Checksum of the object. For packages, the value is the checksum of all of the package components. chkout_path The pathname to the location where a file was checked out. By default, this attribute is automatically recorded when a user checks out a file. Description The description of the file that was entered when the file was first created. This is a text type attribute, so it cannot be displayed in the SOS user interface. Group The SOS group to which the file belongs. Log The log file comment entered for the current or selected version of the file. You enter this comment when you check in a file. This is a text type attribute, so it cannot be displayed in the SOS user interface.
Customizing the SOS Client and the User Interface 97 SOS Administration Guide
Table 13 Predefined Attributes (continued) Attribute Value and Description MatchedLabel The label in your revision search order which caused this revision to be selected. For example, if the revision search order is 'gold, main’ then if any revision of the file has the tag gold that revision will be selected and the MatchedLabel attribute of the file will have the value gold. If none of the revisions has a tag gold, the latest revision of the file will be selected and the MatchedLabel attribute will have the value main. PackageList A list of components that make up the version of the package object. PackageTypeList The type of each object (file or symbolic link) that corresponds to the components in PackageList. Owner The login ID of the owner of the file. ReadAccess The read access permissions for the file. The possible values are: • user: only the owner has access. • group: all administrators and all members of the group or groups to which the object belongs have access. • world: everyone has access. Reference For reference objects, the list of projects that reference the selected object. Revision The revision number of the file that is currently in your work area. SOS_RCPgm The revision control method being used for the selected file. If the value is blank, the revision control method is RCS. Trigger The trigger to be activated when an SOS command is executed on this file. Version The internal RCS-style version number of each version, the SOS branch name, and the SOS version of the object. WriteAccess The write access permissions for the file. The values are the same as for ReadAccess. Writable If this attribute is set to Yes, the object will always be writable in the work area. Usually this attribute is set by the SOS integration with your design tools.
You can access these attributes in triggers as environment variables. To construct the environment variable name, prepend SOS_ to the attribute name. For more information about environment variables, see “Using Environment Variables in Actions”. To see a list of all of the available SOS environment variables, use the soscmd command: 1 (Optional) From your work area directory, select a particular file or directory. For example: soscmd select rtl/testbench.v 2 Enter this command: soscmd shell env | sort | grep SOS
Customizing the SOS Client and the User Interface 98 SOS Administration Guide Using Triggers
Triggers let you extend the functionality of most SOS operations, such as checking files in or out. Triggers let you associate pre- and post-command actions with SOS commands. You can assign triggers to files, directories, and other objects. Triggers specify one or more of the following instructions: • The commands or scripts to execute before an action (such as checking out the file). • The commands or scripts to execute after the action. • The attributes to record, for check in and check out actions only. (Setting attributes on check out actions is not common.) If you specify an attribute when you check in a file, the attribute value gets associated with the revision of the file that you check in. If you specify an attribute when you check out a file, that attribute value is associated with the temporary, checked-out revision of the file. On Linux clients, commands for triggers run in a Bourne shell. On Windows, they run as Windows commands. For example, triggers can: • Send email notifications when someone checks in a critical file. • Set access controls for operations. • Automatically run lint or other commands before checking in a file. • Record the number of changes made in each revision. • Record the number_of_nets attribute when a Verilog file is checked in. NOTE: You can execute shell commands in triggers. You cannot execute SOS command- line commands in triggers, unless you run them in the background. For that reason, SOS command-line commands are typically only used in post-operation actions. Most but not all commands can be extended through a trigger. See “Commands that Accept Actions”.
Assigning Triggers to Files or Directories
You can assign a custom trigger to a file or directory when you add it to SOS with the Tree > Create command. To view or change the trigger for a file or directory, use the
Customizing the SOS Client and the User Interface 99 SOS Administration Guide
command Modify Attrs > Source File/Dir. In the next example, the netif.v file has the trigger demo_file_trigger.
Default Triggers
SOS defines default triggers for each type of object. If you do not explicitly set a trigger when you create a new object, SOS applies the appropriate default trigger whenever you perform an operation on the object (check in, check out, and so forth). For example, all of the default triggers set the chkout_path attribute when you check out an object. Table 14 lists the default triggers. Table 14 Default Triggers for Objects Object Type Default Trigger Description Files dflt_file_trigger This trigger applies to all managed files. Directories dflt_dir_trigger This trigger applies to all managed directories. Packages dflt_package_trigger This trigger applies to all managed composite objects (packages of related files). Symbolic Links dflt_symlink_trigger This trigger applies to all managed symbolic links.
Customizing the SOS Client and the User Interface 100 SOS Administration Guide
Table 14 Default Triggers for Objects (continued) Object Type Default Trigger Description Symbolic Links symlink_trigger This trigger provides backwards (created in SOS compatibility with data created using 6.10 and earlier) this trigger in SOS release 6.10 and earlier. Do not use this trigger to check in new objects in later releases. Please refer to the SOS documentation from your release for help managing legacy symbolic links. Virtuoso data cdsgdm_file_trigger This trigger gets applied to all files and (working in DFII) cellviews that you manipulate through the Virtuoso user interface. The dflt_dir_trigger gets applied to directories.
These triggers have basic definitions in the default sos.cfg file. You can override those definitions in your site or project configuration files.
Defining a Trigger
Trigger definitions are a list of SOS commands together with the shell commands to run before and afterwards, and the attributes to compute or set when the command is executed. The syntax for triggers in sos.cfg is: trigger trigger_name { sos_command_1 { exec_before [server] shell_command_1 [exec_before [server] shell_command_2...] exec_after [server] shell_command_3 [...] [exec_after [server] shell_command_4...] attribute attribute_name_1 ; [attribute attribute_name_2 ; ... ] } sos_command_2 { ... } ... } where shell_command is usually a script and attribute_name is an SOS attribute. Do not quote shell_command, except in the unusual situation that the command name itself contains spaces. NOTE: Client systems need to be able to resolve the path to the shell_command. Keep this requirement in mind when you have project users located at multiple sites.
Customizing the SOS Client and the User Interface 101 SOS Administration Guide
This example uses the default directory trigger to restrict who can use the delete command. The trigger specifies that only the project lead can delete a directory. trigger dflt_dir_trigger { delete { -- Allow only the project lead to delete directories exec_before /projects/my_project/setup/scripts/ac_lead_only } } -- trigger dflt_dir_trigger This trigger calls the script ac_lead_only, shown below, to enforce the restriction on the delete command: #!/bin/csh -fe set UID = $SOS_LOGIN_NAME set LEADID = toolman if ($UID != $LEADID) then echo "** Only the project administrator may perform this operation." exit 1 endif exit 0 For more examples, see $CLIOSOFT_DIR/data/sos.cfg. The following sections describe the keywords in trigger definitions.
exec_before The text between the exec_before action and the end of the line (which you can extend with a backslash character \), is submitted to a Bourne shell /bin/sh before the SOS command is executed. You can specify multiple exec_before commands for each SOS command. If the shell does not exit with normal status, the SOS command does not run. The exec_before action is useful for operations like these: • Process controls, such as running a Lint check before checking in Verilog files • Access controls, such as preventing check-ins during a scheduled backup window
exec_after The text between the exec_after action and the end of the line (which you can extend with a backslash character \), is submitted to a Bourne shell /bin/sh after the SOS command is executed. You can specify multiple exec_after commands for each SOS command. SOS ignores the exit status of the exec_after action. The exec_after action is useful for operations like these: • Generating email notifications • Cleaning up temporary files that editors create
Customizing the SOS Client and the User Interface 102 SOS Administration Guide
attribute The specified attribute is recorded in the SOS database when this action is executed. The attribute keyword is allowed only for the co, ci, and create commands. You can specify multiple attributes for each SOS command. You must declare attributes before you reference them, earlier in the configuration file (or in another configuration file that was read earlier). With the create command, you can only use the attribute keyword to assign a value to a predefined file attribute, not to a revision attribute.
server By default, SOS executes trigger actions on the client system. Use the server keyword after exec_before or exec_after to execute the trigger action on the server system. Use this keyword with caution, because a script running on the server might slow down SOS operations for all project users or crash the server. For security, you cannot run arbitrary commands on the server. The script or program that you execute must be located in the project_repository/setup directory. For example, consider this trigger: exec_after server my_script arg1 arg2 … SOS runs the following command on the server: project_repository/setup/my_script arg1 arg2 … Script Languages and Locations
Making Scripts Platform-Independent Scripts run in the Bourne shell on Linux, and as Windows scripts on Windows. To run a platform-independent script with a trigger command, write the script in Tcl and execute it with the sostclsh command. For example: exec_before sostclsh my_script.tcl The sostclsh command is a version of tclsh that is included in the bin directory of the SOS installation. For more examples, see $CLIOSOFT_DIR/adaptors/ip_mngr/
Making Scripts Accessible at All Project Sites All clients at all sites must be able to use exactly the same pathname to access the script. There are three ways to make the script accessible to all clients: • Use a standard mount point at all sites. For example: /projects/SOS/scripts/script_name • Use an environment variable, set to point to the appropriate scripts directory at each site: $SOS_SCRIPTS/script_name
Customizing the SOS Client and the User Interface 103 SOS Administration Guide
• Place the scripts in the project_repository/setup/SCRIPTS directory. When the SOS client starts, it copies all of the scripts in that directory to .SOS/SCRIPTS. This means that you can run the script with this path: .SOS/SCRIPTS/script_name Be aware that a user can edit the script in the .SOS/SCRIPTS directory. if scripts are meant to enforce a strict process flow or access control that users should not be able to override, do not use this method.
Commands that Accept Actions
Table 15 lists the SOS commands that accept actions. Table 15 SOS Commands that Accept Actions Command Special Considerations and Limitations in Actions addreference ci You can set attributes with this command. co You can set attributes with this command. create You can set object attributes with this command. definebranch Because this command is not associated with a specific file, the actions associated with this command are set in the dflt_file_trigger. definetag Because this command is not associated with a specific file, the actions associated with this command are set in the dflt_file_trigger. delete You can only define exec_before triggers for this command. deleterev diff discardco exportrev history merge modattr move newworkarea Because this command is not associated with a specific file, the actions associated with this command are set in the dflt_file_trigger. Also, you can only specify exec_after actions for this command. populate SOS runs actions associated with this command when the populate command is executed, and any other time that revisions of a file are brought into a work area. rename snapshot The trigger is applied to all objects that are included in the snapshot. tag terminate unpopulate You can only define exec_before triggers for this command.
Customizing the SOS Client and the User Interface 104 SOS Administration Guide
Table 15 SOS Commands that Accept Actions Command Special Considerations and Limitations in Actions update Because this command is not associated with a specific file, the actions associated with this command are set in the dflt_file_trigger. userev
For more information about the SOS commands in Table 15, type soscmd help at your Linux prompt. For the most current information about the commands that do accept actions, see the system default client configuration file, $CLIOSOFT_DIR/data/sos.cfg.
Using Environment Variables in Actions
SOS passes project information into the shell that runs an action script in the form of environment variables. NOTE: You can also use the environment variables described in this section when you run the shell command from the SOS command line or a user-defined button in the user interface.
Predefined Environment Variables Table 16 lists the environment variables that are predefined in the SOS software. In addition to these predefined variables, SOS automatically creates environment variables for all predefined and user-defined attributes whenever you select an object. The format of these environment variables is: SOS_variable-name See Table 13, “Predefined Attributes” on page 97 for a list of predefined attributes. Table 16 Predefined Environment Variables Variable Description SOS_CURRENT_REV The version number of the current version of the file or directory in your work area. This value is only available if the script is operating on a file or directory that is under SOS revision control. SOS_FLAGS The state of the object in the work area. Each bit corresponds to a state of the object. You can use the status command to check the value. • 0: The file has been checked out by the user in that work area. • 1: The file is not the latest revision on the branch. • 2: The file has unmerged branches • 3: The current version in work area does not match the RSO of the work area • 4: The current version has been checked out in a different work area. • 5: The current revision has been terminated. • 6: The file has been checked out without a lock.
Customizing the SOS Client and the User Interface 105 SOS Administration Guide
Table 16 Predefined Environment Variables (continued) Variable Description SOS_LOGIN_NAME The login name of the user running the command. SOS_NUM_SELECTED The number of objects currently selected. SOS_OBJ_CLASS The type of object selected, one of the following: • src_file: a file that is under SOS revision control. • src_dir: a directory that is under SOS revision control. • src_pack: a package that is under SOS revision control. • src_symlink: a symbolic link that is under SOS revision control. • tmp_file: a file that is not under SOS revision control. • tmp_dir: a directory that is not under SOS revision control. • tmp_pack: a package that is not under SOS revision control. • tmp_symlink: a symbolic link that is not under SOS revision control. • revision: a revision of a file or directory under SOS revision control. • tag: a tag on a revision of a file or directory. • branch: a branch of development from a revision of a file or directory. SOS_OBJ_LIB The internal location under which the object resides in the repository and cache SOS_OBJ_PATH The path to the selected object relative to the root of the work area. SOS_OBJ_SRC The internal unique name assigned to the object as maintained in the repository and cache. SOS_PROJECT The project name. SOS_PROJECT_PATH The path to the repository from the primary server. SOS_SELECT_INDEX A number which is an index of an object in the current list of selections. For example, if you have five objects selected then SOS_SELECT_INDEX is set to 1 when the first object is being processed and set to 5 when the last one is being processed. SOS_SELECTED_REV The version number of the selected file or directory. If you have explicitly selected a version other than the current version in your work area, this value will not match SOS_CURRENT_REV. Otherwise, the values match. SOS_SERVER The name of the server. SOS_TAG The name of the TAG that you are assigning to an object. This variable is useful in a script that you run in a pre-event trigger, in a test to check whether you have permission to assign that particular tag. SOS only sets this variable when you run the tag command, or when the ci command sets a tag.
Customizing the SOS Client and the User Interface 106 SOS Administration Guide Trigger-Based Access Controls
One of the most common uses of triggers is to set up access controls by executing scripts in C shell, Bourne shell, Perl, and other scripting languages. Access control scripts need to be executed in the exec_before trigger for the command that you want to control. For example, to restrict the delete command to the project lead: 1 Write a shell script that returns a non-zero status if the user ID does not match the project lead ID. See “Defining a Trigger” for an example of this script. 2 Install the script in a location and with permissions such that it is executable by all but writable only by the project lead. See “Making Scripts Accessible at All Project Sites” 3 Copy the trigger definition that you want to modify from $CLIOSOFT_DIR/data/sos.cfg to the project_repository/setup/sos.cfg file. 4 Edit the project sos.cfg to invoke the script as an exec_before action for the delete command for all of the defined triggers. See “Defining a Trigger” for an example of these trigger definitions. 5 Require that all users exit and then restart their SOS client software. This forces the clients to re-read the configuration file and begins enforcing the new restrictions. 6 If you do not set access controls for all of the defined triggers, or if you use the Owner file attribute to set the access controls, you must also set access controls for the modifyattr command.
SKILL Triggers
You can set up SKILL triggers to be executed when you use the Virtuoso user interface to check in, check out, or tag an object. For example, a pre-event trigger can run a Check and Save operation before a schematic is checked in. These triggers are specific to SOS, and are different from the Cadence-supplied generic DM triggers. For instructions on setting up and using SKILL triggers, see this file: $CLIOSOFT_DIR/scripts/cds_sosviadfII_vars.il
Customizing the SOS Client and the User Interface 107 SOS Administration Guide Example: Setting the Trigger Attribute When Creating a File
This example uses the create command to assign a trigger to all Verilog files based on their file extension. Here is the trigger: trigger dflt_file_trigger { create { attribute Trigger { value .SOS/SCRIPTS/is_verilog } } } Here is the is_verilog script, which should be installed in the repository/ setup/SCRIPTS directory: #!/bin/sh # # Print 'verilog_file_trigger' if the filename extension is 'v' # Used to automatically associate 'verilog_file_trigger' with all verilog files. # if [ -z "$SOS_OBJ_PATH" ]; then echo "" exit fi
filename=$(basename "$SOS_OBJ_PATH") extension="${filename##*.}" if [ $extension = v ]; then echo "verilog_file_trigger" else echo "" fi
Customizing the SOS Client and the User Interface 108 SOS Administration Guide Example: Setting the Group Attribute when Creating a File
NOTE: This is a continuation of “Example: Overlapping Design and Layout Groups”. We can use the cdsgdm_file_trigger to set the Group attribute. This trigger is assigned to all files that are checked in from Virtuoso. By default, the Group attribute is set to the DEFAULT_GROUP of the user as specified in the server configuration file. However, this default behavior does not yield correct results if the user belongs to multiple groups (for example, Design and Layout groups). By using the cdsgdm_file_trigger trigger, when a user initially checks in an unmanaged Virtuoso file, you can assign the Group attribute based on the name of the cellview or file instead of the user’s identity. This ensures that other members of that group can check out and modify the file, but users from the other group (design or layout) can only populate and update that data. trigger cdsgdm_file_trigger { create { attribute Group { -- This path should be accessible to ALL SOS clients. value /path/to/set_grp.pl; } } Here is the Perl script set_grp.pl: #!/usr/bin/perl # Here are some environment variables that might come in handy. $path = $ENV{'SOS_OBJ_PATH'}; #path of the object # Example for comparing view names. # The group names are returned on stdout. # The script must have an exit 0 at the end. if ($path =~ /layout/) { print STDOUT "layout\n" ; } else { print STDOUT "design\n" ; } exit 0 Example: Overriding Attribute Properties in a Trigger
You can override the prompt, required, and value properties of attributes inside a trigger definition as shown in this example: trigger test_bench_trigger { ci { attribute issue_id { prompt no; required no; }
Customizing the SOS Client and the User Interface 109 SOS Administration Guide
attribute Log { required yes; } attribute line_count { value .SOS/SCRIPTS/tb_line_count } } } Example: Trigger for Running a Verilog Lint Check
This example defines a pre-event action to be executed when a Verilog file is checked in or checked out. If the script called in exec_before exits with a non-zero status, SOS does not execute the command. For this example, the path /projects/common/scripts must be accessible to all local and remote clients. trigger verilog_file_trigger {
co { attribute chkout_path; } ci { -- Pre-event action exec_before /projects/common/scripts/lintchk } } The drawback to defining the lint check action in this way is that you need to somehow determine which files should have this trigger associated with them. It would be easier to run the lint check by modifying the dflt_file_trigger to run a script that checks whether the file is a Verilog file, and if it is, runs the lintchk script. However, this approach means that the script gets invoked for all files, even though the lint check only runs on the Verilog files; this is inefficient. A second approach would be to change the Trigger attribute during the create operation by modifying the dflt_file_trigger: trigger dflt_file_trigger { create { attribute Trigger { value script_to_determine_what_trigger_value_to_set } } }
Customizing the SOS Client and the User Interface 110 SOS Administration Guide Example: Script for Notification of Command Results
This example shows a script that you could include in an exec_after trigger to generate email messages when files are checked in. #!/bin/csh -f #------# Send email notification after command is executed in successful in SOS. # Usage: exec_after send_email_notification
set log = $SOS_Log if ($SOS_CMD == "tag") then set log = "Tag Name: $SOS_TAG" endif
# Send email to all users specified as input foreach usr ($argv) mail -s "SOS alert - $cmd $SOS_OBJ_PATH." "$usr" <
Specifying Exclude, Cleanup, and Local Copy Files
Several keywords in the site and project client configuration files (sos.cfg) let you identify files that require special handling: • Specify file types that should not be added to revision control with the exclude keyword. • Specify files that SOS may safely delete when you delete their parent directory from SOS with the cleanup keyword. • Specify files that should always be local copies in the work area, not symbolic links, with the localcopy keyword.
Customizing the SOS Client and the User Interface 111 SOS Administration Guide Setting the Exclude Files List
The exclude command in the client configuration file specifies file patterns that should be excluded from SOS revision control. Use this list to avoid adding backup files and other nonessential files to revision control. The effective exclude list combines the exclude declarations in the system default, site default, and project client configuration files. The syntax is: exclude { "pattern1", "pattern2", ... } Each pattern must be enclosed in double quotation marks. Separate the patterns by commas. The pattern syntax is the glob pattern used in Linux shells. The pattern may include the * wildcard. The pattern may use a directory path, to match a file type only in a specific subdirectory name. Here is an example that excludes all files that begin and end in the # character, all files with the .cd% extension, and any files in a directory named schematic with the .dat extension: exclude { "#*#", "*.cd%", "schematic/*.dat" } --exclude For more examples, see $CLIOSOFT_DIR/data/sos.cfg.
Setting the Cleanup Files List
If a directory contains unmanaged files after you have deleted all of the managed files, SOS cannot remove the directory from the work area. Use the cleanup files list to avoid leaving useless files in unmanaged directories when SOS tries to delete directories. The cleanup command in the client configuration file specifies file patterns that match unmanaged files that SOS should delete when deleting a managed directory. Typically these files are backup files or simulation run files. The syntax is the same as for the exclude command, except that patterns may not contain directory names. cleanup { "pattern1", "pattern2", ... } -- cleanup For example, to remove temporary files that end in .cd% or .cd~: cleanup { "*.cd%", "*.cd~" } -- cleanup
Customizing the SOS Client and the User Interface 112 SOS Administration Guide
For more examples, see $CLIOSOFT_DIR/data/sos.cfg.
Setting the Local Copy Files List
When you create a work area, the recommended Links to smart cache option tells SOS to create symbolic links in the work area to files in the cache. This arrangement is not compatible with certain special files for design tools, such as the lib.defs file for Virtuoso libraries. Use the localcopy keyword to identify files that should always be copied, not linked, to work areas. localcopy { "pattern1", "pattern2", ... } -- localcopy Use this pattern for Virtuoso 6.x: localcopy { "lib.defs" } -- localcopy Use this pattern for Silicon Canvas Laker 3.2v3 or higher with LDM support: localcopy { "libfile" } -- localcopy
Setting UDMA Rules for Automatic Cellview Packaging
SOS supports rules for automatically combining related files that comprise an object into package objects. These rules are called the Universal Design Management Adapter (UDMA). Internally, SOS uses UDMA rules to identify and package objects for some supported tools, such as Synopsys Custom Designer and Keysight ADS. You can write your own UDMA rules for EDA tools that ClioSoft does not formally support. Bundling the files that comprise objects like cellviews into a single package makes working with cellviews more intuitive and convenient for your designers. NOTE: You can use UDMA rules to combine any set of related files, not just cellviews. After you add a set of files that meets the UDMA rules to SOS revision control, SOS applies the rules automatically and creates packages. Automatic packaging happens the first time that SOS examines the contents of the changed folder (for example, when a user expands a directory to view the contents or refreshes the tree view of the folder in the SOS application).
Customizing the SOS Client and the User Interface 113 SOS Administration Guide UDMA Rule Syntax
Define UDMA rules in the sos.cfg configuration file. The package keyword introduces an UDMA rule set. The syntax for a rule set is: package package_type_name { libid { matchall | matchany } pattern_list ; basename { globall | globany } pattern_list; packname use packname_pattern; include globplus pattern_list; exclude glob pattern_list; } A pattern_list is a comma-separated list of regular expressions that are enclosed in double quotes. Table 17 describes the keywords in UDMA rules. Table 17 UDMA Rule Keywords Keyword Description libid The libid rule defines how to recognize the directory that contains the files that comprise a cellview (or some other object that you want to package). Usually this directory is a library directory for your EDA tools. matchall Recognize a library directory when a directory contains file names that match all of the specified patterns. matchany Recognize a library directory when a directory contains file names that match any of the specified patterns. basename The basename rule captures the design object name, which you can use in later rules. globall Use the string that matches all of the patterns in the list as the object name. globany Use the string that matches any of the patterns in the list as the object name. For example, this rule: basename globany {*}/master.tag ; matches {schematic}/master.tag. packname use packname_pattern The packname rule sets the SOS package name. To use the basename as the package name, specify $1.
Customizing the SOS Client and the User Interface 114 SOS Administration Guide
Table 17 UDMA Rule Keywords (continued) Keyword Description include globplus The include rule identifies the files to include in the package. You can use $1 to use the basename in a pattern. Use the ellipsis (...) to match files at any level below a specified directory. For example: include globplus "$1/.../*.oa" exclude glob The exclude rule omits the files that match the pattern from the package, even though their names match the include rule. The ellipsis (...) operator is not supported with this keyword. This keyword is optional. For example: exclude glob "*.lck"
Example UDMA Rule
For a Synopsys UDMA rule example, see $CLIOSOFT_DIR/adaptors/cdesigner/sos.cfg. Below is an example of a UDMA rule for the Mentor DxDesigner product: package DxDesigner {
// A directory must contain sub directories labeled "sch", "sym" and "wir". libid matchall “*/sch”, “*/sym”, “*/wir”;
// Match the pattern to get the composite object name. basename globany “sch/{*}.[0-9]*”, “sym/{*}.[0-9]*”, “wir/{*}.[0-9]*”;
// Use the composite package name without any modification. packname use “$1”;
// The composite object must contain files below the sub directories matching // package name. Also extensions on the file can be any nonnegative integer. include globplus “sch/$1.[0-9]*”, “sym/$1.[0-9]*”, “wir/$1.[0-9]*”; }
Customizing the SOS Client and the User Interface 115 SOS Administration Guide
The next figure shows the result of applying this rule to newly-created DxDesigner cellviews. Figure 8: UDMA Rules Applied for Mentor DxDesigner
Applying these rules does not move files into new folders on the file system. In this example, the files for each sheet remain in their original parent folders. Only the representation within SOS changes. This is why the sch, sym, and wir folders appear as unmanaged files with lavender-colored icons in Figure 8 (right). Hiding unmanaged files from view in SOS simplifies the tree view and excludes files (such as lock files) that the EDA tool manages automatically.
Using X Resources
You can customize the SOS application graphical user interface by setting X resource values. You can set values globally, for a project, or for an individual user. Using X resources you can: • Set colors and fonts. For example, to change the main window background color, modify this X resource: Sos.workAreaDisplay.windowBackgroundColor: white • Define which attributes to display. • Add user-defined commands as buttons in the user interface. • Set the default revision search order.
Priority of X Resources
SOS reads the X resources in the following order:
Customizing the SOS Client and the User Interface 116 SOS Administration Guide
1 The file $CLIOSOFT_DIR/data/Sos.ad (Linux) or Sos.win.ad (Windows) 2 The settings in the X server, which are typically set by xrdb. 3 The site-specific Sos.ad or Sos.win.ad file in $SOSD_CONFIG_DIR. See “Configuration File Locations”. 4 The file server_name.rep/project_name/setup/Sos.ad or Sos.win.ad. 5 The file specified by the environment variable $XENVIRONMENT. 6 If the file specified by $XENVIRONMENT does not exist, or the environment variable is not set, the file ~/.Xdefaults. To change a resource for all users working on a specific project, edit server_name.rep/project_name/setup/Sos.ad. To make changes to an individual user’s environment, edit ~/.Xdefaults or the file $XENVIRONMENT (if it exists). Restart the SOS clients to load any changes that you make to X resources. If you change Tk X resources (names beginning with Sos* for fonts and colors used in dialog boxes, menus, and buttons), you must also run xrdb: xrdb –merge X_resource_file NOTE: On Windows, the path to the system default X resources file is: installation_directory\data\Sos.win.ad For example: C:\ClioSoft\sos_6.30p1\data\Sos.win.ad Also, the software looks for the user .Xdefaults file in $HOME/.Xdefaults if $HOME is defined, or otherwise in C:/.Xdefaults.
Working With X Resource Files
ClioSoft provides several template X resource files: Table 18 X Resource File Templates Template Features change_display_appearance Examples for changing colors and fonts customize_buttons Examples for adding buttons to the SOS application main window display_attributes Example for changing the list of file attributes displayed in the SOS application main window
Follow the next steps to perform these tasks with X resource files: • Retrieve a copy of the current global or project X resources file for editing. • Create or update a file from a template. • Install a new or updated file in the correct location. 1 Highlight the primary server in the SOSAdmin window and click Projects. The Projects window for the server opens. 2 Highlight the project in the Projects window and click Customize.
Customizing the SOS Client and the User Interface 117 SOS Administration Guide
3 For Select config file, choose Client GUI. 4 Select your operating system, click Get, and do one of the following: • To edit the existing configuration file, highlight Get existing project cfg and click Select. By default, new projects do not have an X resources file and this option is disabled. • To retrieve a copy of a template X resources file, choose Get a template, highlight a template, and click Select. 5 Specify a destination folder and file name. 6 Edit the file with a text editor. 7 From the Projects window, click Customize again. 8 Click Put, browse to the file that you edited, and click Open. 9 Restart your SOS client.
Changing Colors and Fonts
You can use X resources to change the colors and fonts used in the SOS and SOSAdmin applications. The default global X resources file, $CLIOSOFT_DIR/data/Sos.ad, contains all of these resources and their defaults. Most of these resources are commented out with the ! comment character. To make global changes, uncomment the lines and change the values. To make project or user-specific changes, copy the lines to the project or user (~/.Xdefaults) X resources file. For example, to change the default background from the color wheat to white: 1 Locate this line in Sos.ad: !Sos.workAreaDisplay.windowBackgroundColor: wheat 2 Paste the line into the project or user X resource file and change the color: Sos.workAreaDisplay.windowBackgroundColor: white 3 Restart SOS to see the change.
Displaying Attributes
The main SOS window shows attribute values to the right of the Hierarchy tree. By default, four attributes appear: the CheckedOutBy attribute (labeled Locked), the CheckedInBy attribute, the CheckInTime attribute, and the change_summary attribute. If the file is checked out, the Locked column shows the login ID of the user who checked out the file. If the file is not checked out, this column is empty. The Change Summary column shows your check out comment if you have the file checked out in this work area; otherwise, this column shows the check in comment
Customizing the SOS Client and the User Interface 118 SOS Administration Guide
associated with the file revision that you have in your work area (which is not necessarily the latest revision).
By updating the related X resources, you can change and rearrange which attributes are displayed. You can display all types of attributes except text attributes (because they are multi-line attributes). The Sos.attributes.list resource defines which attributes get displayed and the order of the columns: Sos.attributes.list: attribute1 [attribute2 ...] For each attribute, three resources define how the attribute gets displayed: Sos.attributes.attribute_name.display: {yes | no} Sos.attributes.attribute_name.label: "label" Sos.attributes.attribute_name.width: integer For example, if you have a user-defined attribute issue_id which contains a bug tracking number, you would modify Sos.attributes.list to include issue_id and define three new resources: Sos.attributes.list: CheckedOutBy issue_id change_summary Sos.attributes.issue_id.display: yes Sos.attributes.issue_id.label: "Bug #" Sos.attributes.issue_id.width: 5 You can also change how the default attributes are displayed: • To make the change_summary column 60 characters wide: Sos.attributes.change_summary.width: 60 To move the change_summary column to the left of the CheckedOutBy column: Sos.attributes.list: change_summary CheckedOutBy Adding Buttons
You can use X resources to define buttons that appear on the right side of the SOS window. The list of buttons and their order is defined by the resource Sos.buttons.list. To modify an existing button, copy the relevant resources from $CLIOSOFT_DIR/data/Sos.ad into the .Xdefaults file in your home directory, and make the necessary changes.
Customizing the SOS Client and the User Interface 119 SOS Administration Guide
User-defined buttons can execute Linux commands, Linux shell scripts, SOS Tcl commands, or Tcl scripts. If no objects are selected, the script or command runs once. If multiple objects are selected, the script or command runs once for each selected object. Follow these steps to add a user-defined button: 1 In your personal ~/.Xdefaults or the project Sos.ad resources file, define the label for the button: Sos.buttons.NAME.label: LABEL The LABEL string may contain spaces and does not need to be quoted. 2 Define the command for the button Sos.buttons.NAME.command: [shell | source] path_to_script_or_cmd where path_to_script_or_cmd is a Linux command, Linux Bourne shell script, SOS Tcl command, or Tcl script. The path must be accessible to all clients, so use environment variables or common mount paths as needed. See “Making Scripts Accessible at All Project Sites”. Anything after the shell command is submitted to the shell. The shell script can accept arguments. This example runs tclsh and passes in a file name as an argument: Sos.buttons.ipcompare.command: shell $CLIOSOFT_DIR/bin/sostclsh .SOS/SCRIPTS/ip_compare.tcl Only one argument may follow the source command: the name of the Tcl file to source into the SOS Tcl interpreter. Use this option carefully, because syntax errors or other mistakes might cause the SOS process to hang or crash. This file cannot be a Tcl command, and the file does not take any arguments. If you omit both source and shell commands, SOS treats the argument as a built-in SOS Tcl procedure. For example, the Check In button in the GUI is defined as: Sos.buttons.ci.command: gui_check_in The gui_check_in procedure is a built-in SOS Tcl procedure. 3 Copy the Sos.buttons.list resource from the site or project Sos.ad file to a personal or project X resources file. 4 Add your button to the list in any position: Sos.buttons.list: create co ci ... NAME ... where NAME is the same name you used in the label and command resources.
Running Shell Commands with Buttons To run a Bourne shell command or script, precede the value of the command resource with the keyword shell. All output from the command to stdout or stderr is displayed in a popup window. If you do not want this window to pop up, redirect stdout and stderr to a file or to /dev/null. For example, to redirect stdout and stderr for the user-defined Lint button to the selected file name with a .lnt extension, use this command resource:
Customizing the SOS Client and the User Interface 120 SOS Administration Guide
Sos.buttons.lint.command: shell verilint 1>$SOS_OBJ_PATH.lnt 2>&1 & The command or script is invoked in a Bourne shell in the background. If your script is written for a different shell then make sure that you use the proper notation to run the script in the correct shell. For example, the report script is written in the C shell, so the first line of the script is: #!/bin/csh -f The next example shows how you could define a Report button to generate reports about files. These are the X resources: Sos.buttons.list: create co ci ... report Sos.buttons.report.label: Report Sos.buttons.report.command: shell /project/scripts/report This is the report script: echo "${SOS_SELECT_INDEX}. $SOS_OBJ_PATH" echo " Revision: $SOS_CURRENT_REV" echo " Change summary: $SOS_change_summary" echo " RSO label: $SOS_MatchedLabel" echo " Checked in by: $SOS_CheckedInBy" echo " Check in time: $SOS_CheckInTime" Running Tcl Commands with Buttons The resources in the first example define a button with the label Chk In that runs the built-in SOS Tcl command gui_check_in: Sos.buttons.ci.label: Chk In Sos.buttons.ci.command: gui_check_in The resources in the next example customize the button list to delete the Create button and add a button to run the Revision > Use Revision command: Sos.buttons.list: co userev ci tag difference history showsel update edit \ info Sos.buttons.userev.label: Use Rev Sos.buttons.userev.command: gui_use_revision Available TCL Commands for Buttons TCL commands are available for each item in the SOS menus. You can use all of these commands in buttons. Table 19 Tcl Commands for SOS Menu Items Menu Item TCL Command File > Open Workarea gui_open_workarea File > New Workarea gui_setup_workarea File > Update Workarea gui_update_workarea Update (button) File > Update Selected gui_update_selected File > Delete Workarea gui_delete_workarea
Customizing the SOS Client and the User Interface 121 SOS Administration Guide
Table 19 Tcl Commands for SOS Menu Items (continued) Menu Item TCL Command File > Exit gui_exit Project > Create Project gui_create_project Project > Plot Attributes gui_plot Project > Define Tag gui_define_tag Project > Define Branch gui_define_branch Project > Take Snapshot gui_take_snapshot Modify Attrs > Revision gui_modattrs_revision Modify Attrs > Checked Out gui_modattrs_checked_out Modify Attrs > Source File/Dir gui_modattrs_source Modify Attrs > Project gui_modattrs_project Modify Attrs > Tag gui_modattrs_tag Modify Attrs > Branch gui_modattrs_branch Modify Attrs > Snapshot gui_modattrs_snapshot Select > All Below gui_select_below Select > All Files Below in SOS gui_select_below "insos" Select > All Files Below not in SOS gui_select_below "notinsos" Select > Unselect All gui_unselect_all Select > All Checked Out in gui_select_checked_out Workarea Select > All Checked Out and gui_select_checked_out "changed" Modified Select > All Checked Out but Not gui_select_checked_out "unchanged" Modified Select > All Checked Out by Others gui_select_checked_out_others Select > All Untagged gui_select_untagged Select > All Unmerged gui_select_unmerged Select > All Not Latest gui_select_not_latest Select > Show Selected gui_show_selections ShowSel (button) Select > Advanced Select gui_select_advanced Tree > Populate gui_populate_tree Tree > Unpopulate gui_unpopulate_tree Tree > Create File/Dir gui_create_source Tree > Delete gui_delete Tree > Rename gui_rename Tree > Expand/Collapse gui_toggle_expansion Tree > Expand/Collapse Full gui_toggle_expansion_full Tree > Refresh gui_refresh_window Tree > Show/Hide Files not in SOS gui_toggle_visibility_notinsos Tree > Show/Hide Tags gui_toggle_tag_visibility
Customizing the SOS Client and the User Interface 122 SOS Administration Guide
Table 19 Tcl Commands for SOS Menu Items (continued) Menu Item TCL Command Tree > Show/Hide Directory gui_toggle_revdir_visibility Revisions Tree > Sort by Name/Extension gui_toggle_tree_sort Tree > Propagate Flags gui_propagate_flags Tree > Set Node RSO gui_set_rso Revision > Check Out gui_check_out Chk Out (Button) Revision > Check In gui_check_in Chk In (Button) Revision > Discard Check Out gui_discard_check_out Revision > Use Revision gui_use_revision Revision > Export Revision gui_export_revision Revision > Delete Revision gui_delete_revision Revision > Tag gui_tag Revision > Merge gui_merge Revision > Terminate Branch gui_terminate_branch Revision > History gui_history History (Button) gui_history_full Revision > Difference gui_difference Diff (Button)
Specifying SOS Tcl Commands in .sosrc
The .sosrc configuration file provides another mechanism for setting site and project defaults, especially default values in SOS dialog boxes. This file contains SOS Tcl commands.
Default Settings in .sosrc
The default .sosrc file contains settings for two frequently-customized user interface settings: the default work area type and the concurrent checkout feature. # New workarea dialog # wa_type = 1 local copy # = 2 links to common WA # = 3 links to latest # = 4 links to smart cache # set DBOX(newworkarea.wa_type) 1
# Check Out Dialog # concurrent checkout flag = True or False #
Customizing the SOS Client and the User Interface 123 SOS Administration Guide
set DBOX(co.concurrent) False To change the default work area type from Local Copies to Links to Smart Cache, change the value of newworkarea.wa_type to 4. To enable concurrent checkout, set co.concurrent to True. For more information about customizing the user interface, contact ClioSoft Support.
Priority of .sosrc Files
The software reads the .sosrc file from these locations, with the last-read values taking priority: 1 $CLIOSOFT_DIR/data/.sosrc 2 $SOSD_CONFIG_DIR/.sosrc 3 project_repository/setup/.sosrc 4 $HOME/.sosrc 5 work_area_root/.sosrc Also see “Configuration File Locations”.
Customizing the SOS Client and the User Interface 124