6.1 Creating a Project from Scratch

This section describes how to create and set up a new project that is not based on an existing project or on an existing set of ClearCase VOBs.

Creating the Project VOB

PRODUCT NOTE: This task does not apply to ClearCase LT users. The ClearCase administrator creates the PVOB during the installation.

To create a PVOB:

1. Click Start > Programs > Rational ClearCase Administration > Create VOB. The VOB Creation Wizard appears.

2. In Step 1 of the VOB Creation Wizard, enter a name for the PVOB. Enter a comment to describe the purpose of the PVOB. Leave the Create as a VOB-level component check box clear. Although you can use one VOB as the PVOB and a component, we recommend against doing so unless your project is very small and you anticipate that it will remain small. Select the Create as a UCM project VOB check box.

3. In Step 2, specify the PVOB's storage directory. A PVOB storage directory is a directory tree that serves as the repository for the PVOB's contents. A PVOB's storage directory contains the same subdirectories as a VOB's storage directory. (For details about VOB storage directory structure, see the Administrator's Guide for Rational ClearCase or the Administrator's Guide for Rational ClearCase LT.) You can choose one of the recommended locations or enter the universal naming convention (UNC) path of a different location. Click Browse to search the network for shared resource locations.

4. Step 3 prompts you to choose an administrative VOB to be associated with the PVOB. Because you are creating a project from scratch and do not currently use an administrative VOB, scroll to the top of the list and select none. When you create components, ClearCase makes AdminVOB hyperlinks between the components and the PVOB, and the PVOB assumes the role of administrative VOB.

Creating a Component for Storing the Project Baseline

This task is optional but we strongly recommend it. Using a composite baseline to represent the project is easier than keeping track of a set of baselines, one for each component. Although you can store a composite baseline and elements in the same component, it is cleaner to dedicate one component for storing the project baseline. To ensure that nobody creates elements in this component, create the component without a VOB root directory. A component that has no VOB root directory cannot store its own elements. To create a component without a VOB root directory:

1. In the ClearCase Explorer, click UCM and click Project Explorer. The Project Explorer is the graphical user interface (GUI) through which you create, manage, and view information about projects.

2. The left pane of the Project Explorer lists folders for all PVOBs in the local ClearCase domain. Each PVOB has its own root folder. ClearCase creates the root folder using the name of the PVOB. Navigate to the PVOB that you created.

3. ClearCase also creates a folder called Components, which contains entries for each component in the PVOB. Right-click the Components folder and select Create Component Without a VOB from its shortcut menu.

4. In the Create Component Without a VOB dialog box, enter a name and description for the component. Click OK.

You may decide to use multiple composite baselines in your project. If you do, we recommend that you still use one top-level composite baseline that selects the baselines of all components in the project, either directly or indirectly through other composite baselines.

Creating Components for Storing Elements

This section describes how to create components for storing the files that your team develops.

PRODUCT NOTE: The process for creating components that store elements is slightly different for Rational ClearCase and Rational ClearCase LT.

When you create a component, you must specify the VOB that stores the component's directory tree. You can store multiple components in a VOB, or you can create a VOB that stores one component. See Deciding How Many VOBs to Use for details about using one VOB to store multiple components.

Creating One Component Per VOB

To create a VOB and its one component in ClearCase:

1. Start the VOB Creation Wizard.

2. In Step 1, enter a name for the component. Enter a comment to describe the purpose of the component. Select the Create as a VOB-level component check box.

3. In Step 2, specify where to store the component. You can choose one of the recommended locations or enter the UNC path of a different location. Click Browse to search the network for shared resource locations.

4. Step 3 prompts you to identify the PVOB that will store the project information about the component. Click the arrow to see the list of available PVOBs. Select the PVOB that you previously created.

ClearCase creates the component with an initial baseline that points to the \main\0 version of the component's root directory.

To create a VOB and its one component in ClearCase LT:

1. Click Start > Programs > Rational ClearCase LT Server > ClearCase Create VOB. The VOB Creation Wizard appears.

2. In Step 1, enter a name for the component. Enter a comment to describe the purpose of the component. Because ClearCase LT assumes that you are using UCM, the VOB Creation Wizard creates the VOB as a component.

3. In Step 2, select one of the available storage locations for the VOB's storage directory. This page of the wizard lists the VOB storage locations created by your ClearCase administrator. If only one VOB storage location exists, the VOB Creation Wizard skips this step and uses that VOB storage location.

Creating a VOB That Stores Multiple Components

To create a VOB that can store multiple components in ClearCase:

1. Start the VOB Creation Wizard.

2. In Step 1, enter a name for the VOB. Enter a comment to describe the purpose of the VOB. Clear the Create as a VOB-level component check box.

3. In Step 2, specify where to store the VOB. You can choose one of the recommended locations or enter the UNC path of a different location. Click Browse to search the network for shared resource locations.

4. Step 3 prompts you to identify the administrative VOB that is associated with the VOB you are creating. Because you plan to use this VOB to store components, you do not need to use an administrative VOB. Select none. When you create the components, you associate them with a PVOB, which assumes the role of an administrative VOB.

To create a VOB that can store multiple components in ClearCase LT, use the cleartool mkvob command. For example:

cleartool mkvob -nc -tag \myvob -stgloc stgloc1

To create a component and store it in the VOB:

1. Create a non-UCM view with the default config spec. In ClearCase Explorer, click Base ClearCase, and click the Create View shortcut. Complete the steps of the View Creation Wizard.

2. In the Command Prompt window, navigate to your view.

3. Use the cleartool mkcomp command. For example:

cleartool mkcomp -root \kmt_om_vob\admin_comp admin_comp@\kmt_om_pvob

This example creates the admin_comp component in the kmt_om_vob VOB. The component's root directory in the VOB is admin_comp. The component's root directory must be at or directly below the VOB root directory. If the component's root directory is at the VOB root directory, that VOB cannot store multiple components.

Creating the Project

This section shows how to create a project by using the Project Explorer and the New Project Wizard. For information on creating a project from the command-line interface (CLI), see the cleartool mkproject, mkstream, and mkfolder reference pages. To create a project:

1. In the left pane of ClearCase Explorer, click UCM and then click Project Explorer.

2. The left pane of the Project Explorer lists root folders for all PVOBs in the local ClearCase domain. Each PVOB has its own root folder. ClearCase creates the root folder using the name of the PVOB.

ClearCase also creates a folder called Components, which contains entries for each component in the PVOB. Folders can contain projects and other folders. Select the root folder for the PVOB that you want to use for storing project information.

3. Click File > New > Folder to create a project folder. You do not need to create a project folder, but it is a good idea. As the number of projects grows, project folders are helpful in organizing related projects.

4. In the left pane, select the project folder or root folder. Click File > New > Project. The New Project Wizard appears.

5. In Step 1 of the New Project Wizard, enter a descriptive name for the project in the Project Title box. Enter a comment in the Description box to describe the purpose of this project.

6. Step 2 asks whether you want to create the project based on an existing project. Because you are creating a project from scratch, click No.

7. Step 3 asks you to choose the baselines that the project will use.

Click Add to open the Add Baseline dialog box. In the Component list, select one of the components that you previously created. The component's initial baseline appears in the Baselines list. Select the baseline. Click OK. The baseline now appears in the list in Step 3. Continue to use the Add Baseline dialog box until the project contains its full set of foundation baselines.

8. Step 4 prompts you to specify the development policies to enforce for this project. Select the check boxes for the policies you want to enforce. See Chapter 4, Setting Policies for information about each policy.

9. Step 5 asks whether to configure the project to work with the ClearQuest integration. To enable the project to work with Rational ClearQuest, click Yes and select a ClearQuest user database from the list. See Enabling a Project to Use the UCM-ClearQuest Integration for details about the integration.

Defining Promotion Levels

ClearCase provides five baseline promotion levels. You can keep some or all of them, and you can define your own promotion levels. To define the promotion levels that your project uses:

1. In the Project Explorer, select the PVOB root folder that contains your project, and then click Tools > Define Promotion Level. All projects that use that PVOB have access to the same set of promotion levels.

2. The Define Promotion Levels dialog box opens. To remove an existing promotion level, select it and click Remove. To change the order of promotion levels, select a promotion level and use the Move Up or Move Down buttons.

3. To add a new promotion level, click Add. The Add Promotion Level dialog box opens. Enter the name of the new promotion level and click OK. The new promotion level appears in the list of promotion levels in the Define Promotion Levels dialog box. Move it to the desired place in the order.

4. When you finalize the set and order of promotion levels, select one to be the initial promotion level for new baselines. The initial promotion level is the level assigned by default when you create a baseline.

For information on defining promotion levels from the CLI, see the cleartool setplevel reference page.

Creating an Integration View

When you create a project, ClearCase creates the project's integration stream for you. To see and make changes to the project's shared elements, you need an integration view. To create an integration view:

1. In the Project Explorer, navigate to the integration stream by moving down the object hierarchy:

1. Root folder

2. Project folder

3. Project

4. Stream

Figure 25 illustrates this hierarchy.

Figure 25 Navigating to Integration Stream in Project Explorer

1. Select the integration stream and click File > New > View.

2. The View Creation Wizard opens. Accept the default values to create an integration view attached to the integration stream. By default, the View Creation Wizard uses this convention for the integration view name: username_project-name_integration.

ClearCase supports two kinds of views:

• Dynamic views, which use the ClearCase multiversion file system (MVFS) to provide immediate, transparent access to files and directories stored in VOBs. ClearCase maps a dynamic view to a drive letter in Windows Explorer.

• Snapshot views, which copy files and directories from VOBs to a directory on your computer.

PRODUCT NOTE: Rational ClearCase LT supports only snapshot views.

We recommend that you make the integration view a dynamic view to ensure that you always see the correct version of files and directories that developers deliver to the integration stream. With a snapshot view, you have to perform an update operation to copy the latest delivered files and directories to your computer. For more information about dynamic and snapshot views, see Developing Software.

Creating the Composite Baseline That Represents the Project

To create a composite baseline that represents the project by selecting a baseline from each component that the project uses, perform the following steps:

1. In the Project Explorer, right-click the project's integration stream to display its shortcut menu. Click Edit Baseline Dependencies.

2. The Edit Baseline Dependencies dialog box displays a list of all components that the project uses. Identify the component that will contain the composite baseline. Drag the other components onto the component that will contain the composite baseline. For example, in Figure 26 the om2_proj_comp component contains the composite baseline. The composite baseline selects baselines from the admin2_comp and security2_comp components.

3. Click Apply. The Create Baseline Dependencies dialog box opens.

4. Enter the name that you want to use for the baselines that UCM creates for these components.

5. Click OK.

Figure 26 Using the Edit Baseline Dependencies GUI

Creating the Directory Structure

Because you are creating the project from scratch, you need to create the directory elements within the project's components to implement the directory structure that you define during the planning phase. See Defining the Directory Structure. To add a directory element to a component:

1. In Windows Explorer, navigate to the integration view. Double-click the component to display its contents. If the component is in a VOB that you created to store multiple components, the component appears as a folder under the VOB.

2. Create a folder.

3. Right-click the folder to display the shortcut menu. Click ClearCase > Add to Source Control.

4. When prompted, specify an activity to be associated with the addition of the new directory element.

For more information about creating directory and file elements, see Developing Software and the mkelem reference page.

Importing Directories and Files from Outside ClearCase

If you have a large number of files and directories that you want to place under ClearCase version control, you can speed the process by using the clearexport and clearimport command-line utilities. These two utilities allow you to migrate an existing set of directories and files from another version control software system, such as SourceSafe or PVCS, to ClearCase.

To migrate source files into a component:

1. Create and set a non-UCM view by using the View Creation Wizard. To start the View Creation Wizard, from ClearCase Explorer click Base ClearCase > Create View.

2. From within the view, run clearexport to generate a data file from your source files.

3. From within the view, run clearimport to populate the component with the files and directories from the data file.

4. In the component, create a baseline from a labeled set of versions. If the versions that you want to include in the baseline are not labeled, create a label type and apply it to the versions. See Making a Baseline from a Label for details.

As an alternative, you can use clearexport and clearimport on VOBs, and then convert the VOBs to components. See Creating a Project Based on an Existing ClearCase Configuration for details on converting VOBs into components.

To migrate directories and flat files that are not currently under any version control, use the clearfsimport command-line utility. See the clearfsimport reference page for details.

For details on using clearexport and clearimport, see the Administrator's Guide for Rational ClearCase or the Administrator's Guide for Rational ClearCase LT and the clearexport and clearimport reference pages.

PRODUCT NOTE: ClearCase LT provides the Import Wizard, a GUI that you can use as an alternative to the clearexport and clearimport commands. You can start the Import Wizard from the Server Setup Wizard.

Making and Recommending a Baseline

After you create the directory structure and import files, create and recommend a new baseline that selects those directory and file elements. Developers who join the project populate their development streams with the versions identified by the recommended baseline. For details on making baselines, see Creating a New Baseline. For details on recommending baselines, see Recommending the Baseline.