RADE

Source Code Manager

Workspace Management

Creating and populating a workspace

Use Case

Abstract

This article explains how to create a workspace and how to start working in it.

Setting Up the SCM Environment
Creating a New Workspace
- Creating Images
- Creating a Multi-tree Workspace
Attaching Components
Creating Files and Directories
- Choosing the Right Type
In Short
References

Setting Up the SCM Environment

SCM is provided as a set of commands. The same commands are available on both Windows and Unix platforms.
To have access to these commands, open a shell window (on Unix) and a command window (on Windows) and set up your environment by calling the tck_init profile and executing the tck_profile command. Please ask your administrator for the exact locations of the tck_init profile and the tck_profile command.

Once the environment has been set up, all commands are available in the current window.

[Top]

Creating a New Workspace

A workspace is created in a tree [1] and under an existing workspace.

For the first workspace to be created in a tree, the command to execute is the adl_mk_root_ws command.
For the other workspaces, the command to execute is the adl_mk_ws command.

A full description of all parameters and options is available for all SCM commands by executing the command either with the -h option or -help option or -? option.

A workspace is identified by a unique name and is created under an existing workspace (except for the root [2] workspace). This existing workspace is called the parent workspace and the new workspace is called a child workspace of this parent workspace.

If the name of the parent workspace is know by the user, it is not mandatory to specify the tree where the new workspace will be created. Otherwise the user must select a tree and lists workspaces belonging to it in order to chose a parent workspace:

the command to list trees is the adl_ls_tree command.
the command to list workspaces in a tree is the adl_ls_ws command.

Note that choosing a parent workspace has a consequence for the way the new workspace will deliver its developments:

components available in the workspace will be only those available in the parent workspace
new components or changes to existing components will come from the parent workspace only.
any development will be delivered to the parent workspace.

According to these rules, workspaces should be created regarding the way development teams work together. For example, developers working in a common project should create their workspaces under a common workspace whose purpose will be the integration of their developments.

Creation of the root workspace "SampleRoot1" in the tree "SampleTree1" whose Unix image root path is "/u/lego/WS/SampleRoot1" and whose associated tool level is V5R5.

$ adl_mk_root_ws SampleRoot1 -tree SampleTree1 -dir /u/lego/WS/SampleRoot1 -tck V5R5
Creating the root workspace "SampleRoot1" in the workspace tree "SampleTree1".
Command successful.

Creating the image "UNIX" in the workspace "SampleRoot1".
Command successful.

$

Creation of a workspace named "project" as a child of the "SampleRoot1" workspace and having an Unix image projected under "/u/lego/WS/project". No tool level is specified choosing to inherit the one defined by the parent workspace.

$ adl_mk_ws project -parent_ws SampleRoot1 -dir /u/lego/WS/project
Creating the workspace "project" child of "SampleRoot1" in the workspace tree "SampleTree1".
Command successful.

Creating the image "UNIX" in the workspace "project".
Command successful.

$

[Top]

Creating Images

Images [3] are associated with workspaces and a workspace can have from 0 to n images. The first image can be created when creating a workspace. Others images are created afterwards by using the adl_mk_image command.

All images have a name and default names are WINDOWS and UNIX regarding the current platform where they have been created.

Creation of a Windows image for the "project" workspace.

$ E:\WS>adl_mk_image -ws project -dir \\algue\home\WS\project
Creating the image "WINDOWS" in the workspace "project".
Command successful.

Refreshing the image "WINDOWS" of the workspace "project".
Command successful.

$

On Windows, an image path using the UNC format: \\machine\share_name\directory. This is the default format considering an image can be accessed from different hosts. If a given image will never be accessed from another host than the one where it is created, a local path can be used. In that case the -local_dir option must be specified.

Creation of a local Windows image for the "integration" workspace.

$ adl_mk_image -ws integration -dir E:\WS\integration -local_dir 
Creating the image "WINDOWS" in the workspace "integration".
Command successful.

Refreshing the image "WINDOWS" of the workspace "integration".
Command successful.

$

[Top]

Creating a Multi-tree Workspace

A multi-tree workspace is a workspace existing in more than one tree. Usually all data composing a product are managed in a same tree and all users developing this product create their workspaces in the same tree.

Sometimes, a project development is composed of a lot of components and some users are working on a subset of these components while others need to have the whole set in their workspaces. In such a case, the first users will create their workspace in only one tree (the one managing the subset they need) while the others will create their workspace in all the trees managing the whole set of components.

Fig 1: Multi-tree Workspaces

The figure 1 shows three trees containing both single and multi-tree workspaces:

"Dev1", "Dev2", "Dev3", "Dev4", "Dev5" and "Int3" are single-tree workspaces
"Int1" is a multi-tree workspace (existing in three trees)
"Int2" is a multi-tree workspace (existing in two trees)
"Int1" and "Int2" can operate on components pertaining to several trees while the other workspace can access only components from one tree.

Single or multi-tree workspaces are created by the same command: adl_mk_ws. The difference between these two kinds of workspaces is made by using the -tree option when creating them: if no tree or just one tree is specified at creation time, the workspace is a (single-tree) workspace, if more than one tree is specified, the workspace will be a multi-tree workspace.

Creation of the "project" multi-trees workspace in the trees "system" and "foundation".
    
    $ adl_mk_ws project -parent_ws integration -tree system foundation -dir \\algue\home\ws\project
Creating the workspace "project" child of "integration" in the workspace tree "system".
Command successful.

Creating the workspace "project" child of "integration" in the workspace tree "foundation".
Command successful.

Creating the image "WINDOWS" in the workspace "project".
Command successful.

$

The adl_mk_ws command provides the -alltrees option for creating a multi-tree workspace in the same trees as it parent workspace (no need to specify them).

Notes:

An existing workspace can be turned into a multi-tree workspace using the adl_link_ws command.
A multi-tree workspace can be turned into a (single-tree) workspace using the adl_unlink_ws command.

Creation of the "team" multi-trees workspace in the same trees as its parent workspace.

$ adl_mk_ws team -parent_ws project -all_trees -dir /u/lego/WS/team
Creating the workspace "team" child of "project" in the workspace tree "system".
Command successful.

Creating the workspace "team" child of "project" in the workspace tree "foundation".
Command successful.

Creating the image "UNIX" in the workspace "team".
Command successful.

$

[Top]

Attaching Components

A workspace is created empty, components must be added to it. Components can either created or attached in the workspace:

If a new component is to be managed in a tree, one must chose the workspace where it will be registered in SCM. A component can be created in only one workspace.
The commands to create new components are adl_mk_fw, adl_mk_mod or adl_mk_data according to the type of component: framework, module or data.
If a workspace must contain components declared elsewhere in the same tree, it must attach them.
The command to attach any type of component is the adl_attach command.

The attachment follows the rules defined for data flows:

A component can be attached in a workspace if its parent workspace has already attached this component.
If the parent workspace has not attached the component, it must be synchronized with a version of its own parent workspace where this component exists.

Like for any modifications the creation of new components in a workspace is made visible to the others only when this workspace publishes them and that child workspaces synchronized themselves. The two following examples show the steps to go through for attaching in a workspace a component created in another one.

In this scenario the goal is to attach in "Dev1" a new component created in "Int" workspace:

The component is created in "Int" workspace
"Int" publishes its content to make the new component visible
"Prj" synchronizes with the last published version of "Int" in order to see the new component
"Prj" publishes its content to make it visible to its own child workspaces
"Dev1" synchronizes with the published version of "Prj" in order to see the new component
"Dev1" attaches the new component

Notes:

even the new component is not attached in "Prj" workspace, it is visible for the child workspaces (as soon as "Prj" is synchronized with the right state of "Int" workspace)
if some changes are done in the "Dev1" workspace and if it promotes them, the collect in "Prj" workspace will attach automatically the framework.

In this scenario, the new component is created in a sibling workspace of the workspace willing to work on it:

The component is created in the "Dev1" workspace
"Dev1" promotes the new component
"Prj" collects this promotion
"Prj" published its content to make available the new component
"Dev2" synchronizes with the published version of "Prj"
"Dev2" attaches the new component

SCM manages two kinds of components: the frameworks and the modules (code or data modules).
There are different ways to attach components depending on the parts the user is interested in.

Attachment of the public part of the "fw1" framework, internal modules are not attached:

$ adl_attach fw1

Attachment of the "fw1" framework, including all its internal code and data modules:
      
$ adl_attach fw1 -mod

"fw1" being attached in the workspace, attachment of two of its internal modules:

$ adl_attach fw1/mod1.m fw1/CNext.specifics_UNIX

"fw1" being attached in the workspace, attachment of all internal modules not already attached:

$ adl_attach fw1 -attached_fw_mod

[Top]

Creating Files and Directories

Like for components, files and directories come into a workspace either by attaching them or by creating them. If one user is interested in working on some files already managed by SCM, he/she can get a copy of them by attaching the embedding module and/or framework. Conversely if the files and directories are not yet registered in SCM, they must be declared using the adl_mk_elem and adl_mk_dir commands.

An empty file can be declared to SCM but it must exist when calling the adl_mk_elem command. A empty directory can be declared to SCM but its registration does not lead to register the internal files at the same time, they must be registered one by one using the adl_mk_elem command. It is not needed to declared all directories in the path of files, the registration of a file causes all embedding directories to be registered at the same time (except for frameworks and modules that must be explicitly registered using either adl_mk_fw, adl_mk_mod or adl_mk_data commands).

Files and directories cannot be created anywhere under an image [3] root directory, SCM commands check that the file and directory paths correspond to a right location regarding their purpose:

header files must be created one of the four predefined directories according to their scope:
- "fw/PublicInterfaces" directory contains header files that can be used by other components
- "fw/ProtectedInterfaces" directory contains header files that can be used by "friend" components (relationships are expressed in IdentityCard.h files)
- "fw/PrivateInterfaces" directory contains header files private to the framework and shared by internal modules
- "fw/module/LocalInterfaces" directory contains header files private to the module
framework are created right under the image root directory
modules are created right under the corresponding framework directory

The following example shows the registration of files that will be associated with the embedding module and framework. Each "Command successful" message indicates the end of a transaction, that is to say that each file is created in a separate command.

Registration of files in the current directory:

$ adl_ch_ws team
...
$ cd SampleFw1\SampleMod1.m\src

$ dir
...
Directory of E:\WS\team\SampleFw1\SampleMod1.m\src

10/04/00 11:30 <DIR> .
10/04/00 11:30 <DIR> ..
27/03/00 08:40 5 333 ADLEContext.c
31/03/00 15:03 5 329 ADLECustom.c
19/10/99 16:04 4 729 ADLEEnv.c
03/01/00 17:00 7 031 ADLELog.c
27/03/00 08:56 10 440 ADLEMain.c
...

$ adl_mk_elem *
Creating the element "SampleFw1\SampleMod1.m\src\ADLEContext.c" in the workspace "team" and the workspace tree "SampleTree1".
Command successful.

Creating the element "SampleFw1\SampleMod1.m\src\ADLECustom.c" in the workspace "team" and the workspace tree "SampleTree1".
Command successful.

Creating the element "SampleFw1\SampleMod1.m\src\ADLEEnv.c" in the workspace "team" and the workspace tree "SampleTree1".
Command successful.

Creating the element "SampleFw1\SampleMod1.m\src\ADLELog.c" in the workspace "team" and the workspace tree "SampleTree1".
Command successful.

Creating the element "SampleFw1\SampleMod1.m\src\ADLEMain.c" in the workspace "team" and the workspace tree "SampleTree1".
Command successful.

[Top]

Choosing the Right Type

Some predefined types are recognized by SCM. Those types are useful for setting a specific behavior to all files being registered in SCM.

The type to be associated with a new file is chosen according to the file suffix. If this suffix is also the name of a predefined type, this type is selected, otherwise the command is canceled by asking the user to specify a predefined type.

$ adl_mk_elem unknown.suffix
Looking for a file type "suffix".
# ADLCMD - 1161: No file type "suffix" found.
You have to specify the file type with the option -type.
Use adl_ls_type in order to list all file types.

$

The list of predefined types is displayed by the adl_ls_type command:

$ adl_ls_type
File type      Content type   Unix Executable
---------------------------------------------
CATDlg         Text           Not exec
CATNls         Text           Not exec
CATPart        Bin            Not exec
CATProduct     Bin            Not exec
CATRsc         Text           Not exec
...

When a file has a suffix which does not correspond to any predefined suffix, the user must chose between one of the four basic types that SCM provides:

txt: to be used for any editable text file having no executable rights on Unix platform
sh: to be used for any editable text file having executable rights on Unix platform
bin: to be used for any binary file having no executable rights on Unix platform
exe: to be used for any binary file having executable rights on Unix platform

[Top]

In Short

The location of a new workspace (tree, parent workspace) is chosen regarding the development project this workspace will be involved in.
The commands to create a workspace are either adl_mk_root_ws or adl_mk_ws depending whether it is the first workspace created in a tree.
The command to get copies of components is the adl_attach command.
The command to register new files in SCM is the adl_mk_elem command.
Predefined types are listed by the adl_ls_type command.

[Top]

References

[1]	Tree
[2]	Root Workspace
[3]	Images
[Top]

History

Version: 1 [Mar 2000]	Document created
[Top]