Sun WorkShop TeamWare: User's Guide: 1 - QuickStart

# QuickStart | # 1 |

Use this chapter to quickly get started using Sun WorkShop TeamWareTM. For more details, see the other parts of this guide. Also refer to the online help for immediate assistance in completing specific tasks.

This chapter contains the following sections:

Basic Concepts | page 1
Versioning | page 7
Freezepointing | page 9
Distributed Make | page 11

## Basic Concepts

TeamWare is based on a concurrent development model called Copy-Modify-Merge. Isolated (per developer) workspaces form the TeamWare model. A workspace is a specially designated UNIX directory and its subdirectories. With TeamWare, you copy source from a central workspace into your own workspace, modify the source, and merge your changes with changes made by other developers in the central workspace.

Besides providing isolated workspaces, TeamWare enables you to easily and intelligently copy files between workspaces and then merge changes that exist between corresponding files. The intelligent copy feature enables you to copy project files in groups that you (or the project administrator) determine are logically linked, and automatically determines differences between files in the originating workspace and the destination workspace.

TeamWare further assists the concurrent development process by determining whether differences exist between the files in the central workspace and your workspace. If differences are found to exist, TeamWare commands prevent you or another developer from copying over those changes; TeamWare then provides sophisticated window-based tools that help you to merge these differences.

### Parent and Child Workspaces

When you copy files from a central workspace to create a new workspace, a special relationship is created between the central workspace and the new one. The central workspace is considered the parent of the newly created child workspace. You can acquire files from any Configuring workspace in this manner, and workspaces can have an unlimited number of children. The portion of the file system that you copy from the parent workspace is determined at the time you copy it. You can copy the entire contents of the parent to the child, making it a clone of the parent, or you can copy only portions of the file system hierarchy that are of interest to you. The TeamWare Configuring transaction used to copy files from a parent workspace to a child workspace is called Bringover.

When development and testing are complete in the child, you copy changes in files that were modified or added in the child, back into the parent workspace. Once the altered files are present in the parent, they can be copied by other children or passed up another level to the parent's parent workspace. The TeamWare Configuring transaction for copying changes in files from a child workspace to a parent workspace is called Putback.

If any of the files you attempt to put back are changed in both the parent and child workspace, the files are in conflict. If this is the case, Configuring will block the transaction. You must then use the Bringover transaction to bring over the changed information from the parent and use the Resolve transaction to resolve the conflict in the child workspace before you can put your work back to the parent.

### Source Code Control System

TeamWare Configuring acts only upon files under the source code control system (SCCS). When considering Configuring file transfer transactions, remember that source files are derived from SCCS deltas and are identified by SCCS delta IDs (SIDs). When a file is copied by either a Putback or Bringover transaction, Configuring acts upon (copies or merges) the file's SCCS history file (also known as the "s-dot-file"). How Configuring manipulates and merges the history files is described in Chapter 11, "How the Configuring Program Merges SCCS Files."

### Changing Names

The current release of TeamWare uses new command names, so Table 1-1 summarizes the correspondences for you. Note that the old commands still work, however this manual uses the new commands and GUI names.

#### Table 1-1 Correspondences Between Old and New TeamWare Commands

Old Command | New Command | Old Tool Name | New GUI Name
codemgrtool | twconfig, teamware | CodeManager | Configuring
vertool | twversion | VersionTool | Versioning
filemerge | twmerge | FileMerge | Merging
maketool | twbuild | MakeTool | Building
freezepttool | twfreeze | FreezePoint | Freezepointing

| ### Getting Started

You can use TeamWare Configuring through either a graphical user interface (GUI) or command-line interface (CLI). The following procedures use the GUI. For information about the CLI, refer to the `bringover`(1) and `putback`(1) manual pages.

> Note - Before you begin using TeamWare Configuring on your project, you must know the path name of the workspace from which you are to bring over your work.

| ### Creating a New Workspace

  1. From a command prompt start the Configuring GUI:

      % twconfig &

  2. If the workspace from which you must obtain your files is not automatically loaded, load the workspace using the Load item from the File menu.

  3. Once you load the workspace, use the Bringover Create transaction to create your own workspace. Your workspace is a child of the original workspace. You initiate the transaction by dragging and dropping the parent workspace icon into an open area of the pane. This activates the Bringover Create version of the Transactions window.

  4. In the Bringover Create Transactions window, enter the child workspace path name in the text field labeled: To Child Workspace Directory.

  5. In the Directories and Files text pane, create the list of directories and files you wish to bring over to your workspace from the parent workspace. Select all files to bring over by accepting the default "." or choose File Add Files to create the Directories and Files list. Optionally: Select the Preview option to verify your transaction before you actually transfer any files.

  6. Click on the Bringover button at the bottom of the window to initiate the transaction.

  7. View transaction output in the Transaction Output window.

    For more information about the Bringover Create transaction, see "Creating a New Child Workspace (Bringover Create)" on page 90."

| ### Changing Files in the Child Workspace

  1. To change files in a child workspace, you need to start Versioning. Refer to "Starting Versioning" on page 7.

  2. The files must then be checked out, edited, and checked back in under SCCS. Refer to "Checking Files In and Out of SCCS" on page 8.

| ### Putting Back Changes to the Parent

  1. Update the parent workspace with the changes you make.

    This Configuring transaction is called Putback.

  2. Initiate Putback transactions by dragging and dropping your child workspace icon onto the parent workspace icon. This step activates the Putback version of the Transactions window.

    Configuring automatically fills in the names of the parent and child workspaces in the Putback Transaction window and includes the same directories and files that you included when you created the child workspace.

  3. Type a comment in the Comments text window. Optionally: Select the Preview option to verify your transaction before you transfer any files.

  4. Click on the Putback button at the bottom of the window to initiate the transaction.

  5. Delete selected workspaces.

  6. View transaction output in the Transaction Output window.

    For more information about the Putback transaction, see "Updating a Parent Workspace Using Putback" on page 100."

| ### Updating the Child Workspace

If any of the files have changed in the parent since you brought them over, the Putback transaction is blocked. In this case, you will have to use the Bringover Update transaction to bring those changes into your child workspace.

  1. Resolve any conflicts.

  2. Test.

  3. Put them back to the parent.

    A popup window advises you that the transaction is blocked.

  4. Initiate the Bringover Update transaction by clicking on Bringover now in the popup window. Optionally: Select the Preview option to verify your transaction before you transfer any files.

    This activates the Bringover Update version of the Transactions window. In the Bringover Update Transactions window, Configuring automatically fills in the names of the parent and child workspaces, and includes the same directories and files that you included when you created the child workspace.

  5. Click on the Bringover button at the bottom of the window to initiate the transaction.

  6. View your transaction output in the Transaction Output window.

    For more information about the Bringover Update transaction, see "Updating an Existing Child Workspace (Bringover Update)" on page 94".

| ### Resolving Conflicts

If any of the files you changed in your child workspace were also changed in the parent workspace, they are in conflict. If Configuring discovers any conflicts during the Bringover Update transaction, it automatically activates a popup window advising you of this.

  1. Initiate the Resolve transaction by clicking on Resolve now in the popup window.

    This step activates the Resolve version of the Transactions window. Configuring automatically alters the workspace icon to alert you that a workspace contains unresolved conflicts. Configuring automatically:

  - Lists the path names of the files that are in conflict in the Resolve Transaction window
  - Starts the Merging program, loading the first file in the list

  Merging displays two text files (the versions of the file from the parent and child workspaces) for side-by-side comparison, each in a read-only subwindow. Each version is shown in comparison (using glyphs) to the version that existed before the changes were made. Beneath them, Merging displays a subwindow that contains a merged version. The merged version contains selected lines from either or both deltas.

  Merging automatically merges the files for you in the bottom window. If you disagree with the choices made by the program:

  2. Use the Left and Right buttons to accept the changes found in the left or right window.

  3. When you merge the files, select the Save button to save the file.

    If there are more files in the Transactions window conflict list, Configuring automatically loads the next file in the list into Merging.

    For more information about resolving conflicts and merging files, see Chapter 9, "Resolving Conflicts".

## Versioning

Versioning is a GUI to SCCS that enables you to manipulate files and perform SCCS functions without having to know SCCS commands. It provides a way to check files in and out, and to display a file's delta history and show differences between deltas. With Versioning, you can do the following:

- Check out a version of the file for editing
- Check in files
- Retrieve copies of any version (delta) of a file
- Visually peruse the branches of an SCCS history file
- Back out changes to a checked-out copy
- Display differences between selected deltas using Merging
- Display the version log summarizing executed commands
- Create new SCCS files

| ### Starting Versioning

To start Versioning, enter the command as shown:

    demo% twversion &

> Note - Versioning can also be started directly from the Configuring GUI by double-clicking on a workspace icon.

To use Versioning, select a file (or group of files) in the File List pane and choose a menu item to operate on it. Commands are located in the:

- Commands menu
- View menu
- File List pane floating menu

Following are two examples that describe how to use Versioning to check out and check in files, and to view and compare a file's delta history.

| ### Checking Files In and Out of SCCS

  1. From a command prompt start Versioning: `

      % twversion &

  `

  2. If the directory that contains your file is not automatically loaded, you can type the directory path name (followed by Return), in the Directory text field.

  3. Click on a file icon to select a file; use the ADJUST mouse button to extend the selection.

  4. Choose either Checkout Default or Checkout Check Out and Edit from the Commands menu. As the files are checked out a check mark appears in their icons.

  5. When you are ready to check the files back in, select the file(s) and choose Check In from the Commands menu.

    This activates the Check In popup window.

  6. Enter a comment in the text window that describes your changes and click on Check In to complete the check in process.

    The check mark is removed from the file icon as the files are checked in.

| ### Viewing and Comparing a File's Delta History

  1. To view a graph of a file's delta history, select the file's icon in the main window and choose File History from the View menu.

  2. Select two deltas in the graph.

  3. Choose Use Merging from the Differences menu.

    Merging displays the two deltas side by side, marking differences with glyphs. For more information about Merging, see Chapter 11, "How the Configuring Program Merges SCCS Files" in this guide.

## Freezepointing

During software development it is often useful to create freezepoints of your work at key junctures. These freezepoints serve as "snapshots" of a project that enable you to recreate the state of the project at key development points. With the Freezepointing program, you preserve these freezepoints using small storage resources. You can use Freezepointing through two functionally equivalent user interfaces:

- Graphical user interface (`twfreeze`)
- Command-line interface (`freezept`)

The concepts discussed in this section apply to both the GUI and the CLI. Descriptions and examples are included for the GUI only. For information on the CLI, see the `manual` pages: `twfreeze` (1), `freezept`(1), and `freezepointfile`(5).

Freezepointing enables you to create freezepoint files from Configuring workspaces. Freezepointing files are text files that list the default deltas in SCCS history files contained in the workspace. When you later recreate (extract) the files, Freezepointing uses those entries as pointers back to the original history files and to the delta that was the default at the time the freezepoint file was created.

> Note - The recreated files will not contain the original SCCS histories; only the g-files represented by the default deltas from the original hierarchy are recreated. The default delta is the delta that would be retrieved using the SCCS `get` command with no options specified.

| ### Starting the Freezepointing GUI

To start Freezepointing, at a shell command prompt type `twfreeze` followed by the ampersand symbol (`&`):

    demo% twfreeze &

| ### Creating and Extracting Freezepoints

  1. From a command prompt start the Freezepointing GUI:

      % twfreeze &

    The pane below the Control area is used for both creating and extracting freezepoints. Switch between the Create and Extract panes by choosing the appropriate item from the Category menu. The Create pane is the default and is displayed when you start Freezepointing.

  2. Enter the path name of a freezepoint file.

    Freezepointing automatically inserts the file name `freezepoint.out`.

  3. Delete it and replace it with a path name of your choosing.

  4. Enter the path name of the source workspace.

    This is the workspace that you are "freezepointing."

  5. In the Directories and Files text window, compose a list of directories, or files, or both that you wish to freezepoint.

  6. Choose File Add Files to create the Directories and Files list

  7. Click Create to execute.

  8. To extract a freezepoint, choose Extract from the Category menu.

    This changes the pane from Create to Extract.

  9. Type the path name of an existing freezepoint file.

  10. Specify the path name of the Destination Directory.

    This the directory into which the newly extracted files are placed.

  11. Click on Extract to execute.

    For more information about Versioning, see Chapter 14, "Performing Basic SCCS Functions with Versioning" in this guide.

## Distributed Make

DistributedMake (DMake) marks the evolution of the `make` utility into a powerful and flexible tool that permits you to take full advantage of the potential of today's networks and powerful multiprocessor workstations. Using DMake, you can concurrently distribute the process of building large projects, consisting of many programs, over a number of workstations and, in the case of multiprocessor systems, over multiple CPUs.

You execute `dmake` on a DMake host and distribute jobs to build servers. You can also distribute jobs to the DMake host, in which case it is also considered to be a build server. DMake distributes jobs based on makefile targets that DMake determines (based on your makefiles) can be built concurrently. You can use any machine as a build server that meets the following requirements:

- From the DMake host (the machine you are using) you must be able to use `rsh`, without being prompted for a password, to remotely execute commands on the build server. For example:

      demo% rsh build_server which dmake
      /opt/SUNWspro/bin/dmake

> Note - For more information about the `rsh` command see the `rsh`(1) man page or the system AnswerBook.

- The `bin` directory in which the DMake software is installed must be accessible from the build server.

> Note - For more information see the `share`(1M) and `mount`(1M) man pages or the system AnswerBook.

- The `bin` directory in which the DMake software is installed must be in your execution path when you `rsh` to the build server. Be sure this directory is added to the PATH variable in your `.cshrc` file (or equivalent), not in your `.login` file. You can verify this as follows:

      demo% rsh build_server which dmake
      /opt/SUNWspro/bin/dmake

- The source hierarchy you are building must be accessible from the build server.

From the DMake host you can control which build servers are used and how many DMake jobs are allotted to each build server. The number of DMake jobs that can run on a given build server can also be limited on that server.

For more information about DMake see Chapter 20, "Using DistributedMake."