Cliosoft SOS User Guide

Version 7.00 and later

September, 2020 Revision H SOS User Guide

Legal Notices

Copyright © 2014 - 2020 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]

Overview of the SOS Software 2 SOS User Guide 1

Chap OVERVIEW OF THE SOS SOFTWARE

This chapter gives an overview of the Cliosoft SOS hardware configuration management software.

About This Manual

This manual explains how to use the SOS software to manage EDA design files and related files, such as documentation files and EDA tool configuration files. This manual is for both designers and project administrators. Project administrators should also read the SOS Administration Guide. This manual shows how to work directly with the SOS user interface. You can also use SOS through its interfaces with popular EDA design tools, such as Cadence® Virtuoso®. Many designers, especially schematic and layout designers, usually work with the SOS this way. For information about using SOS with your design tools, see these documents: • Getting Started with SOS for Virtuoso® Designers • Getting Started with SOS for ADS Designers • Getting Started with SOS in Synopsys Custom Compiler

Overview of the SOS Software 3 SOS User Guide

Understanding Hardware Configuration Management

EDA Design Methodology without Design Management

When the design environment does not include design management software, each user has scratch libraries for development. All users share the same master libraries of finished cells. FiguMethodology and Libraries without Design Management

Designers create or edit cells in their personal scratch libraries, and then verify changes by using their scratch libraries and the shared master libraries. Designers copy finished cells hierarchically from their scratch libraries to the master library. Working without design management, it is very easy for a designer to accidentally overwrite another designer’s work 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.

Design Methodology with Hardware Configuration Management

Hardware configuration management helps design teams avoid these problems by automating and simplifying how you manage all of the libraries and 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 copy of the project libraries. The SOS software prevents accidental or simultaneous changes to project libraries. • Version Control: every time you check in a file, you create a new revision of that file in the project repository. You can revert back to older revisions at any time. You can also easily recreate any previous release of your entire project. Each revision gets an ID number starting from 1 and incremented for each new revision.

Overview of the SOS Software 4 SOS User Guide

• Change Tracking: SOS automatically maintains a change history for every file. Virtuoso users can run Visual Design Diff to see the change history for any cellview graphically in the schematic or layout editor window, with each change highlighted. • Access Control: CAD managers determine who can make changes to “golden” versions of files, or to specific libraries and. For example, layout engineers might not be allowed to modify schematics. • Release Management: you can save snapshots of a design that record the version of every 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.

Managing Files and Libraries in SOS Projects

All of the files and libraries associated with a design are stored in a central SOS project repository. The project repository is a database that is specialized for handling circuit and semiconductor design data. As a designer, you work with copies of the libraries in your own “sandbox” or work area. The work area contains project libraries and files that are shared between everyone working on a project. This means that you do not need to create your own editable “scratch” copies of the project libraries. FiguProject Repositories and Work Areas

Most large design teams are spread out across multiple sites, often in more than one country. For multi-site installations, there is usually a primary SOS

Overview of the SOS Software 5 SOS User Guide 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 the figure, when Sally checks in a new file to the project, the new file gets copied to the SOS cache server and the designers in Shanghai can begin using the new file immediately. For more information about the SOS client and server software architecture, see About SOS Servers, Clients, Projects, and Work Areas in the SOS Administration Guide.

Typical Daily Work Task Flow

Designers typically work with the SOS software by following these steps: 1 Check out a file from a library, working from the SOS user interface or from within your design tool environment. SOS creates a writable copy of the file in your work area directory, and places a lock on the file in SOS. The lock prevents other users at both local and remote sites from checking out the file and accidentally making simultaneous changes. 2 Edit the file and save the changes to disk. 3 Verify the changes with simulations. 4 When you are satisfied with the changes, check in the verified file from your work area to the repository. This creates a new version of the file. Now other designers can use the view. 5 Update your work area to collect changes from other designers. Designers might repeat these steps once each day, or several times each day, depending on the scope of the changes in each iteration.

About the SOS Software

The SOS software applies revision control to cellviews and other design data files, so that your entire design team can: • Stay informed about changes made by other designers on your team wherever they are located. • Always work with the correct libraries and correct file versions. The SOS software consists of: • The SOS application, for advanced design data management • The SOSAdmin application for managing projects and servers

Overview of the SOS Software 6 SOS User Guide

• The SOS integration with your design tools, which lets you perform most daily design management tasks using SOS commands added to the normal tool menus • The SOS Visual Design Diff utility, for comparing versions of cellviews Both the SOS and the SOSAdmin applications have graphical user interfaces for day-to-day work and command-line interfaces for scripting. The next few pages give a quick overview of each of the SOS software tools.

The SOS Graphical User Interface

The tool for day-to-day operations on files is the SOS graphical user interface, shown in the next figure. To start the SOS graphical user interface, cd to your work area directory and enter the command sos. For help, choose Help > Documentation. See Starting SOS for information about startup options. FiguSOS Graphical User Interface

The SOS window shows the status of the files in your project. Using the commands in the menus, you can check files into and out of the project, select which versions of the files to use in your work area, and perform other design

Overview of the SOS Software 7 SOS User Guide management tasks. The right-click shortcut menu in the Hierarchy tree gives you quick access to commonly-used commands.

Shift-click the + icons in the Hierarchy tree to expand the tree down the lowest level. Shift-click the - icons to collapse the tree up to the current folder. NoteYou can also perform many of these tasks from the user interface of your design tools. For RTL designers and for anyone who is managing text-based or documentation files, using the SOS window is often more convenient than working from the design tool user interface. Schematic design and layout engineers typically do most of their work from the design tool environment, using the SOS customizations for their design tools. Hovering the mouse over a folder shows detailed information about its contents down through the folder hierarchy.

Overview of the SOS Software 8 SOS User Guide

The SOS Command Line Interface

You can use the SOS command line interface to run SOS in a terminal window, or from scripts. The syntax is soscmd command [arguments] For a list of commands, type soscmd help. For detailed help about a particular command, type soscmd help command. For examples, see Using the Command Line Interface.

The SOSAdmin Graphical User Interface

The SOSAdmin graphical user interface is the tool for managing projects and servers. All users can run this tool, but some commands are restricted to project administrators. To start the SOSAdmin tool, use the command sosadmin from any directory.

Overview of the SOS Software 9 SOS User Guide

FiguSOSAdmin Window

The SOSAdmin Command Line Interface

The SOSAdmin tool 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 . See the SOS Administration Guide for more information about SOSAdmin.

SOS Integration with Design Tools

Typically, RTL engineers and project administrators use the SOS application for most of their work. Design and layout engineers most often use the SOS integration with their design tools, and manage their files from within their design tool environment. For example, in the Cadence Virtuoso environment, you use the Check In dialog box to check in files to the project. In the figure, a user is adding a new file to the project.

Overview of the SOS Software 10 SOS User Guide

FiguCheck In Dialog Box in the Virtuoso Environment

There are differences in the SOS integrations with each of the supported design tool environments. For all of the integrations, some advanced and less common tasks require using the SOS graphical user interface (or the command line).

The Visual Design Diff (VDD) Utility

The VDD utility lets you compare two schematic, layout, or Verilog views of a Virtuoso cellview. For more information, see Using Visual Design Diff (VDD).

Overview of the SOS Software 11 SOS User Guide

Starting SOS

To start SOS normally and open the SOS window: 1 Move (cd) to your work area directory. 2 Enter the command sos &. You can use these options with the sos command:

TablOptions for the sos Command

Option Description -help Print command option help and exit. -here Start SOS in the current directory unconditionally. Use this option to start SOS when you wish to create a nested work area directory under an existing work area directory. Cliosoft does not recommend creating nested work area directories. To avoid the need to create nested work area directories, do not use your home directory as your first work area directory. By default, SOS checks whether a higher-level directory is an SOS work area, and automatically moves up to that work area directory before starting. Use this option to override the default behavior. -iconic Minimize the SOS window when SOS starts. -nowin Start SOS without opening the SOS window. This is mainly used for scripting, or to hide the window. -quiet Start SOS without printing informational message to the terminal. Errors and warnings always get reported in the terminal. -wa path_to_dir Start SOS in the specified directory, to associate the SOS process with the work area. This option is typically used in scripts that launch SOS, so that output from the ps command will show which work area directory each sos process is using. For example: sos -wa /u1/demo/verification

NoteIf you use SOS on a Windows PC, see “Using SOS on Windows PCs”.

Overview of the SOS Software 12 SOS User Guide

Object Types in SOS

SOS manages and keeps track of revisions for four types of objects:

• Files, such as Verilog source files, design tool configuration files (for example, Virtuoso .cdsinit files), and project planning spreadsheet files

• Symbolic links to files or directories, such as PDK or reference library directories. For example, when the path to the PDK changes after a new release, an update to the link gives all project users access to the new PDK.

• Directories SOS creates a new revision of a directory when you add, delete, rename, or move an object in the directory. Modifying an object in a directory does not change the directory, so no new revision gets created. When you add or delete objects, SOS automatically checks out the parent directory and checks it in to create a new revision. Directory revisions make it possible to restore the project hierarchy that existed at project milestones.

• Packages (composite objects), such as Virtuoso cellviews, which consist of multiple files that need to be managed together For more information about the icons in the SOS user interface, see “Understanding Object Status in a Work Area”. NoteFor brevity, this manual uses the term “file” to refer to all types of objects, except when discussing a product feature that only applies to certain types of objects.

Managed and Unmanaged Files

Files that belong to an SOS project are called managed files. Files that do not belong to a project, and therefore are not under revision control, are called unmanaged files. Unmanaged files and directories are represented by lavender-colored icons in the SOS user interface ( and ).

Packages

Packages are a special object type in SOS. Packages let you work with a group of related files as a single object. Packages are most commonly used to manage multi-file objects in your design tools, such as cellviews in Virtuoso and

Overview of the SOS Software 13 SOS User Guide design blocks in Mentor vialCstudio. Managing the files as a package lets users check out and edit the abstract design object without worrying about the individual files.

Labels in SOS: Tags, Snapshots, Branches, and the Revision Search Order

Labels give you a way to access specific revisions of project files without needing to memorize which revision of each file shares a certain status. There are three kinds of labels: tags, snapshots, and branches. The Revision Search Order is a list of labels that specifies which revisions of project files you want to make available in your work area.

Tags

A tag is a symbolic label for a revision of a file. Typically you tag a design file when it reaches a significant milestone, such as completing a successful verification. Some examples of tag names are verified, gold, lvs_clean, and drc_clean. In the next figure, revision 4 of the netif.v file has two tags: design_done and design_verified. Revision 3 of the file has the snapshot label release_1.0. (See the next section for information about snapshots.) Revision 2 has at least one label (it could be a tag, snapshot, or branch), which is not displayed. Revision 1 does not have any tags, so there is no + control on the left.

NoteThe icons for tags are blue. Snapshots have red icons. The same revision of a file can have multiple tags. However, the same tag cannot be placed on multiple revisions of the same file. If a tag already exists on a revision of a file and you apply that tag to a different revision, the tag moves to the new revision. Tags are typically moved from older revisions to newer revisions.

Overview of the SOS Software 14 SOS User Guide

Tags are typically used to publish or promote a change to a different level of visibility. For example, you may choose to use tags called gold, silver, and bronze to imply different levels of confidence. You may tag a file bronze after some initial testing and add the silver and gold tags after it passes more tests. Designers who are investigating the most aggressive design possibilities might pick the bronze revisions of all the files. However, the release engineer would probably pick only the gold revisions. “Picking” a tag means including that tag in your Revision Search Order, at or near the beginning of the list. See About the Revision Search Order. To assign a tag to the current revision of a file, right-click the file and choose Tag. For more information about defining and using tags, see “Using Tags”.

Snapshots

A snapshot is a special type of tag that you apply to multiple objects to record a configuration, such as a tapeout milestone. When you take a snapshot, SOS recursively labels the current revisions of all of the files and directories in the selected tree with the snapshot name.You typically take a snapshot from the root directory of the project, so that the snapshot label applies to everything in the project. By specifying a previous snapshot name in your Revision Search Order, you can recreate the project at the recorded milestone: SOS repopulates your work area with the exact revision of each file and the exact directory hierarchy that existed when you took the snapshot. Some typical snapshot names are release_1.0 and final_tapeout. Snapshot labels have red icons; regular tags have blue icons. Only project administrators can reassign a snapshot label to a different revision. To understand the purpose of snapshots, consider this small project with three source files. Some of the files have been modified more often than the others, so some files have more revisions. For example, mux.v has been modified three times, while inv.v has not been modified since it was created. Project before the Snapshot shows the history of the files. The shaded revision is the current revision. FiguProject before the Snapshot

Overview of the SOS Software 15 SOS User Guide

Suppose that the 1.0 production release of this module of the design is now complete, and the files are ready to be delivered to the rest of the design team. To identify the revisions of the files used in this release, we can create a snapshot named 1.0_prod. This snapshot lets us identify the exact revision of each file being released to the rest of the team. Project at the Snapshot shows the 1.0_prod tag assigned to the project files. FiguProject at the Snapshot

Over time, development of the project continues. The same source files continue to be used, but there have been several changes to the mux.v file, as shown next in Project after the Snapshot: FiguProject after the Snapshot

Overview of the SOS Software 16 SOS User Guide

Notice that the snapshot tag 1.0_prod remains fixed on the correct revisions of the files. If a developer needs to review some code from the 1.0_prod release, they can create a work area using a Revision Search Order that specifies the 1.0_prod snapshot name. Without the snapshot, the developer would need to keep track of all of the file revisions and explicitly select revision 2 of ram.v, revision 3 of mux.v, and revision 1 of inv.v. For help creating and using snapshots, see About the Revision Search Order and “Working with Snapshots”.

When to Use Tags and Snapshots

The key differences between tags and snapshots are: • Tags only apply to the specific objects that you select. Snapshots are usually recursive. (They are recursive by default.) • Regular users can (and often will) move tags from one revision of a file to another. Only project administrators can move a snapshot label to another revision of a file. (Moving snapshot labels is not common.) Although any user can create a snapshot, Cliosoft recommends that only administrators and designated designers create them. Use tags to communicate the status of individual files: that they have been verified, for example. Use snapshots to capture project milestones, such as product releases. For example, you might assign the verified tag to revision 1 of a file and then move that tag to revisions 2, 3, and 4 as the design progresses. Version 2 might belong to the beta snapshot, version 3 to the release_candidate1 snapshot, and version 4 to the release_1.0 snapshot.

Overview of the SOS Software 17 SOS User Guide

Branches

A branch is an alternate thread of design development. Typically, development proceeds sequentially: you make a series of changes to a file, one after the other. This means that files usually have a single line of development: the main branch. Occasionally you may want to work on two versions of a file in parallel. For example, you might need to experiment with an alternative implementation, create a special design variant for one client, or make a major redesign. In these cases, you may want to create a new branch of development for one or more files, so that you can pursue the alternative implementation while continuing to work on the main line of development. When you have completed development on a branch you should either: • Terminate the branch to indicate that development on that branch is complete and changes on this branch are not applicable to the main line of development. • Merge the changes on the branch back to the main line of development. In the figure, revision 2 of branch plan_b has been merged back to the main line of development as revision 3.

For more information, see “Using Branches for Project Variations”.

About the Revision Search Order

The Revision Search Order (RSO) is an ordered list of label names. It specifies which revisions of files and directories will be placed in your work area when you populate or update your work area. You set the Revision Search Order with the Files > Change RSO command.

Overview of the SOS Software 18 SOS User Guide

SOS starts from the first label and tries to find a revision that matches the label. If SOS finds a revision with a matching label, SOS selects that revision. Otherwise, SOS tries the next label in the revision search order. • If the label is a tag or a snapshot name, SOS picks the revision which currently has that tag. • If the label is a branch name, SOS picks the latest revision on that branch. For example, in the next figure, the Current RSO option is set to prefer revisions with the design_done tag or snapshot name. If no revision with that tag is available, SOS chooses the latest revision from the main branch of the project.

You can qualify the main branch in the Revision Search Order to select only certain objects on that branch by appending a suffix, as described in the next table. These qualifiers only appear as Revision Search Order choices when you select Branches in the Update Workarea dialog box:

Overview of the SOS Software 19 SOS User Guide

TablQualifiers for main in the Revision Search Order

Qualifier Result main/dir Get the latest versions of directories, but not files, links, or packages. Cliosoft recommends that you include main/dir at the beginning of your Revision Search Order, so that you always use the newest directories as your starting point. The /dir qualifier is also useful when you want to explore the latest directory hierarchy, but do not want to update your files. For example, the Revision Search Order main/dir, verified selects the latest versions of all directories, and files tagged as verified. If you specified only verified as the Revision Search Order, you would not necessarily get the latest directories, because users do not typically assign tags to directories. (If verified is a snapshot name, directories as well as files would have the verified label assigned.) main/files Get the latest versions of files, links, and packages, but not directories. main/owner Only select objects on the main branch that you own. If you do not own the latest version of the object on the main branch, SOS proceeds to the next label in your Revision Search Order. The Owner file attribute determines who owns a file. Typically this attribute gets set to the user who added the file to SOS. Checking in a later version of a file does not change the ownership. main/group Only select objects on the main branch that belong to your default group. If the latest version of the object on the main branch does not belong to your default group, SOS proceeds to the next label in your Revision Search Order.

Overview of the SOS Software 20 SOS User Guide

For example, a Revision Search Order of main/owner, verified would match the latest versions of all files owned by the user, and match the versions tagged as verified for all other objects. NoteAdministrators may set a default revision search order for all project users, for groups of users, or for individual users by editing the server configuration file, sosd.cfg. Also see Changing the Revision Search Order While Updating Your Work Area and Examples of Revision Search Orders.

Examples of Revision Search Orders

Whenever you manually update your work area, you can change your Revision Search Order (RSO). This lets you populate your work area with a different set of revisions, such as a previously taped out version of the project. Here are some examples: • main Get the latest checked-in revisions on the main branch. This is the most common RSO. • verified, main Get the revisions of files that are tagged verified. If a file does not have a revision with that tag, get the latest revision on the main branch. • main/dir, verified, main Get the latest revisions of all directories. Also get the revisions of files that are tagged verified. If a file does not have a revision with that tag, get the latest revision on the main branch. • tapeout_1 Recreate the exact work area that was recorded by the snapshot tapeout_1. • lowpower_branch, tapeout_1 If a file has a branch named lowpower_branch, get the latest revision on that branch. For all other files, get the revision labeled tapeout_1. NoteIf you change the Revision Search Order in a way that excludes an existing directory, SOS retains the current revision of the directory. This means that, working from the same Revision Search Order, updating an existing work area can yield a different set of files than creating a new directory. To have SOS delete directories that do not match the Revision Search Order during updates, set the environment variable SOS_STRICT_RSO to 1 and restart SOS.

Overview of the SOS Software 21 SOS User Guide

Log Files

SOS writes log files for each SOS client and server. Most messages from your client and the servers appear in the message area at the bottom of the SOS window. Some messages are only written to the log files and do not appear in the message area.

Messages are classified as Notes (green), Warnings (yellow), or Errors (red). An Error message generally means that an operation with SOS failed. Click the button on the left to clear the message area. • The client log file, sos.log, gets written to the top-level directory in the work area. • The server log file, server.log, and the cache server log file, srv_cache.log, get written to SERVERS/LOCAL or SERVERS/REMOTE under their server-specific directories. NoteLog files are for debugging purposes only; you can delete them if they begin to take up too much disk space. Always exit the SOS software before you delete the sos.log file. In addition to the sos.log file, SOS writes two other information files to the directory from which you start SOS: • The history.out file records the messages from the History command. SOS replaces this file each time that you run the History command. • The update_summary.out file records information about new, changed, and deleted files whenever you update your work area. SOS replaces this file whenever you update your work area.

Overview of the SOS Software 22 SOS User Guide

Documentation and Support

To view the online documentation, choose Help > Documentation from the SOS window or use the sos_docs Linux command. For information about SOS command-line options, use these commands: % soscmd help % sosadmin help PDF documentation is available here: $CLIOSOFT_DIR/docs/ Visit www.cliosoft.com/support to: • View FAQs and online training videos. For troubleshooting information, select Troubleshooting under FAQs. • Download application notes. • Download new releases of Cliosoft software. • Ask a question or report an issue by opening a support ticket. You can also open a ticket by sending email to [email protected].

Overview of the SOS Software 23 2

Chap USING WORK AREAS (SANDBOXES)

This chapter explains how to use SOS work areas, or sandboxes, in the following sections: • Setting Up Your Work Area • Types of Work Areas: the Op • Add • Understanding Object Status in a Work Area • Updating (Repopulating) Your Work Area

Using Work Areas 24 Setting Up Your Work Area

A work area is a local directory structure that mirrors the directory hierarchy of an SOS project. If you work on multiple projects, you need separate work area directories for each project. A work area may be physically located on a local disk, or it may be on a file server. Often the project administrator creates all of the user work area directories in the same subdirectory on a file server, to simplify project management. Ask your project administrator where to create your work area directory. Here is an example directory structure for a project that groups all users work areas together under a common directory: /server/ourchip/adsl_project/workareas bob cadmgr fred lynh If your work area will be under your own home directory, always create a subdirectory of your home directory for the work area directory. Do not use your home directory itself as the work area directory, because by default you cannot create work areas under an existing work area directory. This means that, if your home directory is already a work area, it is inconvenient to create and work with multiple projects and their separate work areas. (To work around this limitation, use the -here command line option. See “Starting SOS”.)

Creating Your Work Area Directory

At most organizations, creating user work areas is automated with a script that the project administrator writes. If your organization does not use a script, follow these steps to create a work area directory: 1 From the Linux command line, create a new directory. For example: % cd /projects/scsicontroller/workareas % mkdir jesse % cd jesse 2 Copy any necessary startup files for your design tools into the new directory. Consult with your project administrator about this step. Some or all of the startup files might be part of the SOS project data, so they will get copied to your work area automatically later in the setup process. 3 If you need to add new files to the project, you can copy them to your work area directory now or later. 4 From your work area directory, enter the Linux command sos to start SOS.

Using Work Areas 25 If the SOS Login dialog box appears, enter your Linux or UNIX account name and password. 5 In the SOS window, choose File > New Workarea.

6 Set the options in the dialog box as follows. Check with your project administrator for help choosing the right options. 1 Click the arrows next to the Server Name and Project Name fields to display the drop-down lists, and choose the correct values. 2 For Workarea Dir, choose the current directory. 3 Leave Project Root blank, unless you only need to work in one particular subdirectory of the project. See Minimizing the Size of a Work Area. 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 other choices for this option, see Types of Work Areas: the Op.

Using Work Areas 26 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. NoteThe 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. The next step is to populate your new work area with read-only copies of (or links to) the project files.

Populating a New Work Area

When you create your work area, the main SOS window shows the entire project files tree, but no files or directories have actually been copied or linked into your work area directory. To add those copies or links, you need to populate your work area. Once you have populated your work area, you can begin to work with the files. Unpopulated files are shown as gray in the SOS window, as shown in the next figure. FiguA Small, Unpopulated New Work Area for a Project

To populate your work area with all of the files in the project: 1 Select the top-level ( . ) folder in the Hierarchy tree, as shown in the figure. 2 Select Tree > Populate and click Yes in the confirmation dialog box. Populating a work area may take some time, depending on the size of the project, while the files and directories get created.

Using Work Areas 27 The window updates to show the status of each file, as shown in the next figure. FiguA Populated Work Area

Minimizing the Size of a Work Area

Most users do not need copies of every file in the project. For example, analog designers might not need the Verilog files. You can save disk space and speed up SOS operations by excluding unnecessary files from your work area. There are several ways to do this: • You can include just one of the project subdirectories in your work area by specifying a Project Root when you set up your work area. • You can populate selected subdirectories instead of populating the entire root directory. After you set up your work area, select the subdirectories and choose Tree > Populate. • You can apply the Tree > Never Populate command to one or more subdirectories to permanently exclude their files from your work area. • The project administrator can use the NEVER_POPULATE directive in the sosd.cfg file to prevent the Populate command from automatically populating specified directories. • To temporarily clear the contents of a directory, use the Tree > Unpopulate command. The next time you update your work area, SOS repopulates the directory.

Specifying a Project Root while Creating a Work Area New work areas contain all of the subdirectories in the project if you leave the Project Root field empty. To include just one subdirectory in your work area, click Browse opposite Project Root and choose a subdirectory from the Select root dialog box. To choose the project view for your user role, such as cfg_analog or cfg_layout, choose the configuration folder as the Project Root. Using Work Areas 28

Using the Never Populate Option Instead of populating your entire work area, you can designate some subdirectories to never be populated. This means that SOS does not copy or link the files to your work area, and does not need to check the status of the files when you update your work area. 1 Highlight a directory to exclude. 2 Choose Tree > Never Populate. 3 Repeat these steps for other directories, subdirectories, or files that you do not want to populate.

Using Work Areas 29 Types of Work Areas: the Option Keep Files in Workarea as

The options for Keep Files in Workarea as in the New Workarea dialog box give you choices for trading off disk space usage and performance when you populate your work area. • Links to Smart Cache uses disk space most efficiently and minimizes the time required to update your work area. Large teams, or teams working on large designs, should generally choose this option. • Local Copies uses more disk space, and updates to your work area take longer. With this option, you can work offline without a connection to the server. Simulation and verification jobs may run faster, because the simulator does not need to follow links to open files. • Writable Copies makes the files in the work area directory writable local copies of the project files. With the other options, files are read-only until you check them out. This option is useful for digital designers who work with text files. For more information about these options, see the next sections. Links to Smart Cache

The Links to Smart Cache option is the choice that Cliosoft recommends in most situations. This option creates symbolic links from your work area to files on the cache server for all of the files that you choose to populate. Large hardware teams with large designs should always choose this option, and there are no real drawbacks for small teams. You work in an isolated, stable file structure. When you check out a file, SOS replaces the symbolic link in your work area with a writable copy of the file. Editing the file in your work area does not affect the contents of the cache, so your changes do not impact other users until you check in the file.

Using Work Areas 30 NoteThe targets of the symbolic links to the cache do not change until you update your work area, so you always have full control of the contents of your work area. The Links to Smart Cache option minimizes disk space usage by the team, and makes populating and synchronizing your work area with the project repository as fast and efficient as possible. Local Copies

The Local copies option creates read-only copies in your work area directory of all of the files that you choose to populate.

This option is best suited for small teams of designers doing RTL or digital design work, or software development. You can check out files quickly because there is a local copy available, and you work in an isolated file structure. With this option, you can work offline without a connection to the server. Simulation and verification jobs may run faster, because the simulator does not need to follow links to open files. This option increases disk space usage, because every user has copies of all of the files in the project. For a large project, copying all of the files to populate your work area, and synchronizing your work area with the project repository, may take a long time. Writable Copies

The standalone version of SOS lets you create writable work areas. In a writable work area, all files are local writable copies. You can edit any file without having to run the checkout command. You can then check in the modified files. This use model is useful for software, firmware, and front end digital engineers who primarily work with text files and may be familiar with other software configuration management systems such as GIT, SVN, and Perforce. With other types of work areas, files in your work area are read-only unless you check them out with SOS.

Using Work Areas 31 When you update a writable work area: • SOS brings in new revisions of unmodified files and attempts to automatically merge any modified text files. If there are conflicts, the original is maintained as an .SVM file and SOS reports a warning. SOS adds merge markers to the updated files to show the conflicts. • If you have modified a binary file, the modified local file is renamed to .SVM, and the new revision replaces the file in the work area with a warning. • If you have disabled the preference Update files modified without CO, SOS does not change the modified files and only updates the flags.

Adding New Files to a Project and a Work Area

1 Copy the new files and directories to your work area directory, or create them there. 2 Open the SOS application with the sos command from your work area

directory. The new files are unmanaged (not under revision control), so they have lavender-colored folder and file icons. If the unmanaged files are not visible, select Tree > Show Unmanaged Files to display them. 3 Select the specific folders and files that you want to add to the project, as shown in the figure. 4 Select Tree > Create File/Dir.

Using Work Areas 32

For Revision control method, do not make a selection if you want SOS to choose the appropriate default values for different types of data. Overriding this default behavior is not common. 5 Optionally, disable RCS Keyword substitution for ASCII files by selecting No. See General SOS Preferences for more information about this feature. 6 Optionally, select an Icon to display for the files and select a Trigger. For information about triggers, see the SOS Administration Guide. 7 Enter a Description of the files. 8 Click Create All. SOS checks in the files.

Using Work Areas 33 Understanding Object Status in a Work Area

The SOS Hierarchy tree uses icons with a variety of colors and shapes to indicate the status of files and other objects in your work area. This section describes those icons. Other icons to the right of and below the object icon give you more details about the status of the object. FiguExamples of Object Icons

Lavender icons denote unmanaged objects. To add unmanaged objects to the project, select the unmanaged objects and then choose Tree > Create File/Dir. When SOS has placed an object in your work area, either as a local copy or as a symbolic link, that object has been “populated” in your work area. Until an object has been populated, it does not physically exist in your work area. Lavender colored icons denote unmanaged objects, and gray colored icons denote unpopulated objects. To populate files into your work area, select the gray icons and choose Tree > Populate. Table 3 shows the icons for directories.

TablDirectory Icons

Icon Meaning Unmanaged directory: this directory exists in your work area but is not part of the project. Possibly a program that you ran created this directory. Unpopulated directory: you must populate a directory before you can check in or check out files in the directory.

Using Work Areas 34 Never populate this directory: you marked this directory to not be populated when you update your work area. Marking directories this way lets you avoid copying unnecessary files to your work area, speeding up file synchronization and saving disk space. Populated directory: this is the normal status of a directory that contains files you might need to edit or to use in verification.

Partially populated directory. If the folder is yellow, the folder itself is not fully populated but some of its children are populated.

Partially populated directory. If the folder is orange, the folder itself is populated but some of its children are not populated.

Reference directory: the black arrow means that this directory uses the default RSO. See Using Reference Projects.

Reference directory: the red arrow means that this directory uses a custom RSO. The main purpose of internal references is to set up configurations. See Defining and Using Project Views in the SOS Administration Guide. Reference directory: the gray arrow means that this directory does not use the default RSO. The directory is partially populated.

Reference directory: the gray arrow means that this directory does not use the default RSO. The directory is fully populated.

Unreadable: you do not have permission to read this directory.

File, Symbolic Link, and Package Icons shows the icons for files.

TablFile, Symbolic Link, and Package Icons

Icon Meaning Unmanaged: this file exists in your work area but is not part of the project. To add the file to the project, see Add.

Unpopulated: this directory is not populated and will not automatically be populated when you update your work area.

Never populate this file.

Using Work Areas 35 Unpopulated temporarily: this file is not populated, but it will automatically be populated when you update your work area

Populated file.

Populated reference file: the arrow means that this file has been included in this project from a separate reference project. See “Using Reference Projects”. Populated package. Unmanaged packages have lavender icons. Unpopulated packages have gray icons. Packages marked as Never Populate have a red slash through the icon. Populated symbolic link. Unmanaged symbolic links have lavender icons. Unpopulated symbolic links have gray icons. Links marked as Never Populate have a red slash. Populated reference package: the arrow means that this package has been included in this project from a separate reference project. See “Using Reference Projects”. Unreadable file: you do not have permission to view or edit this file.

Revision icons appear below objects in the Hierarchy tree. There is an icon for every revision of an object. Revision Icons

TablRevision Icons

Icon Meaning This revision of the object is the one that you currently have in your work area.

This revision of the object is not the revision that you currently have in your work area.

This object was branched to a new development path. For information about branches, see “Using Branches for Project Variations”.

This branch has been terminated. No more development along this branch is expected for this file This icon appears next to the last revision on the branch.

describes these icons.

Using Work Areas 36 Status icons appear to the right of objects in the Hierarchy tree. SOS updates the status icons based on your own actions. To see status changes caused by other users, you must update your work area. Status Icons shows the SOS status icons.

TablStatus Icons

Icon Meaning On a file, the feather icon means that you have this object checked out for editing and locked. Other users cannot accidentally edit the object, but they may be able to override your lock. On a directory, the feather icon means that you have checked out the directory, or at least one object in or below it. Another user has this object checked out for editing and locked. Usually you should wait for the other user to check in the file, and then check it out to make your changes. If the file has both the lock icon and the yellow feather icon, concurrent checkout is enabled on this file and you have also checked out the file. This is a common situation for Verilog test bench files, when multiple designers need to edit different sections of the file. You have this object checked out for editing, but it is not locked. Files can have this status for several reasons: • You might have selected the Do NOT lock file option when you checked out the file. If you are at a remote site and the connection to the server goes down, this is the only way to check out the file. You might also choose that option if you are running a simulation and the simulator requires write access to a file, but you do not plan to save the changes. • An administrator may have canceled your lock on the file by using the Revision > Discard Checkout command. This icon appears if you had modified the file. See “Canceling a Check Out”. You do not have the latest revision of this object in your work area. This is not necessarily a problem, if you are deliberately working with an earlier revision of the design (for example, a previous tapeout). If you want to check out the older revision already in your work area, you need to create a branch. On a directory, this icon means that you have an older revision of some object lower in the hierarchy. This object has an open branch with changes that have not yet been merged or terminated. On a directory, this icon means that at least one object lower in the hierarchy has an open branch.

Using Work Areas 37 The revision of this object in your work area is not the revision that your revision search order would select. If you update your work area, this file will be replaced with a different revision. On a directory, this icon means that some object lower in the hierarchy does not match the current Revision Search Order, unless you have turned off the Propagate Flag attribute for this flag. This icon indicates that a reference lower in the hierarchy does not use the default RSO. You can trace this icon down the hierarchy to locate the reference.

Updating (Repopulating) Your Work Area

Once you have populated your work area, you have a stable work environment. Your work area is not automatically affected by changes that other users make to the project files. However, you will want to update your work area periodically (daily, weekly, or at some other interval) to synchronize your work area with the project and collect updated revisions of the project files. When you update your work area, SOS checks the status of every file that has been updated in the project since your previous update. • Existing files get updated in your work area, but only if your revision search order specifies that you want the updated revision. • New files in the project, and existing files that have been moved, get added to your work area. • Deleted files get removed from your work area. • Renamed files get renamed in your work area. NoteIf you chose Links to Common Workarea or Links to Latest Revisions for the Keep Files in Workarea as option, your work area always gets updated automatically with new revisions of existing files, but there is no automatic update for files that are added, deleted, renamed, or moved.

Automatically Updating (Synchronizing) Your Work Area

If you use the Local Copies or the Links to Smart Cache options for your work area, you can use the SOS Preferences dialog box to specify whether and how often to automatically update your work area. Use File > Preferences to

Using Work Areas 38 open this dialog box.

To automatically update your work area with new and changed files from all of the projects that you use in your design at the end of every work day, but avoid having automatic updates run during your work day: 1 In the Preferences dialog box, select these options: • Set Automatic Update to Primary & Reference Projects. • Set What to Changed Files & Dirs. • Set When to Idle for to a reasonable value, such as 120 minutes. 2 Do not shut down or suspend your PC or workstation at the end of the day. NoteWhen you close the SOS window, you have the option of keeping SOS running in the background. If you schedule automatic updates, be sure to keep SOS running in the background so that the updates can run as scheduled. Keep in mind that, if you shut down or suspend your workstation at the end of the day, SOS will not be able to update your work area overnight. For more information about options for automatic updates, see “Setting Preferences”.

Manually Updating Your Work Area

To manually update your work area (for example, to pick up a change that you know a colleague has checked in): 1 Select File > Update Workarea. The Update Workarea dialog box appears. FiguUpdate Workarea Dialog Box

Using Work Areas 39

2 For a typical daily or weekly update, accept the default options and click OK. To preview the changes that will happen when you click OK, click Preview. To revert the files in your work area to the revisions that match your Revision Search Order at a specific past date and time, select the Specified Time option in the Update Workarea dialog box. For example, you can use this option to roll back your work area to a known good state if you discover that some colleagues have checked in changes that caused regressions. If you have created new revisions of some objects, and do not want to overwrite those changes, select Keep revisions newer than RSO. When you click OK, SOS checks which files and directories have changed since you last updated your work area. Then SOS applies the revision search order specified in the Current RSO list to select the correct revisions of the updated files. (This will not necessarily be the newest revision.) Finally, SOS copies (or creates a link to) the files that need updates. For information about the other options in this dialog box, see the next section. 3 Review the Update Summary dialog box and click Dismiss.

Changing the Revision Search Order While Updating Your Work Area

The Update Workarea command always uses the current Revision Search Order. To change the Revision Search Order and update your work area at the

Using Work Areas 40 same time, use the File > Change RSO command instead of Update Workarea. 1 Select File > Change RSO. The Update Workarea dialog box appears with Revision Search Order options.

2 Build the new Revision Search Order in the RSO box. See “About the Revision Search Order” and “Examples of Revision Search Orders”. To preview the changes that will happen when you click OK, click Preview. 3 Set the other options appropriately and click OK.

Selectively Updating Your Work Area

To partially update certain files or directory trees in your work area to match the current Revision Search Order, without updating the entire work area:

Using Work Areas 41 1 Select all of the files and directories that you want to update. For help, see “Selecting Files”. 2 Choose File > Update Selected. 3 In the dialog box, choose At Time: Now or specify a past time, and click OK.

Moving a Work Area Directory to a New Location

To move a work area directory to a new disk or location: 1 Exit SOS. 2 Move the root directory of the work area. This is the directory that contains the hidden .SOS directory. For example: mv /mach1/usr/mylogin/wa1 /mach2/usr/mylogin/wa2 3 Restart SOS.

Using Work Areas 42 SOS User Guide

3

Chap WORKING WITH DESIGN FILES

This chapter explains how to work with design files.

Working with Design Files 43 SOS User Guide

Checking Out Files

Before you can edit a file in an SOS project, you must first check out the file. 1 In the SOS window Hierarchy tree, right-click the file and choose Check Out. The Check Out Dialog Box appears.

For help selecting files, see Sel. 2 In the Log box, write the reason for checking out the file. 3 Click Check Out. SOS creates a writable copy of the file in your work area, which you can edit. (In Links to Smart Cache work areas, SOS replaces the link with a writable copy of the file.) By default, SOS also places a lock on the file so that other users cannot check it out. 4 Double-click the file in the Hierarchy tree to open the file in the default text editor. NoteOn Windows, if you double-click a file that is not checked out, you are prompted to check it out. On Linux, the file opens in read- only mode in the editor that your preferences specify.

Checking Out Files while the Server is Offline

If the SOS server for the project is offline or unreachable, SOS reports an error when you click the Check Out button. To edit the file, select Do NOT lock file in the Check Out dialog box and click Check Out. If another user checks out the file, you will need to merge your changes.

Working with Design Files 44 SOS User Guide

SOS uses a white feather icon, instead of the usual yellow feather icon, to identify files that you have checked out but have not locked. In Locked and Unlocked Checked Out Files, • The two feather icons next to the rtl folder indicate that your checked out files in the folder include both locked and unlocked files. • You checked out netif.v while the server was online, and you locked the file. • You checked out rxjitbuf.v without a lock, possibly while the server was offline. • You checked out sigmaplus.v without a lock, and another user has a lock on the file. FiguLocked and Unlocked Checked Out Files

Using Concurrent Checkout

If you need to check out a locked file, select Enable concurrent checkout when you check it out. Concurrent checkout lets the SOS server keep track of who is working on the file, without blocking other users from making changes. Other users will see the lock ( ) icon, and you will see both the lock and the yellow feather ( ) icons because you have the file checked out and it is also locked by another user. When the last user checks in the file, they need to merge the changes by using the Revision > Merge command. See Mer. NoteIf you use the Do NOT lock file option, other users will not realize that you are editing the file. This might cause problems if they work in a way that makes merging your changes with theirs more difficult. Only use the Do NOT lock file option when the server is unavailable, or when you intend to cancel the checkout.

Creating a Branch When You Check Out a File

To create a branch when you check out a file, select the Create a Branch option and choose an existing branch from the list that appears. For best practices about branching files, see Usi.

Working with Design Files 45 SOS User Guide

Canceling a Check Out

If you check out a file accidentally, or decide to discard your changes to a file, use the Discard command. NoteIf you use more than one work area for the same project, start SOS and use the Discard command in the work area where you checked out or modified the files. 1 Select the files in the Hierarchy tree. 2 Right-click one of the files and choose Discard.

3 If you have not changed the files, click Yes. Otherwise, choose one of these options: • If you did change the files in your current work area, and want to discard your changes, deselect Do not discard if modified, check that the default choice (Discard selected checkouts by me in this workarea) is selected, and click Yes. • If you created multiple work areas for the same project, and have accidentally deleted one of the work areas, select Discard selected checkouts by me in any workarea, and click Yes to remove the “orphan” locks from the missing work area. • If you are a project administrator and want to unlock the files, select Discard selected checkouts by everyone and click Yes. Any users who had the files checked out will see a white feather icon in SOS after they update their work areas. SOS cannot recover discarded changes. You might be able to recover the files from a backup of your work area.

Working with Design Files 46 SOS User Guide

Checking In Files

When you have finished editing a file, check in the file to add the new revision to the project. Until you check in the file, your changes are not visible to other designers. Once you have checked in the new revision, other designers can get it when they update their work areas. 1 Select one or more files in the Hierarchy tree. For help selecting files, see Sel. 2 Right-click one of the files and choose Check In. The Check In dialog box opens.

3 If the new revision represents a milestone, such as completing the verification of the file, you can apply a tag to reflect the milestone. Click Apply Tags and choose an existing tag from the

list. For more information, see Using Tags. NoteIf your organization has defined optional user-specified attributes, such as issue tracking system information, those attributes appear in this dialog box. Enter the appropriate values.

Working with Design Files 47 SOS User Guide

4 Select an option for Get attributes from. This controls how SOS fills in the Log message box, and user-defined attribute values (if any). • By default, Check In of previous file is selected, and your most recent check in comment is copied into the Log message. • Choose Check Out to copy the log message that you entered when you checked out this file. • Choose Clear to erase the Log message. 5 If the Log box is empty or contains the wrong comment, enter a comment that describes the changes. 6 Click Check In. If you have selected multiple files, the dialog box updates to show the next file. Repeat steps 3-5 for each file, or click Check In All if you want to use the same comment for all of the files. SOS uploads the files to the project server, creates the new versions, and changes the permissions on the file in your work area to be read-only.

Handling Unchanged Files

The If no changes option in the Check In dialog box lets you manage unchanged files. • By default, Skip is selected and the file remains checked out. • Choose Discard to cancel the checkout. • Choose Check in anyway to force the check in operation to proceed. For example, if you have changed the UNIX permissions on a script file, but not its contents, SOS would not recognize that the file has changed. Choose Check in anyway to force SOS to check in the file with the new permissions.

Using the Diff Utility During a Check In

Click the Diff button in the Check In dialog box to compare the revision in your work area with the changes in the local copy of the file. In addition to the SOS diff utility, SOS comes bundled with the tkdiff utility, renamed sostkdiff to avoid command name conflicts. Use the File > Preferences command to choose a diff utility. For example, to select the bundled copy of tkdiff, set diff Command to: sostkdiff -L @L1 -L @L2 @1 @2

Working with Design Files 48 SOS User Guide

FiguSOS diff Utility

Merging Changes at Check In

If another user modifies a file after you check it out, SOS reports a warning when you check in the file. This situation can happen whenever a user checks out a file without locking it and checks in their changes. When you click Check In in the Check in dialog box, SOS opens the Merge dialog box to let you manage the changes. Click Merge to let SOS merge the changes automatically. If SOS cannot perform an automatic merge, you see a warning message that prompts you to edit the file and manually merge the changes. For more help with the Merge dialog box, see “Merging Branches”.

Updating a Change Request During a Check In

When SOS is integrated with a change request tracking system, you can select an issue when you check in a file. In the figure, the Trac issue tracking system is integrated with SOS, and you can select a value from the Track Issue ID drop-down list.

Working with Design Files 49 SOS User Guide

FiguCheck In Dialog Box with Issue Tracking Configured

In addition to the description that you enter in the Log box, the issue tracking system change history also receives this information: • A list of the objects that you checked in • The revision number, including the branch name, of each object • The time that you checked in the objects

Managing Files

This section covers file management topics. Also see “Adding New Files to a Project and a Work Area”.

Selecting Files

The commands in the Select menu let you quickly select files by a variety of useful criteria. You can also select files by name by typing into the Search box at the top right of the SOS main window. For advanced searches, use any of the options for soscmd select in the Search box (type soscmd help select at the command line for a list of options). Some commands operate on files below the current selection; other commands ignore the current selection. The next table describes these commands.

TablSelect Menu Commands

Working with Design Files 50 SOS User Guide

Command Description All Below Select all files below the current selection. All Managed Files Select all files below the current selection that are under SOS Below revision control. All Unmanaged Select all files below the current selection that are not under Files Below SOS revision control. Unselect All Remove everything from the selected set of files. All Checked Out Select all files in this work area that are currently checked out in Workarea by you in this work area. The selection includes both locked and unlocked checkouts. All CO Unlocked Select all files in this work area that are currently checked out in Workarea by you in this work area and are not locked. All Checked Out and Modified Select all modified files in this work area that are currently checked out by you in this work area. All Checked Out but NOT Select all unmodified files in this work area that Modified are currently checked out by you in this work area. All Locked by Others Select all files in this work area that are currently checked out and locked by other users. All Out of Date Select all files in this work area that do not match the current Revision Search Order. These are files that will be replaced with different revisions the next time you update your work area. All Unmerged Select all files in this work area that are on a branch with unmerged changes. All Not Latest Select all files in this work area for which you do not have the latest revision on the current branch. All Writable files in Workarea Select all files in this work area for which you have write permission. All Below Labeled Select or deselect all files below the current selection that have a specified tag, snapshot name, or branch name. The Select labeled files dialog box opens to let you choose the label and choose whether to select or deselect the files. All Below with Attribute Select all files below the current selection that carry a specified attribute, or optionally a specified attribute and value. The Select by Attribute dialog box opens to let you choose an attribute and optionally specify a value. Show Selected Displays a list of the currently selected files. To view a file in the SOS window, select it and click Scroll to in the list dialog box.

Working with Design Files 51 SOS User Guide

Renaming Files

To rename a file or directory: 1 Check out the parent directory. 2 Select (highlight) the file and choose Tree > Rename. 3 Enter the new name and click Rename. 4 Check in the parent directory.

Moving Files

You can move files to another directory by dragging and dropping in the Hierarchy tree. 1 Check out the source and destination directories. 2 Select the files to move. 3 Click and drag the files to the destination folder. 4 Check in both the source and the directories.

Deleting Files

You do not need to check out the directories before deleting files. SOS updates the directories automatically. 1 Select the files in the Hierarchy tree. 2 Choose Tree > Delete.

Managing Revisions

Several SOS commands let you manage the different revisions of a file, so that you can work with earlier revisions and examine a file’s revision history. For help managing revisions, see these topics: • Recovering Deleted Files • Rolling Back Files to an Earlier Revision • Getting a Specific Revision of a File • Identifying Changed Files in a Project

Working with Design Files 52 SOS User Guide

Recovering Deleted Files

To recover deleted files, you must know the name of the directory from which they were deleted. 1 Select the original directory in the Hierarchy tree. 2 Choose Tree > Undelete. The Undelete dialog box appears with a list of the most recently deleted files. 3 If necessary, click Go back more to see previously deleted files. 4 Select the items to recover and click Undelete.

Rolling Back Files to an Earlier Revision

When a design change is unsuccessful, you may want to revert back to an earlier revision of a file. 1 Select the earlier revision in the Hierarchy tree. In the example, version 1 is

selected. 2 Choose Revision > Revert Revision. SOS creates a new revision at the head of the revision tree that is identical to

the selected revision.

Getting a Specific Revision of a File

Most of the time, you select revisions of files by adjusting your Revision Search Order. However, at times you may want to update your work area with a specific revision of a particular file. To do this: 1 Select the revision in the Hierarchy tree. 2 Choose Revision > Use Revision and click OK. This command does not change the status of the file in the project; only the contents of your work area is affected.

Identifying Changed Files in a Project

To determine what files have changed in your project since a specified time:

Working with Design Files 53 SOS User Guide

1 Choose File > Update Workarea and leave the At Time: Now radio button selected. This updates your work area to use the latest revisions of the files that match your Revision Search Order and creates the baseline for comparison. 2 Choose File > Update Workarea again, this time choosing Specified Time, and enter the date and time for the comparison. Also select Flags and Attributes ONLY to avoid changing the contents of your work area directory. 3 Choose Select > All Out of Date. This selects all files that do not match your current Revision Search Order. These are the files that have changed since the specified earlier time. 4 Choose Select > Show Selected to see a list of those files.

Managing Releases with Labels, Branches, and Attributes

You manage releases and design flows in SOS by taking snapshots of the design (and assigning a snapshot label), tagging individual files with labels, setting informative attribute values on objects, and branching files to manage design variants. The next few sections explain these tasks.

Working with Snapshots

Snapshots are restore points of important project milestones, like tapeouts and product releases. For more information about snapshots, see “Snapshots”. You can take a snapshot of your entire project tree, part of the directory tree, or an individual file or directory. Regular users must always create a new snapshot label when they take a snapshot. Administrators can create new labels or update an existing snapshot by re-using an existing snapshot label. For example, if you fix a bug after tapeout, an administrator might take a snapshot of the updated files using an existing snapshot label. This updates the original snapshot to include the fixed files. Individual users can take snapshots to record their own parts of a project. For projects with multiple groups of users (perhaps analog and digital designers), different groups might reach important milestones like tapeout at different times. In that situation, each group might take snapshots of their own portions of a project using labels like analog_tapeout and digital_tapeout. Good snapshot names reflect the project milestone that you are recording, rather than just the date.

Working with Design Files 54 SOS User Guide

Taking a Snapshot Use this procedure to create a new snapshot or add files to an existing snapshot. All of the files comprising the snapshot must be populated in your work area and checked in. 1 Select the top-level directory in the Hierarchy tree, a lower-level directory, or specific files. 2 Choose Project > Take Snapshot. 3 Choose an existing snapshot from the drop-down list (administrators only) or enter a new name. Enter a descriptive comment whenever you create a new snapshot.

4 Set the snapshot options: • Deselect Recursively take snapshot of all objects below if you have partially selected some files and directories but do not want to include their entire contents in the snapshot. • Include writable reference projects applies the snapshot label to files in the reference projects as well as files in the current project. If you are creating a new snapshot label, this snapshot and label get added to the reference project. • Always select Include ancestor directories in snapshot for new snapshots of lower-level directories. This option tells SOS to record the revisions of the ancestor directories, which makes it possible to recreate the project’s directory hierarchy at the time of the snapshot. (You can recreate the directory hierarchy by specifying the snapshot name in your Revision Search Order.) If you deselect this option when you take a new snapshot, it might not be possible to restore the snapshot because your Revision Search Order will not match any revision of the root directory or the other ancestor directories.

Working with Design Files 55 SOS User Guide

If you are updating an existing snapshot to add a few specific files, sometimes you may want to deselect this option. For example, if the project hierarchy changed after you took the snapshot, but you do not want to update the hierarchy of the snapshot, deselect Include ancestor directories in snapshot. 5 Click OK.

Comparing Snapshots of Two Project Releases To compare two snapshots: 1 Choose File > Update Workarea and set the Current RSO to match the most recent snapshot. 2 Choose File > Update Workarea again and set these options: 1 Set the Current RSO to match the earlier snapshot. 2 Set the Update option to Flags & Attributes Only. 3 Choose Select > All Out of Date. 4 Choose Select > Show Selected to see a list of the files that have changed. NoteThe list will not include files that were deleted from the project. To see those files, repeat these steps but first select the earlier snapshot, and then update to the new snapshot with Flags & Attributes Only selected.

Using Tags

Use tags to communicate file status to other users. See “Labels in SOS: Tags, Snapshots, Branches, and the Revision Search Order” for an explanation of tags and other labels.

Creating New Tags Before you can assign a tag to a file, you must define it. Each project has its own set of tags.

Working with Design Files 56 SOS User Guide

1 Select Project > Define Tag. The Define Tag dialog box opens.

2 Type the new tag name in the Tag Name field, or select an existing tag from another project from the drop-down list. 3 Optionally, click Yes opposite Sticky to specify that the tag must be backed off of a revision before it can be applied to a different revision of the same file. See Backing Off Tags. 4 Optionally, click Yes opposite Automatically tag ancestor directories to override the default behavior and apply this tag to ancestor directories whenever the tag gets applied to an object. This makes tags behave more like snapshots, which always apply to ancestor directories. 5 Enter a comment to describe the tag and click Ok. The comment in the example explains that files receive the design_done tag when the design work is complete.

Applying Tags You can apply tags when you check in files. You can also apply tags with the Revision > Tag command. For example, after a successful simulation you can select the files that you verified and apply a tag like design_verified. 1 Select the files and directories to tag. If you want to apply the tag to the current revision in your work area, just select the files and directories. If you want to apply the tag to a different revision, select that specific revision.

Working with Design Files 57 SOS User Guide

2 Select Revision > Tag. It is not necessary to check out the files. The Tag dialog box appears.

3 Optionally, select or deselect Tag ancestor directories to change whether this tag gets applied to ancestor directories as well as the selected objects. 4 Optionally, select Force tag to apply the tag in situations where the tag is already applied to a newer revision of the object. By default, SOS does not apply tags in that situation. 5 Highlight one or more tags and click Tag.

Backing Off Tags SOS keeps a history of tags. The Back Off button in the Tag dialog box is the undo command for the Tag operation. For example, if revision 1 of a file was tagged as verified three days ago, and revision 4 was tagged as verified today, the verified tag will appear on revision 4. If you back off the tag, you Undo the last Tag operation and the tag moves back to revision 1. If you back off the tag a second time, the tag disappears from the file. To back off (undo) a tag: 1 Select one or more files and directories. It is not necessary to select the revision that carries the tag.

Working with Design Files 58 SOS User Guide

2 Select Revision > Tag. It is not necessary to check out the files. The Tag dialog box appears.

3 Click Back Off to move the tag to the revision that previously carried the tag, or click Back Off All to delete the tag instead of moving it.

Editing Tag State and other Attributes To change the comment that describes a tag, or change the tag state: 1 Select Modify Attrs > Tag. 2 Select the project and tag from the drop-down lists 3 The Tag State can be changed. The tag can be changed to either a Normal tag , a Sticky tag which cannot be applied to any other revision of the same object. A third option is to make it Locked i.e where the tag cannot be applied to any other revision of the revision of the current as well as any other object. The tag is locked in place.

4 Make the changes and click Ok

Working with Design Files 59 SOS User Guide

Using Tags with Directory Revisions Directories in SOS have revisions, just like files. In most situations you can ignore this feature of SOS. However, when you assign tags to directories, the results can be unintuitive. This section explains how SOS handles tag and snapshot labels on directories. By default, directory revisions and their tags are hidden in the Hierarchy tree. To display directory revisions, select Tree > Show Directory Revisions. The Hierarchy tree updates to show the _Revisions icon for each folder:

Working with Design Files 60 SOS User Guide

FiguHierarchy Tree with Directory Revisions Displayed

In the figure, the tag gold is applied to the top-level directory and the alu subdirectory. When you take a recursive snapshot, SOS assigns the snapshot label to the revisions of the directories and the managed files in those directories. This means that when you restore a snapshot, the same set of directories gets restored along with the files. In general, when you are working with snapshots, you can ignore the fact that directories have revisions, because the “correct” revision gets selected automatically based on the snapshot label. This is not always true when you assign labels by applying tags. When you assign tags, SOS applies the tags to whatever is selected: files, directories, or both. Assigning tags to directories can lead to some confusing results, because (unlike with a snapshot) it is possible to create an inconsistent environment. For example, if you assign a tag to a directory, and then add a new file to the directory, that file gets hidden when you select the tagged version of the directory in your Revision Search Order. This is true even if the file carries the same tag. For this reason, Cliosoft recommends that you not assign tags to directories. To avoid problems of “disappearing” files in these situations, if you are using tags on directories, the first item in your Revision Search Order should generally be main/dir. This selects the latest versions of the directories. Put

Working with Design Files 61 SOS User Guide tags after main/dir. For example:

Using Branches for Project Variations

Branches are a way of exploring alternate development paths for one or more files. See “Branches” for an overview. You can use branches to explore variations on individual files, or for an entire design. For example, if you have released a design and now want to create a low-power version of that same design, you might create a development branch for the low-power design work. SOS supports two types of branching, which are properties of the branch itself: • File branching, for making experiments with a small number of files while getting the rest of the project files from the main line. When you use file branching, SOS does not automatically branch directories. • Project branching, for creating a variant of the entire project (such as a low- power version of the design). When you use project branching, SOS branches directories as well as files. To begin work on a branch for a design, follow these steps: 1 For file branching, take a snapshot of the project to record the current baseline. See Taking a Snapshot. 2 Define the branch for this project variation. See Defining Bra, next. If you create a project branch, SOS automatically takes a baseline snapshot of the project, based on your Revision Search Order (not the current state of your work area). 3 Set the new branch as the default branch for the project with the Project > Use Branch command. This ensures that all check out operations happen on the branch, unless a designer explicitly specifies otherwise. NoteDesigners that need to work in both the main line and the branch simultaneously should create separate work area directories, with different Revision Search Orders, for the two versions. With this methodology, all changes get recorded on the variant branch without affecting development on the main branch. If you update your work area, you

Working with Design Files 62 SOS User Guide only collect changes made by other users on the variant branch; you do not get changes that other designers have made on the main branch.

Defining Branches for a Project To define a branch: 1 Select Project > Define Branch

You can review the existing branch names for this and other projects with the drop-down lists. 2 Type a new name for the branch. 3 Enter a comment to describe the branch and click Ok. 4 (Optional) Cliosoft recommends that you take a baseline snapshot of the project before adding files to the new branch. For project branches (Branch project option), SOS takes a baseline snapshot automatically, and that snapshot name becomes part of the branch Revision Search Order. 5 If you create a project branch, the Use Branch dialog box appears. Click Ok to begin working on the new project branch, or click Cancel to create the new branch but continue working on the current branch.

Changing the Project Branch for Your Work Area To begin using an already-defined project branch in your work area: 1 Select Project > Use Branch.

Working with Design Files 63 SOS User Guide

2 Choose a branch from the drop-down list box, review the new RSO, and click Ok.

Branching Files When you check out files, you can add them to an existing branch. 1 In the Check Out dialog box, select Create a Branch.

2 Enter a comment explaining the reason for branching the files and click Check Out. SOS updates the flags for the file as shown in the next figure. The feather icon indicates that the file is checked out.

Working with Design Files 64 SOS User Guide

Merging Files to Another Branch When you finish work on a branch and want to bring the changes into the main branch, you should merge the branch. In this example, we have completed work on revision 1 of the high_speed branch and want to merge that revision onto the main branch.

1 Check out the revision on the main branch, making sure that Create a Branch is no longer selected in the Check Out dialog box.

2 Highlight the version of the branch that you want to merge. In this example, there is only one version on the branch.

3 Choose Revision > Merge.

Notice that the From Version is the revision we highlighted, and the To Version is the revision on the main branch that we checked out. If you have

Working with Design Files 65 SOS User Guide

already performed a partial merge, you may need to update the Base Version (see below). 4 Click Automatic. The log message at the bottom of the SOS window confirms the operation. ** Revision 'high_speed/1' of './design_data/digital/OC-UART/ rtl/uart_receiver.v' was merged into revision '2'.

If SOS cannot resolve all of the differences and there are overlapping changes after the merge, SOS reports a warning and annotates the conflicting changes in the file. Edit the file to resolve the conflicts. 5 Check in the file. In the Hierarchy tree, version 1 from the high_speed branch becomes the new revision 3 on the main branch.

Changing the Base Version can be useful if you have already partially merged the changes from a branch into the main branch. Continuing the example above, suppose that you make another change on the high_speed branch and create revision 2 on that branch. To merge that change, you would check out revision 3 on the main branch and merge from revision 2 on the high_speed. branch. By default, the Merge dialog box will show revision 1 as the Base Version, but the changes from revision 1 have already been merged. To improve the results of the merge operation, change the Base Version to 3 so that SOS does not re-evaluate the previously merged changes.

Resolving Conflicts While Merging Directories in SOS 7 If SOS 7 encounters a conflict between the directory in a branch and in the main line, the Merge command fails with a warning message. Follow these steps to resolve the conflict: 1 In a text editor, edit the .sosdir file in the directory where the conflict exists. SOS only creates this file when a conflict occurs during a merge. Each line in the file after the comments on the first few lines represents an object in the directory. The objects for which there is a conflict are commented out. Objects that were merged successfully are not commented out. Here is an example file showing a conflict that occurred because the subdirectory usb3 was replaced by a file of the same name on the branch: 1613:1249:1611:

Working with Design Files 66 SOS User Guide

//1381:usb3:Added:0001/2 //108:usb3:Added:main/(in workarea) //108:usb3:Deleted:0001/2 116:ether 90:i2c 1380:p 192:spi 106:usb2 For the commented-out lines: • The number at the beginning of the line represents the item ID. The larger the number, the newer the item. In the example above, item 1381 is the file named usb3 that replaced the directory of the same name. • The numbers at the end of the line represent the branch and version, respectively. For example, Added:0001/2 indicates that the file was created under the 0001/2 version of its parent directory. • The label (in workarea) indicates that the object is part of the current version in the work area, which is on the main branch. 2 Uncomment the lines for the objects that you wish to keep. 3 Save the file and restart SOS. The Merge successful message appears in the SOS window if there are no remaining conflicts. 4 Check in the objects that had the conflict.

Recording a Manual Merge Use the Record Merge Only button in the Merge dialog box to tell SOS that you have manually merged the changes from the branch. A manual merge is always necessary to merge binary files. A manual merge of text files might be necessary when the code on the two branches is so different that the automatic merge is not successful. Beginning with SOS 7.05, there are two ways to handle a manual merge. The Manual button opens an editor to let you specify how to handle the merge. For

Working with Design Files 67 SOS User Guide files, the editor is the Tkdiff tool. For directories, this dialog box appears:

If you want to perform a manual merge outside the SOS editors, and simply record the merge in SOS, click Record Merge. SOS records the merge without opening an editor.

Overwriting Instead of Merging Use the Overwrite button in the Merge dialog box to tell SOS to simply replace the To revision with the From revision. SOS replaces the checked out file in your work area with the From revision of the file.

Terminating Branches You can terminate individual branched files. You can also terminate an entire branch to prevent check ins and check outs on the branch. Use the second procedure in this section to terminate an entire branch.

Working with Design Files 68 SOS User Guide

When you complete work on a branched file and decide not to merge the changes into the main branch, you can terminate the branch with the Revision > Terminate command to make the status of the file clear to other users. The branch that gets terminated is the branch that has the current revision,

indicated by a green icon. 1 Select any revision on the branch, or select the branch name itself. 2 Select Revision > Terminate.

3 Click Terminate Branch. SOS terminates the current branch. To continue work on a terminated branch, administrators may select the terminated revision, choose Revision > Terminate, and click Activate Branch. To lock an entire branch and prevent files from being checked in to or out of that branch: 1 Select Modify Attrs > Branch. 2 Choose the branch to terminate from the drop-down list box. 3 Select the Terminated check box and click Ok.

Merging Project Branches The Project > Merge Branch command lets you merge files and directories from a source branch to a destination branch. This type of merge operation differs from the Revision > Merge command in that you begin by selecting the source and destination branches, rather than by selecting specific branched files or directories. The Merge Branch command then shows you all the

Working with Design Files 69 SOS User Guide affected directories and files. The interface lets you first select which directories to merge and then select which files to merge to the destination branch. Keep in mind these features and requirements of the branch merge process: ● You can only perform a branch merge on the primary project. ● Before you begin a branch merge, all pending changes in the work area must be checked in or discarded. ● The Merge Branch command updates your work area, if necessary, based on the destination branch that you choose in the first step of the operation. ● Once you begin a branch merge, all other commands that would write to the work area get blocked. You cannot make any other changes to the work area until you complete the branch merge. ● During the merge, you can check if there is any re-merge required for the objects merged with the latest revisions available on the destination branch by clicking the checkIn All button. For the objects that are not merged yet, the destination revision will be updated so you merge with an updated one. Follow these steps to merge branches: 1. Select Project > Merge Branch. The Branch Merge dialog box opens.

2. Choose the Source Branch. 3. Optionally, select Merge revs with label and choose a label if the revisions you want to merge are not the latest revisions on the source branch. 4. If the desired destination branch is not the current branch in the RSO, select a different Destination Branch. Then click OK. The Process Branch Merge dialog box opens.

Working with Design Files 70 SOS User Guide

The list of objects includes all files, directories, links, and packages. 5. Select the directories to merge. Click Directories to filter the list and simplify making your selection. In this first step, the interface only allows you to select directories. 6. Choose a merge option such as Automatic. SOS merges the selected directories and reports any conflicts.

If there are any conflicts, such as a directory that has been renamed or removed, use the Manual command to perform a manual merge of the directories with conflicts. All of the objects that are added on a source branch get marked as New until you merge their parent directory. During the merge, if there are any objects that will not be merged (because you made that choice during a manual directory merge), they get marked as Skipped. After you have merged all of the directories, the Process Branch Merge dialog box updates and you can begin merging the files.

Working with Design Files 71 SOS User Guide

7. Now select the files to merge, optionally using the Files filter to simplify the list.

8. Again choose a merge option such as Automatic. SOS merges the selected files and reports any conflicts. Use the Manual command to resolve any conflicts. SOS uses the merge tool specified in the project preferences. Optionally, use the Conflicts filter to view only the files with conflicts. If the automatic merge did not handle a file correctly, select the file and click Undo Merge. Next, use the Manual, Overwrite, or Record Merge command to properly handle the file. You can use the Edit button to edit selected files, or the Diff button to review changes in a file, before deciding how to handle those files. Note: You must resolve all conflicts and merge all of the files before proceeding to the next step and checking in the files. 9. After you have resolved all conflicts and merged all of the objects, click Checkin all to check in the merged files and directories.

Working with Design Files 72 SOS User Guide

The Checkin all button will check whether there are any latest revisions available on the destination branch and the object needs to be remerged. The object that has the latest revision available gets marked as Remerge. You would need to merge this to complete the merge branch and commit the changes.

SOS takes a merge snapshot after the check in operation finishes. This snapshot name is incremental, so you can merge the same branch multiple times if necessary.

The next figure shows the snapshot name for a merged branch.

Working with Design Files 73 SOS User Guide

Modifying Object Attributes

Attributes are information that SOS stores about files, such as ownership, permissions, and log messages. Revision attributes apply to a specific revision of a file (for example, the check in log comment). File attributes apply to all revisions.

TablSummary of Commands for Modifying Attributes

Attributes Command to Modify Attributes • Revision history log comments Modify Attrs > Revision • Custom attributes • Checkout path Modify Attrs > Checked Out • Checkout log messages • Ownership and permissions Modify Attrs > Source File/Dir • Icon displayed for the file • Trigger for the file • File description

Working with Design Files 74 SOS User Guide

Editing Revision and Custom Attributes To update revision history log comments or any custom attributes that are defined for your project: 1 Begin by selecting the specific revisions of the files and directories that you want to modify. 2 Choose Modify Attrs > Revision.

The example above shows several custom attributes. 3 Make the changes and click Update. For more information about custom attributes, see Defining and Using Attributes in the SOS Administration Guide.

Editing Check Out Attributes To update the checkout path or checkout log message for files that you have checked out: 1 Begin by selecting the files and directories on which to operate. For example, use Select > All Checked Out in Workarea.

Working with Design Files 75 SOS User Guide

2 Choose Modify Attrs > Checked Out.

3 Do one of the following: • To change the check out log message for all of the files, enter the message and click Update All. • If you have moved a work area while files were checked out, and need to change the check out path, modify each path separately and click Update for each file.

Editing File Attributes To update ownership, permissions, icons, triggers, and the file description: 1 Begin by selecting the files and directories on which to operate. For example, use Select > All Below to apply a change recursively.

Working with Design Files 76 SOS User Guide

2 Choose Modify Attrs > Source File/Dir.

If you click Update All, a confirmation dialog lets you choose which attributes to update. Referenced in Projects lists the projects that contain references to the selected directory or file. When you first create a reference to a file, SOS updates this attribute for reference projects. SOS does not automatically remove projects from the list. You can update the list to remove obsolete references. For more information about the Owner, Group, Read Access, and Write Access attributes, see the SOS Administration Guide.

Working with Design Files 77 SOS User Guide 4

Chap WORKING WITH PROJECT DATA AND SETTINGS

This chapter describes the tasks in SOS related to settings, data, and configuration that affects the entire project.

Working with Project Data and Settings 78 SOS User Guide

Managing Tags, Branches, and Snapshots

This section explains how to manage the labels that are defined for a project.

Defining Tags and Branches

To define a new tag, use the Project > Define Tag command. See “Creating New Tags”. To define a new branch, use the Project > Define Branch command. See “Defining Branches for a Project”. NoteYou define new snapshots when you take the snapshot. See “Working with Snapshots”.

Changing Tag, Branch, and Snapshot Descriptions

To change the description of a tag, branch, or snapshot, use the Tag, Branch, and Snapshot commands in the Modify Attrs menu. For example, to change the description of a branch: 1 Select Modify Attrs > Branch. 2 Select an existing branch. 3 Edit the description and click Ok. NoteYou cannot rename or delete labels, but you can hide them. See the next section.

Hiding Unused Labels with the Retire/Activate Label

If your project no longer uses a tag, branch, or snapshot, you can hide the label to simplify the lists of choices in SOS. Hiding a label does not delete it; you can restore the label to the original objects at any time.

Working with Project Data and Settings 79 SOS User Guide

1 Select Project > Retire/Activate Label.

2 Set Label type to match the kind of label you want to hide. 3 Select one or more labels and click Ok. To restore hidden labels, select the Project > Retire/Activate Label command and choose Activate to see a list of hidden labels.

Using Reference Projects

References let you make files and directories that are managed in one project available in other projects. These references appear in the hierarchy trees of the SOS projects that contain the references. This referencing system is designed to accommodate IP libraries, PDKs, or other situations where design data is divided into multiple projects. Depending on how the projects are configured, referenced files may be read-only or writable to designers working in other projects. NoteBy default, new projects are not available as reference projects in other projects. You must explicitly enable references to the new project. For more information about setting up reference projects, see Defining Reference Projects in the SOS Administration Guide. To add a reference to a file or directory from another project into the current project: Working with Project Data and Settings 80 SOS User Guide

1 In the Hierarchy tree, highlight the directory where you want to create a reference to a file or folder in the external project. 2 Select Tree > Add Reference.

3 Choose a Project and click Browse to choose a file or directory. 4 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 directory or file that you want to reference.

Working with Project Data and Settings 81 SOS User Guide

About 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 when you add them to the project with the Create command. In the example, the verilog_file_trigger will be assigned to this Verilog file. This trigger might automatically run a Verilog lint check on the file every time a user tries to check in the file after making an edit.

For more information about triggers, see Using Triggers in the SOS Administration Guide.

Working with Project Data and Settings 82 SOS User Guide

About SOS Access Controls

Access controls let users and project administrators 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. Project administrators can specify which users have access to which files, and also specify which users are allowed to loosen the access controls on files. 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. • 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. You can set access controls on new files when you create them with the Tree > Create command. You can view and (if you have permission) change access controls on existing project files with the Modify Attrs > Source File/ Dir command. In this example, all users have both read and write access to the selected file.

For more information, see Setting Project Access Controls in the SOS Administration Guide.

Working with Project Data and Settings 83 SOS User Guide

Generating Project Reports

Use the Project > Audit Trail command to generate a report about the data management activity that has happened in a project. The are many ways to retrieve information about the files in a project but the Audit Trail report is a means by which you can obtain the history of a project: a chronologically sorted list of all the SOS operations executed on data from a project. You can also generate reports from SOS by invoking a command, program, or script that prints formatted data. Use the SOS command line and the SOS shell command to generate reports. You can use Perl or other languages to create formatted reports. You can also generate reports about the differences between two RSOs, or two time points, by using the soscmd showdiffs command.

Using the Audit Trail Command

You can generate an Audit Trail report from the command line or from the SOS graphical user interface. NoteFor more information about generating reports from the command- line, use these commands to view the online help: soscmd help audit and sosadmin help audit.

Working with Project Data and Settings 84 SOS User Guide

From the SOS window, select Project > Audit Trail to open the Audit Trail dialog box:

The options that control how the report will be generated in terms of the amount of detail and the breadth of the scope, are available at the top of the dialog box. • Use: Can be Entire Project or Selected Paths. This option controls whether the report includes DM activity for the entire project or for a specific path. The second option requires you to select a path in the SOS GUI, before you select the Audit Trail command, but lets you limit the output to the operation on that path or its children. For example, to limit the AT to a particular directory or subtree of the project. • Project/Branch: These options control which project and branch to report about. The branch can be one of the branches defined for that project, or all branches.

Working with Project Data and Settings 85 SOS User Guide

• From/To: These options let you limit the report to a particular time window. • Users (CSV): This a comma separated list of user names that limits the report to the DM operations issued by those users. • Operations: This section lets you generate a report that includes either all of the DM operations or only specific operations. There are additional options in the middle of the dialog box:

These options control the formatting of the report. Group By Transaction defines whether to generate a flat list of DM operations or to group the operations into transactions. A transaction is a group of operations executed as a batch. For example, a user that checks in multiple files at once, may choose to see this as a list of multiple DM operations or group them all in one transaction. Here is an example of a flat list (Group by Transaction is not selected):

Working with Project Data and Settings 86 SOS User Guide

Here is an example of a clustered list (Group By Transaction is selected):

Include Ext Refs: This option is disabled unless you chose Selected Paths above. This option expands the report with the DM operations executed on the reference objects in that path of the project. Report Format: You may select GUI, Html, or Text. The GUI option sends the report to the current window. The Html option generates the report as an external HTML file that opens automatically in your Web browser. The Text option sends the report to a text file. With either the GUI or Html options, you can search and filter the results in the report window.

Working with Project Data and Settings 87 SOS User Guide

Apply: This button generates the report. The GUI format looks like this:

The transactions are listed by rows and can be expanded by clicking on the triangle at the beginning of that row:

Working with Project Data and Settings 88 SOS User Guide

The report has these columns: • Date: The time stamp of the execution of the transaction/individual operation (all the operations in a transaction will have the same time stamp) • User: the user who performed the transaction/operation • Cmd: The operation (SOS command) being executed • File: The file count in a transaction or the individual file affected (when expanding the transaction or viewing as a flat list) • Revision: The affected revision of the file • Summary: the Change Summary property associated with this operation (the first line of the Log property) You can limit the results in the output by typing in the box above the report and clicking Search. The string that you typed in the search box gets searched in the column that you select in the list box to the left of the search box.

Working with Project Data and Settings 89 SOS User Guide

When a transaction affects more than 50 files, for readability, only 50 results are displayed:

To display all the results, click the Show All button inside the transaction. This will display only the results of that transaction:

Working with Project Data and Settings 90 SOS User Guide

Use the Return (Grouped) button to return to the previous view. At the bottom of the window are several buttons:

• Update to Time: Update the work area to the state it had at the time of the time stamp of the currently selected transaction. • Use Previous: This button is only valid after selecting a Check In operation. It reverts the revision of the file affected by that check in to the state it had before the check in operation. • Select: Selects the files from the highlighted transaction in the SOS GUI • Dismiss: Close the dialog box.

Working with Project Data and Settings 91 SOS User Guide

Generating Reports from the Command Line

Here are some examples of how to generate simple reports from the command line. For help using the command line, type soscmd help at the Linux or UNIX prompt.

Example 1: List of Locked Files These two commands print out a list of all files in your work area that are currently locked by any user. The report identifies who has the file checked out and when the file was checked out. Notice that the selections are made first before invoking the shell command. Note also that the shell arguments are enclosed in single quotes; this prevents the arguments from being interpreted by your Linux or UNIX shell. soscmd select -sor -sco -slk soscmd shell echo '$SOS_CheckedOutBy @ $SOS_CheckOutTime :: $SOS_OBJ_PATH'

Example 2: List of Project Files and Current Revisions These two commands print a complete list of the files and directories in the project, together with the revision currently in use in the work area. soscmd select -sr . soscmd shell echo '$SOS_OBJ_PATH Rev: $SOS_CURRENT_REV'

Example 3: List of All Files and Owners These two commands select all of the files in the project and then prints the path and owner for each file. soscmd select -sr . soscmd shell echo '$SOS_OBJ_PATH Owner: $SOS_Owner' NoteTo use environment variables with a Windows server, use this syntax instead: soscmd shell echo '%SOS_OBJ_PATH% Owner: %SOS_Owner%'

Example 4: Checking Information for Specific Files These commands print the check-in information for all of the Verilog files under the current directory. soscmd update -lmain find . -name '*.v' | xargs soscmd select soscmd shell echo '$SOS_OBJ_PATH Rev: $SOS_CURRENT_REV Check in time: $SOS_CheckInTime Author: $SOS_CheckedInBy'

Working with Project Data and Settings 92 SOS User Guide

Comparing Two RSOs

Use the showdiffs command to generate a report about the differences between two RSOs, either at the current time or between specified points in time. The report lists objects that have been added, deleted, renamed, or moved. When you run the command from within a work area directory, the syntax is: soscmd showdiffs [-frsoLabel1[,Label2...]] -trsoLabel1[,Label2...] [-ftime"time" -ttime"time" ] [-op{add | del | upd | nop}] [-fmt{txt | csv | csv:noheader}] where frso is the “from” or source RSO, trso is the “to” RSO, ftime is an optional starting time, and ttime is an optional end time. By default, frso is the current work area RSO. If you omit -op, the default is to report all changes. If you omit -fmt, the default format is txt. For example: soscmd showdiffs -frsomain -trsob1,main soscmd showdiffs -frsomain -trsob1,main -ftime"02/02/2017" -ttime"04/02/2017" -fmtcsv:noheader soscmd showdiffs -frsomain -trsob1,main -ftime"02/02/2017" -ttime"04/02/2017" -fmtcsv:noheader -opadd You can also run showdiffs from the sosadmin command line; in this case, the first two arguments must specify the server name and project name: sosadmin showdiffs server project ... Here are some examples working from the sosadmin command line: sosadmin showdiffs server project frso trso format ftime ttime sosadmin showdiffs dev dev1 main b1,main csv For more information, see the command-line help.

Managing Related Files as Packages

A package is a group of related files that you can manage as a single object in SOS. The main use for packages is in SOS integrations with design tools, where a single block or cellview consists of several related files that need to be managed together. When you populate your work area with a package, all of the files that comprise the package get copied or linked to your work area. Packages contain only files, not directories.

Working with Project Data and Settings 93 SOS User Guide

Creating a New Package

You create packages from unmanaged files. To create a new package: 1 Select the files in the Hierarchy tree. Usually the files will be in the same directory, but this is not a requirement. 2 Select Tree > Pack.

3 Optionally, highlight additional files and click Add Selected to include those files in the package. 4 Enter a name for the package in the Package Name field. 5 Optionally, remove the trailing directory name from the Package in Directory value to move the package up one level in the hierarchy. In the example above, we want the package to be located in the inv8a folder, not a schematic sub-folder of inv8a, so we have deleted /schematic from the Package in Directory default value, 6 Click Pack. The next figure shows the result for a package named

schematic. The individual files in the package disappear from the Hierarchy tree, replaced by the package. 7 Add the package to SOS by selecting it and choosing Tree > Create File/Dir. The next figure shows the result in the Hierarchy tree. SOS created revision 1 of the package. Working with Project Data and Settings 94 SOS User Guide

Unpacking a Package

Before you add a package to SOS, if you decide you have packaged the wrong set of files, you can unpack it. This makes the package files appear as regular unmanaged files in the Hierarchy tree again. To unpack a package, select it and choose Tree > Unpack.

Changing the Contents of a Package

You can add or remove files from packages after you create them in the SOS repository. 1 Check out the package. 2 Select Tree > Edit Package. 3 To add files, select them in the Hierarchy tree and click Add Selected. 4 To remove files, select them in the Edit Package dialog box and click Remove. 5 Click Update to finish. SOS creates a new revision of the package.

Listing the Contents of a Package

To view a list of the files in a package, use the History command. 1 Right-click the package and choose History. 2 Scroll to the bottom of the window and look for the PackageList line below the change_summary: Initial revision line. (If you have modified the contents of the package, look for the most recent PackageList line.) Here is an example. change_summary: Initial revision. Log: Checksum: 2708229515 PackageList: data.dm master.tag sch.oa

Working with Project Data and Settings 95 SOS User Guide 5

Chap MANAGING FILES WITH THE WEB INTERFACE

This chapter explains how to manage files with the SOS Web interface. For installation instructions, system administrators should read the file $CLIOSOFT_DIR/web/README.

Managing Files with the Web Interface 96 SOS User Guide

Overview

The SOS Web interface lets you perform basic design management tasks in your Web browser: • Add files to projects and delete files from projects. • Download project files for viewing, and check files in and out for editing. • Cancel checkouts and clear locks on files. • Add tag labels to files. • Compare revisions of text files. FiguSOS Web Interface (Project View)

When you use the Web interface, you do not have your own personal SOS work area. The Web interface simply lets you upload and download files to and from locations that you specify. To change a file, you check out the file to place a lock in the repository, and then download the file to any location that you choose on your computer. After you finish editing the file, you can select the modified file to upload and check in.

Managing Files with the Web Interface 97 SOS User Guide

When to Use the Web Interface

The Web interface is most useful for editing and managing documentation files on Mac or Windows PCs, and for managing (but not editing) design files. Use the Web interface when you do not need a complete work area with all of the design data. Although you can edit design files through the Web interface, verifying changes is more practical in a work area that you manage with the SOS application (either the standalone application or the SOS integration with your design tools). The Web interface is also useful when you need to access files from a PC where the SOS software is not installed.

Limitations of the Web Interface

The current release of the Web interface has these limitations: • You can view the tags on the current revision of a file, but not on older versions. • Only PAM authentication is supported. • You can view packages, symbolic links, and directories, but you cannot download, check out, or delete these object types.

Getting Started

1 Ask your system administrator for the Web server URL and open that page in your Web browser. If you are prompted to log in, enter your Linux credentials.

Managing Files with the Web Interface 98 SOS User Guide

The starting page lists the projects for which someone has already created shared Web work areas.

2 If you cannot find your project in the list, follow these steps to create the Web work area: 1 Click Create WorkArea. 2 Highlight an SOS server and click Select Server. 3 Highlight your project and click Select Project. 4 Click Create Work Area. 5 Wait a short time while SOS populates the Web work area. 3 Highlight a project and click Go to Project. The window updates to show the project hierarchy tree on the left and the file management menu on the right (SOS Web Interface (Project View)). NoteIf the menu does not contain the editing commands such as Create, Check Out, Check In, and Tag, your system administrator limits the Web interface to read-only mode. You can view files, view their revision history with the History command, and run the View Diff and View Tag commands.

Managing Files with the Web Interface 99 SOS User Guide

Adding Files to a Project

1 Select a project folder in which to add either a single file or a zip archive that contains multiple files. 2 From the menu, click Create. 3 To upload a single file, click Browse, select the file, and click the Create button. 4 To upload the contents of a zip archive as a new directory: 1 Click Directory and then click Browse. 2 Select the zip archive and click the Create button. 3 Refresh your browser window to see the new directory in the tree.

Viewing and Editing Files

To view a text file in a new tab of your browser, click the View ( ) button next to the file name. To check out a file and download it: 1 Highlight the file and click Check Out. 2 In the Log box, write the reason for checking out the file.and click Checkout. 3 Click the link to download the file. 4 Use the commands in your operating system to locate the downloaded file and open it in a text editor. NoteFiles are downloaded to your Web browser downloads folder, not to a work area directory.

Checking In Modified Files

1 Select the edited file in the Web interface. 2 Click the Checkin button. 3 Click Browse and choose the edited local file on your computer to upload. 4 Enter a Log message. 5 Click Upload and Checkin.

Managing Files with the Web Interface 100 SOS User Guide 6

Chap USING THE COMMAND LINE INTERFACE

This chapter explains how to use the SOS command line interface.

Using the Command Line Interface 101 SOS User Guide

Overview

You can use the SOS command line interface to run SOS in a terminal window, or from scripts. The syntax is soscmd command [arguments] Online help is available from the SOS command line. For a list of commands, type soscmd help. For detailed help about a particular command, type soscmd help command. SOS CLI Command Summary gives a brief description of each command.

TablSOS CLI Command Summary

Command Description addreference Add a reference object to the project. audit Show the audit trail for the project. ci Check in the selected objects. co Check out the selected objects. create Add a new file or directory to the project. definebranch Declare new branches. definetag Declare new tags or modify existing tags delete Delete an existing file or directory. deleterev Permanently delete the selected revision. deleteworkare Delete the SOS work area. a diff Show the differences between 2 revisions. dirrev Toggle the display of directory revisions. discardco Discard the check out of the selected objects. displaytmp Toggle the display of unmanaged objects. editreference Sets the RSO for this sub-tree to be different from that of the project RSO. exitsos Exit the SOS session running in this work area. expand Expand or collapse directories in SOS.

Using the Command Line Interface 102 SOS User Guide

exportrev Create a copy of the selected revision with a different name. findwaroot Print the root path of the current work area. gui Switch to graphical mode. help Print help. history Show history. merge Merge a revision of a file into the checked-out revision. modattr Modify an existing attribute value or add a new attribute. move Move objects to another directory. neverpopulate Mark the specified directory to never be populated in this work area. newworkarea Create a new work area. nobjstatus Show the status and attributes of the specified objects. nogui Switch to non-graphical mode.

objstatus Show the status and attributes of specified object. pack Manage an SOS package object. populate Populate the specified directory. preference Set or print user preference settings. print Print a message in the SOS message window. query Get project-specific information from SOS. rename Rename an existing file or directory. retirebranch Retire or activate an existing branch. retiresnapsho Retire or activate an existing snapshot. t retiretag Retire or activate an existing tag. revertrev Revert the latest revision back to a previous revision. select Select objects. shell Execute a shell command.

Using the Command Line Interface 103 SOS User Guide

showdiffs Generate a report about the differences between two RSOs. showlabels Show all of the revisions in the repository that match the specified labels. snapshot Take a snapshot. status Show status and version information for this work area. tag Tag a revision with the specified name. termbranch Terminate or activate a branch on a file or directory. undelete Undelete objects from a specified directory. unpopulate Unpopulate the specified directory. unselect Remove objects from the current selection. update Update the work area. updatesel Update the selected objects in the work area. userev Bring the selected revision into the work area.

Selecting Objects

The select command selects objects in SOS. By using the command options and regular expressions, you can make very complex selections. Because the command line and the SOS window use the same SOS process (session), you can make a selection on the command line and then operate on that selection from the SOS window. You can use the select command options with any command that accepts multiple selections. For example, here is a two-command sequence that checks in all of the checked out files: soscmd select -sco . soscmd ci -aLog="Fixed issue id 5423" Cliosoft recommends that you instead use the select command options together with the ci command: soscmd ci -sco -aLog="Fixed issue id 5423" For more help on the select command, type soscmd help select.

Using the Command Line Interface 104 SOS User Guide

Using Environment Variables

When you run a command, SOS sets environment variables with names that begin with the prefix SOS_. These variables carry information about the selected object and its attributes. You can print the values of these environment variables or use them as arguments to any shell command or script. For a list of predefined attributes, see Predefined Attributes in the SOS Administration Guide. To print a list of all of the environment variables that SOS sets, select an object and use this command: soscmd shell printenv | grep SOS_

Examples

Reverting Multiple Files Based on a Label

You can make a selection based on a tag or snapshot label and revert those objects back to the revision that matches the label. 1 Run the select command to select all tagged revisions. soscmd select -slbllabel_name relative_path_to_directory where relative_path_to_directory is the relative path to the directory that contains the objects you want to revert. 2 Generate a script file by running this command: soscmd shell echo 'soscmd revertrev -rev$SOS_SELECTED_REV \ $SOS_OBJ_PATH' > revert.sh The output file revert.sh will contain a series of revertrev commands similar to this example: soscmd revertrev -rev3 ./dirname 3 Execute the script to revert the objects to the revision that matches the label: source revert.sh

Reverting All Files Checked In After a Date to the Last Revision Prior to That Date

1 Roll back your work area to the point in time just before the check ins: soscmd update -ttime 2 Select all of the objects that were checked in after that time: soscmd select -snl 3 Run this command:

Using the Command Line Interface 105 SOS User Guide soscmd shell echo 'soscmd revertrev $SOS_OBJ_PATH -rev$SOS_SELECTED_REV' > /tmp/revert.sh The output file revert.sh will contain a series of revertrev commands similar to this example: soscmd revertrev -rev3 ./digcore.v 4 Execute the output file: source /tmp/revert.sh

Using the Command Line Interface 106 SOS User Guide 7

Chap USING SOS ON WINDOWS PCS

This chapter explains the differences between SOS on Windows PC and SOS on Linux or UNIX platforms. NoteFollow the instructions in the Software Installation and Licensing chapter of the SOS Administration Guide to install and configure SOS on Windows. During installation, be sure to configure licensing so that the Windows SOS client can communicate with the license server. Also be sure to specify the list of SOS servers during the installation process.

Using SOS on Windows PCs 107 SOS User Guide

About SOS in the Microsoft Windows Environment

The SOS client software is supported on several versions of the Microsoft Windows operating system. For installation instructions and a list of supported Windows versions, see the SOS Administration Guide. The installation process includes using the sosadmin application on your PC to specify the host and communication settings for the SOS server software. After installing the SOS software on your Windows PC, the SOS folder appears in your Windows Start menu. FiguSOS Menu in the Windows Start Menu

NoteThe folder name includes the SOS software version number. For simplicity, command examples in this chapter show the folder name as simply SOS. The SOS menu contains the following commands:

Command Description FlexNet Utilities Set up SOS software licensing on a Windows host. This is not common; most organizations set up licensing on a Linux host. See the SOS Administration Guide. Register Explorer Install the SOS plug-ins for browsing the SOS repository plugins using Windows Explorer. See SOS.

sos help Show the online documentation. sos Start the SOS client software. sosadmin Start the SOSAdmin software, for identifying your SOS server and other administration tasks. See the SOS Administration Guide.

Using SOS on Windows PCs 108 SOS User Guide

uninstall Uninstall the SOS software. Unregister Uninstall the SOS plug-ins for Windows Explorer. Explorer plugins

NoteTo work with SOS, the SOS server on the remote system must be running and the sosadmin software on your PC must be configured to communicate with that server.

Differences with UNIX and Linux

There are a few differences in how the SOS user interface works in Windows, compared to UNIX and Linux: • On Windows, symbolic links are shown as files.

SOS Windows Explorer Plug-Ins

You can perform many SOS file management tasks with the SOS Windows Explorer plug-ins. This section explains how to install and use the plug-ins.

Installing the Windows Explorer Plug-Ins

1 From the Start menu, choose SOS > Register Explorer Plugins (beta). 2 Click Yes in the confirmation dialog. 3 When prompted to restart Explorer, click Yes to restart now or No to restart later. Restarting Explorer will close all open Explorer windows.

Browsing Files in Your Work Area

With the SOS plug-ins installed, you see SOS status icons for files and directories while you browse the files in your work area. FiguBrowsing Files with the SOS Plug-Ins

The next table shows the icons that SOS uses to show file status in Windows Explorer.

Using SOS on Windows PCs 109 SOS User Guide

TablIcons for File Status

Icon Description Checked in Note: files that show this icon may be out of date. Checked out

Locked

Unmanaged files do not display any icon.

Using the Windows Explorer Plug-Ins

1 In Windows Explorer, browse to your SOS work area. 2 Right-click a file that you want to manage, choose SOS Utilities, and select a command.

The next table describes the commands.

Command Description Check Out Check the file out for editing. Check In Check in the changes to a file. Discard Checkout Cancel a checkout, discarding all changes to the file. Pending Checkins Show all files and directories that are checked out in the work area. Diff Show a diff of the object. Update Selected Files Get the appropriate versions of the selected files, based on your Revision Search Order. To set the Revision Search Order, use the SOS client application.

Using SOS on Windows PCs 110 SOS User Guide

Update Workarea Get the appropriate versions of all files in your work area, based on your Revision Search Order. Open SOS Start the SOS client application.

Using Commands First select the files and then select a command from the menu. The command dialog boxes show the selected files and directories.

Using SOS on Windows PCs 111 SOS User Guide 8

Chap USING SOS WITH JENKINS

You can use the Jenkins open source automation server to automate deploying builds from an SOS repository and performing tasks such as running simulations. This chapter explains how to install and use the SOS Jenkins plugin.

Using SOS with Jenkins 112 SOS User Guide

Installing the Jenkins Plugin

1 Ensure that the account running the Jenkins system can access the SOS system and can create work areas. This is typically a dedicated Jenkins account. This account should have access to the SOS installation. The account does not need access to the repository, only the ability to create work areas. 2 Log in to Jenkins as an administrator. 3 From the Manage Plugins screen, choose the Advanced settings. 4 Upload the plugin file from this location: $CLIOSOFT_DIR/adaptors/jenkins/SOS-plugin.hpi 5 Restart Jenkins.

Using SOS with Jenkins 113 SOS User Guide

Configuring the Jenkins Plugin for an SOS Project

Configuring Jenkins to access an SOS project is similar to defining a new work area in SOS.

1 In Jenkins, from the Source Code Management page, choose Configure Project. 2 From the list of plugins under Source Code Management, choose SOS. 3 For CLIOSOFT_DIR, specify the path to the top of the SOS software installation. 4 For License Variable, specify a FlexNet license file. The value should match your value for CLIOLMD_LICENSE_FILE, if you use that environment variable in your SOS setup. If the Cliosoft licenses are specified by the LM_LICENSE_FILE environment variable, enter that value instead.

Using SOS with Jenkins 114 SOS User Guide

5 For Workarea ID, enter a unique identifier for this Jenkins workspace. This identifier need not match the SOS server or project names, but if the workspace contains only a single SOS project, Cliosoft recommends that you use the same name for both. 6 Specify Server, Project, and Project Root as you would for a new SOS work area. The server and project names must match the names that are specified in SOS. For help, see Setting Up Your Work Area. 7 Specify the Project RSO (Revision Search Order) as a list of SOS tag, branch, or snapshot names preceded by the -l (label) flag in this format: -lSOS_label1 [-lSOS_label2 ...] Typically, the last (rightmost) label in the list is the name of the main branch. 8 Select Use timestamp to update workarea if you want to define a build based on a previous point in time, rather than applying the RSO to the most recent files in the project. 9 If the Jenkins workspace will contain more than one SOS project work area, specify a subdirectory of the workspace for this project in Workarea path relative to Jenkins workspace. 10 In Populate path list, specify the directories to populate. By default, all of the files in the SOS project get copied to the Jenkins workspace. Use this option to limit what gets copied to a specified list of directories. 11 Similarly, in Never populate path list, list the directories and subdirectories that should not be copied to the Jenkins workspace. 12 Click Save to commit the project configuration.

Setting Build and Rebuild Options

At the bottom of the Source Code Management page are two options that modify the build process. • Choose Show soscmd output to display SOS messages during the build. • Choose Rebuild workspace from scratch to delete and recreate the project directory in the Jenkins workspace. NoteChanging some of the options on the Source Code Management page triggers a complete rebuild of the workspace. Before starting the rebuild, Jenkins displays a warning.

Using SOS with Jenkins 115 SOS User Guide

Reporting About Changes in the Build

The Jenkins change log shows what changed in your Jenkins workspace during the previous build. This is essentially the same information that the SOS update command reports. You can click on the hyperlinks to view the updated files. When you create a build for the first time, or the work area gets completely rebuilt for any reason, the change log lists every file in the work area.

The SOS Jenkins plugin sets the SOSSCM_CHANGES_Workarea_id environment variable to summarize the changes after each build.

Value Meaning 0 Nothing in the work area changed during the update. 1 The work area had some changes. 2 The work area was completely rebuilt.

Using SOS with Jenkins 116 SOS User Guide 9

Chap SETTING PREFERENCES

This chapter explains how to set SOS preferences.

Setting Preferences 117 SOS User Guide

Overview of SOS Preferences

There are three ways to set SOS preferences: • With the File > Preferences and File > Project Preferences commands in the SOS window • From the command line, with the soscmd preference command. • With environment variables

Setting Preferences 118 SOS User Guide

General SOS Preferences

You set general SOS preferences with the Preferences dialog box

The next table shows the preference options, including the field names in the dialog boxes and the keywords for setting the preferences on the command line or as environment options. Use the numeric preference values on the command line and in environment options. The sections after the table explain how to set these options.

TablSOS Preferences

Preference Description and Default Value

Setting Preferences 119 SOS User Guide

Directory for CRs This legacy option is not used when you integrate CRS_DIR SOS with third-party issue tracking software. In early versions of SOS, this option set the name of the directory for managing change requests in the Cliosoft proprietary issue tracking system. The value should be a path relative to the root of the work area. The default is CRs. Automatic Update Controls whether automatic updates apply to just the AUTO_UPDATE_PROJ project in which you are currently working, or also to ECT all reference projects. Select No (0) to only update the active project. Select Yes (1) to also update reference projects. The default is No. Automatic Update Controls whether automatic updates retrieve copies or What links to updated files, or only retrieve updated status AUTO_UPDATE_TYPE icon values and attribute values. Select Changed Files & Dirs (1) to retrieve updated files as well as updated status icon and attribute values. Select Flags & Attributes (0) to only retrieve flag and attribute values. The default is Flags & Attributes, which means that after an update you see the current status icons for all of the files. Review the status icons and then decide whether to manually update your work area with the changed files. Automatic Update Controls whether and when to automatically update When (repopulate) your work area with changed files and AUTO_UPDATE metadata. Enter a value in minutes to automatically update your work area after your SOS client has been idle for that amount of time. Select Immediate (-1) to automatically update your work area immediately when a files changes on the server. Select No (0) to disable automatic updates. The default is 60. Keep data newer than Controls whether to keep files that you checked in that RSO are newer than the version selected by your RSO during automatic updates of changed files and directories. By default, those newer files are replaced during an automatic update. Updated files, Controls how to handle files that you have modified in modified without your work area without checking them out in SOS. checkout Select Yes (1) to update these files and rename the UPDATE_IF_WRITE modified file to have an .SVM extension. Select No (0) to skip updating files that you modified outside of SOS. The default is Yes (1).

Setting Preferences 120 SOS User Guide

Checkout lock option Controls how and whether to lock files when you for files check them out. Select Concurrent Lock (2) to CO_LOCK_OPTION enable concurrent checkout (the -C option to the co command). Select NoLock (1) to not lock the file (the -Nlock option to the co command). Select Lock (0) to lock the file on the server. The default is Lock. Editor Command Sets the editor for text files. The default is vi on EDITOR UNIX. For Windows, SOS chooses the default application based on the file name extension. See $CLIOSOFT_DIR/adaptors for customization files for the emacs and vim text editors. Alternate Servers Path Shows the path to the SERVERS directory, if you SERVERS_DIR overrode the default path by setting the $SOS_SERVERS_DIR environment variable before you created your work area. You cannot change this value after you have created the work area.

Setting Preferences 121 SOS User Guide

‘diff’ Command Sets the options for the diff command, or sets a DIFF_OPTIONS different command name (with options) for performing diff operations on text files. To set a different utility name, enter that name followed by the necessary options. Use the keywords @1 and @2 to pass file names to the command. Use the keywords @L1 and @L2 to pass labels. For example, if your diff utility has the command syntax mydiff -L label1 -L label2 -file1 file1 -file2 file2 specify the command as mydiff -L @L1 -L @L2 -file1 @1 -file2 @2 The keywords @L1 and @L2 will be replaced by the full pathname to the file and the revision number. For example, if you are comparing ./rtl/uart_recv.v revision 4 with the revision high_speed/2: @L1 = "./rtl/uart_recv.v -- 4" @L2 = "./rtl/uart_recv.v -- high_speed/2" These appear as the header of the two diff’ed files in the diff tool, to clearly indicate which files and revs are being diff’ed. The default is -w, which uses the standard UNIX or Linux diff utility and ignores whitespace when comparing lines. Type man diff on the UNIX or Linux command line for help using the standard diff utility. Display Automatic Controls whether to open a status dialog box for Flags Update Status automatic updates of attributes and flags. Select Yes Popup (1) to display the dialog box. The default is No (0). AUTO_POPUP Log soscmd Controls the level of detail to use when logging command commands in the sos.log file. Select Complete LOG_CMD_NAME cmd (2) to log the command and all of its arguments. Select Cmd name only (1) to log only the command name. Select No (0) to disable command logging. The default is Cmd name only. Popup update Controls whether to open a dialog box with a summary summary of work area updates. Select Yes (1) to display the UPDATE_SUMMARY dialog box. The default is Yes (1).

Setting Preferences 122 SOS User Guide

Hide excluded files Controls whether to display files in the exclude list HIDE_EXCLUDED in the sos.cfg file. Select Yes (1) to hide those files in the SOS user interface. Select No (0) to show those files. The default is Yes. For more information, see the SOS Administration Guide. Keyword substitution Controls whether RCS keyword substitution is enabled KEYWORD_SUB on ASCII files. Keyword substitution has no effect on binary files. You can control RCS keyword substitution on a file-by-file basis with the Keyword substitution option in the Create File/Directory dialog box.

Setting Preferences 123 SOS User Guide

SOS Project Preferences

Each project may have different values set for the project preferences.

TablProject Preference

Preference Description and Default Value Default Group Specifies the group name to use for newly-created objects. If you do not set a value, SOS uses the DEFAULT_GROUP default group specified for your user name in the sosd.cfg file. To override that value, choose an existing group from the list. Default Branch Specifies which branch to use for checkouts. If you do not set a value, files get checked out on their current DEFAULT_BRANCH branch. Choose an existing branch name from the list to ensure that all of your work gets checked out on that branch. Branch directories Controls whether to check out and branch directories also on the default branch. If you branch the directories, users working with the main branch will not see file BRANCH_DIRS additions or deletions on the branch. Seeing those changes might be helpful or distracting to main branch users, depending on the situation. For changes that are not likely to be merged into the main branch, you may not wish to distract main branch users with those changes; in this case, branch the directories also. For example, users working on the next major release of a design might have no interest in seeing the changes in the low power branch for the previous release. Do not branch the directories if main branch users might want to see the changes that you are making on the branch. For example, if you are working on a bug fix, or any other change that will eventually get merged back to the main branch, other users may be interested in seeing what files are being added and deleted. For more information about branches, see “Using Branches for Project Variations”. Select Yes (1) to branch the directories. The default is No (0).

Setting Preferences 124 SOS User Guide

Setting Preferences 125 SOS User Guide

Using Environment Variables to Set Preferences

There is an environment variable for every SOS preference and project preference. To set or check preferences using environment variables, prepend SOS_ to the preference names in SOS Preferences and Project Preference. For example, to set the Default Branch project preference in the C shell: setenv SOS_DEFAULT_BRANCH low_power_branch Changes to preferences in your environment take effect the next time you start SOS.

Setting Preferences 126