Chapter 4: SDE Project Administrator and System Integrator Tasks
This chapter gives an illustration of how to use SDE
commands to manage a project with connected systems. An example is shown
which does not cover all the possibilities of the commands, but which gives
the basic recommendations on how to manage the projects and the systems.
The example is described in Chapter
4.1 Administration before Start of Development
Before John, Paul and Anne can start the development
of the functions, Paul must create the project and the two systems.
To create a project in SDE means to create all directories
where the project files will be placed, and to register the project. To
register a project means adding a link from the "Projects root"
directory (/ipa/projects as default) to the project's home directory.
Projects with the purpose of creating or modifying
software must have at least one SDE system to store the created files in.
The systems square and CompareVersion do not yet exist, so they
must be created before they can be connected to the project smarter.
Paul finds it convenient to first create the systems,
and then the project.
Paul uses SDE - System Manager to manage the
4.1.1 Creating a New System
- Paul, who is system manager, first starts Softbench - SDE Control
Panel from a terminal window by giving the command sde.
Fig 4.1 SDE Control Panel
- He starts SDE - System Manager from SDE Control Panel (Figure
4-1) by choosing System Manager from the SDE menu. The
window in Figure 4-2 is opened.
Fig 4.2 SDE - System Manager
The SDE - System Manager window shows all the systems
present in the "Systems root" directory (/ipa/systems as default)
- Paul chooses the activity System... from the menu Create.
A dialog box is displayed and Paul fills it in with
data for the square system (Figure
Fig 4.3 Create New System
- Paul inserts the system name, the system description and his ID as
the system manager. His full name and a default value for the system directory
are filled in automatically. He uses the configuration name work. Paul
can see what happens when the system is created in the Message output area
(see Figure 4-2) in System
The created directories are:
In the configuration directory work an empty RCS directory
The master directory is used internally by the SDE
program. Among other things it contains one Change Request (CR) directory
for each configuration. Right now Paul only has one configuration, work,
in the system.
4.1.2 Creating Subsystems
To have a good structure of the square system,
Paul decides to have three subsystems in the system. Paul calls the subsystems
square, Math, and doc. Before he creates the subsystems,
he checks so he is positioned in the square system, configuration
- To create a subsystem Paul chooses the action Subsystem... from
the Create menu. The dialog box in Figure
4-4 is displayed.
- Paul fills it in with the name of the subsystem (Math) and clicks
Fig 4.4 Create subsystem
In the normal case you do not turn on the
option Create the subsystem even if this configuration has a child. Paul
leaves the check box turned off.
When the subsystem is created the following directories
- Paul creates the subsystems doc and square in the same
way. Unfortunately, when Paul creates the subsystem
square, he misspells it and writes sqaure instead of square.
4.1.3 Rename subsystem
Paul must correct his mistake with the square subsystem.
- He selects the sqaure subsystem, and chooses the action Subsystem...
from the Rename menu. The dialog box in Figure
4-5 is displayed.
Fig 4.5 Rename subsystem
- Paul fills in the correct subsystem name, clicks OK, and the
subsystem is renamed to its correct name square.
4.1.4 Square and CompareVersion systems
The structure of the created systems is found in Figure
3-2 and Figure 3-3.
4.1.5 Creating a New Project
When the systems are created Paul creates the project
- Paul starts SDE - Project Manager from Softbench
- SDE Control Panel by choosing Project Manager from the SDE
menu. The window in Figure
4-6 is opened.
Fig 4.6 SDE - Project Manager
- Paul does not select any project, but chooses the Admin pull-down
menu and the Create Project... activity. A dialog box is displayed
on the screen and Paul fills it in (Figure
Fig 4.7 Create Project
- Paul writes the project name and the project description. His ID, full
name and a default value for the project directory are automatically filled
in. When he clicks OK the project is created. The
message output area in Project Manager shows what happens when the project
The created directories are:
In the info directory, an overview file is created.
The project start-up file is created in the tools
directory with the name startup. A welcome message is stored in it. This
file can be used for definitions of the project's working environment.
4.1.6 Adding Project Members
The next step is to add the other project members
to the project. In our case, John and Anne must be added.
- Paul chooses the Add New Member/Common Work Directory...
activity from the Admin menu (Figure
4-8) and writes John's userid in the dialog box. John's
full name and the working directory are filled in automatically.
Fig 4.8 Add New Member
- When Paul clicks on Apply the member John is added. The
command creates John's working directory named john (which is John's userid)
in the members directory. It also creates a file called startup which will
be executed each time John chooses to work with the project. In this file
John can insert his own definitions used in the project.
- When John is added, Paul adds Anne as a project member in the same
way. When Paul has added all project members, he clicks on the Cancel
button to remove the dialog box.
4.1.7 Adding a System to a Project
In order to work on a system within a project, the
system must be added to the project.
- Paul selects the project smarter in SDE - Project Manager and
chooses the activity Add System... from the Admin menu. A
window with all the systems appears on the screen (Figure
Fig 4.9 Add System
- Paul's choice is simple. He selects the system square, and clicks
on Apply. Note, a configuration is not selected, only the system name.
The link name is the same as the configuration.
- Paul does the same thing to add the system CompareVersion to
4.1.8 Project Info
Paul wants to check that everything is correctly done
in the project initialization.
- He chooses the action Project Info from the SDE - Project Manager
menu Show. The window in Figure
4-10 appears on the screen.
Fig 4.10 Project Info
The window shows the project name, the project directory,
the project members, the name of the systems that are connected to the
project, and the overview file placed in the project's info directory.
The project structure is found in Figure
4.2 Additional Tasks
Paul must do some additional tasks to have the Change
Requests and the Makefiles for the application to work. Paul does these
changes in the project. Before he can do these changes, he must set up
the environment for the project. How to do this, see Section
4.2.1 Change Requests
The project team has decided they will use Change
Requests (CRs) to describe all the changes done on files in the project.
The Change Requests will work automatically, because the environment variable
SDE_CR_CI has, by default, the value ON in the project start-up
Paul creates the first Change Requests for the square
system. Further Change Requests in the project can be created by all project
- To create the first CR createMath, Paul start SDE - CR Manager
from SDE VersionWorks, he selects CR Manager from the menu File.
The CR Manager main window is opened.
Fig 4.11 SDE CR Manager
- In the window (Figure 4-11)
he chooses the action CR; Create.....
- He fills in the displayed dialog box with data for the CR (see Figure
Fig 4.12 Create CR createMath
Paul decides to assign John as responsible for the
CR, he also takes advantage of the possibility to send him a mail to inform
him of this. In this case he does not fill in the Function field, but he
turns on New Function as the reason for the CR.
- When he clicks OK the CR is created.
- He creates the CR createSquare in the same way.
4.2.2 Preparations in a System to be able to Build with Makefiles
To have the Makefiles work correctly in the building
of the executables, Paul must prepare the systems square and CompareVersion
for this. He must create some common files. He knows how the application
sqr depends on other libraries. These dependencies are shown in Figure
The file internals.mkf defines the subsystems of
the system. The subsystems that will include built executables need to
be defined. The file imports.mkf defines external products used to build
executables in the system, and exports.mkf defines subsystems in the system,
that are used by other systems. A more complete description of these files
is found in the document Make Usage and Makefile Structuring.
Paul must create imports.mkf, and internals.mkf.
They must be created for both systems.
The files are located on configuration level in the
systems, in this case in square/work and CompareVersion/1.0-0. For the
system CompareVersion the file exports.mkf must also be created,
because the system square will use files from this system.
- Paul selects system and configuration in SDE Control Panel, he then
creates a terminal window by double-clicking SDE Terminal in the
SDE Control Panel - Tools window (see Figure
- He creates the file internals.mkf with the command createInternals
from the terminal window.
- He edits internals.mkf and removes the subsystem doc in the started
Softedit window. internals.mkf is shown in Figure
Fig 4.13 internals.mkf
- The file imports.mkf is created from a template in SDE. Paul copies
it from $SDE_HOME/buildt/imports.mkf. He knows that
the square system will need the product c++_complib (a C++ class
library), and that the executable in the square subsystem needs a library
and include file from the Math subsystem. The executable also needs files
from the CompareVersion library. He edits imports.mkf to
fit the square system. The result is shown in Figure
Fig 4.14 imports.mkf
- In the CompareVersion system exports.mkf must be copied from
$SDE_HOME/buildt/exports.mkf. It must be edited to export the subsystem
Version. The resulting exports.mkf is shown in Figure
Fig 4.15 exports.mkf
- Paul also copies the make rules to the configuration level in both
the CompareVersion system and Square system. He copies the
files $SDE_HOME/buildt/rules.p.mkf and $SDE_HOME/buildt/rules.l.mkf.
- Paul checks in the files in the system. How to do this see Section
To make these files "known" to the project members, so they
will be able to use these files automatically, Paul must check out them
on system level.
- Paul uses his terminal window, and does system set square/work.
- Paul gives the command cover, to check out the latest version of the
- Paul leaves the system with the command exit.
Now John, Anne and Paul can do their development
work in the project square. See Chapter
4.4 Preparing a System Configuration for a Product Release
When John, Paul, and Anne have finished the development
work on project level, it is time to integrate the systems and make a product
of them. Only the system square is described, the system CompareVersion
is integrated in the same way.
Paul uses SDE - System Manager to do the necessary
tasks when integrating the system. The first thing he does is to rename
the system configuration from work to 1.0-0. He does this from SDE - System
Manager, the menu Rename; Configuration. The dialog in Figure
4-16 is shown.
Fig 4.15 Rename configuration
To do some checking on the files and CRs he uses
SDE - VersionWorks and SDE - CR Manager.
Both VersionWorks and CR Manager are started from
SDE Control Panel - Tools.
Since Paul has been working in the project for a
while, he must first move up to system level:
- Paul chooses Add System Session... from the Add menu
of SDE Control Panel.
Fig 4.17 Add System Session
- He selects system and configuration, he then clicks Add to List.
The tools Paul now starts from the SDE Control Panel
- Tools window will reflect the system level.
Fig 4.18 SDE Control Panel - Tools
A VersionWorks window and a Development Manager window
are created (see Figure 4-19).
Fig 4.19 VersionWorks on system level
It may be necessary to repeat the steps described
in Section 4.4.1 - Section
4.4.6 if, for example, an error is found in the system to integrate.
4.4.1 Check Files
Before doing anything on system level, Paul checks
the system to see the status of all files.
- He uses System Manager, the action Versioned Files...
in the menu Show. The dialog box in Figure
4-20 is displayed.
- He checks if there are any locked files in the system. There
are no locked files in the system.
- Paul chooses the action once again, and looks for all Unstable files
in the whole configuration (default value).
Fig 4.20 Show Versioned Files
The result is shown in a window (Figure
Fig 4.21 Unstable file window
- Paul saves this result in a file. To do this he uses the item Save
As... from the File menu in the window. Alternatively,
to check locked files, Paul can select the action Search; Find All Locked
Files in the VersionWorks window.
After the checking Paul asks John, why the files
Math.C and Math.H are not marked as Stable. John changes the state
of these files to Stable (how this is done see Section
4.4.2 Check CRs
Paul checks the CRs and the files connected to the
CRs. He uses SDE - CR Manager for this. The system square includes
three CRs createMath, createSquare, and moreFuncInSquare.
The first two CRs should be included in this product release. The CR moreFuncInSquare
is created by John, it describes changes that should be included in the
next product release.
- He chooses the action Check; Check All CRs. In
a new window he sees the result from the search (Figure
Fig 4.22 A CR search result
The equal signs means that the correct versions of
all files are added to the CRs to include in the product release.
- He checks so the CRs createMath and createSquare are
terminated. This is done by the developers when they are ready with the
changes covered by a CR. They are terminated (status
Term on the CRs in the main window).
- He changes the state to Rel for these CRs. He selects the two
CRs and chooses the action CR; Change State.... A
dialog box is displayed.
Fig 4.23 Change state to Rel
- He clicks on the Rel button (Figure
4-23), and clicks OK. The state of the CRs
is changed to Rel.
4.4.3 Show Imports
Before Paul checks out files and build the executables,
he checks the dependencies between the system and used external products
Paul checks the system square/work from SDE -
- He chooses the action Show; Imports.... The
dialog box in Figure 4-24
Fig 4.24 Show Imports
- He clicks on OK, and the result is shown in a new window. There
are no errors or warnings in this system.
4.4.4 Clean Configuration
Before the tag is set (see Section
4.4.5) and all files are checked out on system level, the system configuration
must be cleaned from earlier checked out files, to remove files with the
states Exp and Obsolete.
This can be done from SDE System Manager via the
command Clean Up Working Directory... from the Admin menu.
The dialog in Figure 4-25
Fig 4.25 Clean Up Working Directory
Paul applies the command to the whole configuration
(default). When Paul clicks OK all files but the RCS files are removed.
4.4.5 Tag a Version of Each File
When Paul knows that the latest version of all files
in the system configuration are Stable, which means they are ready
for integration, he can mark this version of each file.
- Paul chooses the Admin menu, and the item Tag File Versions
For Configuration.... The dialog box in Figure
4-26 is displayed.
Fig 4.26 Tag File Versions for Configuration
- Paul is content with the tag name R1_0_0 (same as configuration),
he wants to have all Stable files tagged with this name. Paul
does not have any Unchanged files in this system, because it is
the first configuration.
- He wants to have all files checked out on system level, therefore he
checks so the button Update working directory with tagged files is
selected. He clicks OK and all the versioned files are tagged
with R1_0_0, and checked out on system level.
4.4.6 Build on System Level
Paul builds the square system on system level,
he builds all the checked out files.
He selects the subsystem to build from the VersionWorks
window, and chooses File; Program Builder. The program builder Softbuild
is started. (How to use it see Section
During the build on system level, John and Anne can
if necessary continue to work on project level with some new changes intended
for the next product release.
4.4.7 Freeze for Other Users
John and Anne must not be able to do any changes in
this configuration after the system has been correctly rebuilt on system
- Paul uses the item Freeze/Unfreeze... from the Admin
menu, to make sure John and Anne cannot change anything in configuration
1.0-0. The dialog box in Figure
4-27 is displayed.
- Paul fills it in so group members are not able to do any changes on
the files and in the RCS libraries. When he clicks OK the action
Fig 4.27 Freeze Configuration
After this John and Anne cannot check in anything
in this configuration, they must wait until Paul has created a new configuration
intended for work.
4.4.8 Create New Configuration
Paul must create a new configuration so John and
Anne can start working on changes intended for the next product release.
Paul decides that the new configuration will be called work for
the time being. He intends to rename it later, see Section
After the creation he can continue with the integration
work of the old configuration 1.0-0.
When Paul creates the new configuration, work, he
uses SDE - System Manager.
- He selects the square system and goes down in it, and selects the parent
(1.0-0). After this he chooses the item Configuration... from the
Create menu. The dialog box in Figure
4-28 is displayed.
Fig 4.28 Create New Configuration
- Paul fills it in with the new configuration name work. He decides
to have new work RCS libraries in the new configuration, and to
copy the versions tagged R1_0_0. To be able to transfer changes
done on later file versions than the tagged file version (files with Exp
state), he also turns on and later. All files will be checked out
in the new configuration, because the button Update working directories
in the new configuration is selected.
- When Paul is content he clicks OK, and the new configuration
is created. The directory structure in the new configuration
is the same as in the old one.
In the new CR directory only the Change Request moreFuncInSquare
is transferred, the others are released (the state is Rel), and
are kept in the CR directory for the 1.0-0 configuration.
- Paul must edit the file imports.mkf (see Section
4.2.2), because the project will use c++_complib 3.0/0.
4.5 Creating a Product
When the system (configuration 1.0-0) has been rebuilt
and tested on system level, Paul creates a product. The new product smarter
will contain files from the systems square and CompareVersion.
These files will be copied from the system configuration 1.0-0. He uses
SDE - Product Manager to create the product.
- He starts SDE - Product Manager from SDE Control Panel by choosing
Product Manager from the SDE menu. The
window in Figure 4-29 is created.
Fig 4.29 SDE - Product Manager
- Paul chooses the action Create Product... from the Admin
menu. A dialog box is displayed and Paul fills it in
Fig 4.30 Create Product
- Paul inserts the product name (smarter), the product description, and
responsible department. The product release is by default 1.0-0. It may
be changed to something else or to contain target/release, for example
nt/1.0-0. Target/release is used when the product is intended for more
than one operating system platform. The smarter product will only be for
one target, Paul will only use the release name and is content with 1.0-0.
The product directory is automatically set to/ipa/products/smarter.
- When Paul is content he clicks OK, and the product directory
structure is created. The following structure is created:
In the info directory an overview file is created.
4.5.1 Product Description Files (PD files)
A Product Description file (PD file) describes which
files in the system structure that should be copied to the product structure.
An example of a PD file is shown in Figure
John and Anne creates the product description files
for the subsystems they are responsible for, they know which files should
be included in the product. They create these files during development,
the PD files have the same name as the product, smarter.pd. These
files are managed in the same way as other files.
From the square subsystem, the executable sqr, and
the manual page for the sqr function, sqr.1, should be included in the
John uses the the normal editor to create the PD file
The created PD file is shown in Figure
The first part of the directory (root) is specified
by the environment variable
PRODUCT_ROOT. This variable should in this case be specified to
Fig 4.32 PD file in square subsystem
- Paul checks so the subsystem product description files are correct,
and creates the "main" PD file using his ordinary test editor.
Paul creates a main PD file for the square system on configuration
level. This file (square/1.0-0/smarter.pd) looks as
Fig 4.33 Main PD file
This file includes the PD files in all subsystems
to make sure everything is copied. It also includes the PD file from the
- Paul checks out all the PD files on system level. They must be tagged
with the tag name.
4.5.2 Copy from Systems to Product
Paul copies the files to product level from system
level with SDE - System Manager.
- He positions in the system square/1.0-0. He chooses the item Copy
to Product... from the Admin menu. The dialog
box in Figure 4-34 is displayed.
Fig 4.34 Copy to Product
- Paul inserts the name of the PD files (smarter.pd), and the name of
the Product Root
- When he clicks OK, all files specified in the PD files are copied
to the product.
4.5.3 Verify Product Contents
To verify the contents in the product directories,
with the contents of the PD files, Paul uses SDE - Product Manager.
- He positions in the smarter product release 1.0-0, and chooses the
menu Show and the action Check PD File.... The
dialog box in Figure 4-35
Fig 4.35 Check PD File
- He fills in the correct PD file (/ipa/systems/square/1.0-0/smarter.pd),
and clicks on OK. The result is that all files
in the product can be found in the PD files in the system.
4.5.4 Create System Specification
Part of the system specification can be created from
SDE - Product Manager.
- Paul chooses the action Generate Product Spec... in the Admin
menu. The dialog box in Figure
4-36 is displayed, and Paul fills it in.
Fig 4.36 Generate Product Specification
- He selects the PD file smarter.pd, and the first (new) release 1.0-0.
Because it is the first release the item Old Release
- He also gives a destination where he wants to save the generated FrameMaker
file, he places it in his work directory in the smarter project. Paul is
content with the default List all files.
- When Paul clicks OK, the FrameMaker file is generated and a
window is created showing the same result as in the FrameMaker file.
- Paul includes the generated FrameMaker file in his system specification
for the product smarter, and edits it to fit in the system specification.
4.6 Distribute the Product
Paul uses the company standard routines for creating
and distributing products with Software Install on HP-UX.
4.7 Establish a System Configuration for First Time
When the product smarter is released and distributed,
Paul establishes the system configuration 1.0-0. This means that
no one can check in any file, and the file versions will be purged to include
only one version of each file in the RCS libraries.
- Paul uses SDE - System Manager, and positions in the system square,
- He chooses the action Establish Configuration... from
the Admin menu. The dialog box in Figure
4-37 is displayed.
Fig 4.37 Establish the first configuration
- Paul accepts the default, Use tag R1_0_0 to select the wanted
file versions. Because it is the first configuration, he wants to keep
the RCS libraries, and have them purged. He turns on Keep work RCS libraries.
When the RCS libraries are purged, there is no need for a check action,
so Paul turns on Check and do it and clicks on OK. All
RCS libraries are cleaned so only the selected file version will remain
in the libraries.
4.8 Integrating a Configuration and Creating a Product in Further Releases
The rest of this chapter describes how system configurations
and product releases can be integrated for further releases of the product.
4.9 Prepare New System Configuration for Product Release
When all development is done in configuration work,
this configuration is prepared for a new product release of the smarter
product. This product release will be called smarter 1.1-0 so Paul has
to rename it from the current name work to 1.1-0. For this he uses SDE
System Manager and the action Rename; Configuration.... He fills
in the new name 1.1-0 in the displayed dialog box.
Most of the things are done in the same way as described
earlier in this chapter. The following describes mostly when there are
4.9.1 Build and Freeze New Configuration
Same as Section
4.4, except the tag set is R1_1_0.
4.10 Create a new Product Release
Paul creates a new product release from SDE - Product
- He uses the item Create New Release..., from the Admin
menu. Before he chooses the item, he checks so he is positioned in the
smarter product, release 1.0-0. The window in Figure
4-38 is opened.
- Paul fills it in with the name of the new product release, 1.1-0, and
clicks on OK.
Fig 4.38 Create New Release
The new product structure is created with the same
directories as in the old release. Instead of copying all files from the
old product release, the files in the new release are symbolic links to
the corresponding files in the old product release.
4.10.1 Copy to new product release
4.10.2 Merge Product Release
When all the changed files are copied to the new product
release, the unchanged files are exchanged with copies instead of symbolic
- Paul chooses the item Merge Release... from the Admin
menu in SDE - Product Manager, see Figure
Fig 4.39 Merge Release
- Paul checks so it says the correct product release (1.1-0). When he
clicks OK, all unchanged files will be exchanged with copies from
the old product release.
4.10.3 Compare product releases
Paul wants to check that the smarter product 1.1-0
is correct, to do this he can use SDE - Product Manager.
- He selects the smarter product, uses the item Compare Releases...
from the Show menu. The dialog box in Figure
4-40 is displayed.
Fig 4.40 Compare product releases
- He fills in 1.0-0 as Release1 and 1.1-0 as Release2. The
command compares the two releases and shows the differences between the
- Files only in one release
- Files that are modified between the releases
4.10.4 Generate System Specification
4.10.5 Distribute New Release
4.11 Establish New Configuration
When Paul has distributed the new product release
(smarter 1.1-0), he wants to establish the configuration 1.1-0 of the system
- Paul uses SDE - System Manager, as usual he selects the square system,
and positions in configuration 1.1-0.
- He chooses the item Establish Configuration... from the Admin
menu. The dialog box in Figure
4-41 is displayed.
Fig 4.41 Establish Configuration
- He uses the tag R1_1_0 to select the file versions. Paul wants to keep
all files in the original RCS libraries (the RCS libraries in configuration
1.0-0), therefore he checks that the button Copy back files and remove
work RCS libraries is selected.
- To check that the configuration 1.1-0 can be correctly established
the button Just check is first selected. Paul clicks on OK
and the check is run. The result is shown in the SDE
- System Manager message output area.
- The check says that the configuration will be correctly established,
so Paul chooses the action once again, but in this case he turns on Check
and do it, and clicks OK. All selected file
versions from the RCS libraries are copied back to the original RCS libraries,
the work RCS libraries are removed, instead symbolic links are created
that point to the original RCS libraries.