7.2 Using Visual C++ with ClearCase

The ClearCase build utility omake (and, to a much lesser degree, clearmake) can be used to build in a Visual C++ development environment.

omake

omake can read Visual C++ makefiles, but only if NMAKE emulation mode is specified with the -EN parameter. In addition, if you are working outside the ClearCase MVFS (that is, neither on the drive M nor on a drive assigned to a ClearCase view), or if you disable configuration management (CM) features with the -L option, omake behaves like Visual C++ NMAKE, and no special options are needed. However, if you want to use omake within the MVFS (that is, in ClearCase VOBs) to produce ClearCase DOs, you will find it most convenient to use the SCC integration with Visual C++, which maximizes the cooperation between ClearCase and Visual C++. For information on using omake with Visual C++, see the online help for the omake and Visual C++ integration.

If you are not using the SCC integration or are using Visual C++ 2.x, omake does not have access to the internal environment of the Visual C++ development environment. Therefore, you must set the INCLUDE, LIB, and PATH environment variables before you run Visual C++ rather than rely on the directory lists set in the IDE options. Also, omake cannot access the Visual C++ build rules, so it must get build script information from either the builtins.nm file or the makefile.

If you are using Visual C++ 5.0 or 6.0, you must export your makefile before running omake. You can either click Tools > Options > Build and set the option Export makefile when saving project file, or export your makefile after making changes to the project settings. To export your makefile:

1. Check out the file project-name.mak (if it is an element).

2. Click Project > Export Makefile.

3. If you are prompted to select which configurations to export, select any configurations that will be built with omake.

Visual C++ creates project-name.mak.

clearmake

You can use clearmake only if you are not using makefiles generated by Visual C++ - that is, if you write your own makefiles that call the Visual C++ compiler, linker, and so on.

Incremental Repositories in Visual C++

Program Database files (PDBs) and Incremental Database files (IDBs) are built up with information from compilations of many .c/.cpp source files. This type of database file is referred to as an incremental repository in ClearCase. The consequence of using these incremental repositories is that object files cannot be winked in without making the PDB/IDB out of date. There is no way to wink in a portion of a file, a feature that would be required to wink in the object and the section of the PDB/IDB that holds the debug info for that specific object. For this reason, the SCC integration disables winkin for targets with a PDB or IDB sibling DO. Note that manual winkin with the cleartool winkin command can be used to wink in these objects; this method is described in the section Using the winkin Command.

Alternative: Using C7 Compatible Debug Information

The C/C++ compiler generates debug information in two different ways:

• C7 compatible info (/Z7 parameter from the command line), which is compatible with the V7 compiler. Debug information is stored in resultant object files.

• Create one or more .PDB files that store the debug information.

C7-style debug info is the ideal choice when using clearmake or omake because information is stored directly in the object file. Since no files are shared by builds of multiple targets, winkin is automatic. If you use multiple views to build the same versions of files, this method is the most advantageous way of working. Automatic winkin means that clearmake or omake shops in the VOB for similar DOs and determines whether the previously built DO is the same as would be produced by executing the target's build script. If they would be the same, the target build previously is winked in (an operation that is in most cases faster than executing the build script), and the two views share a single disk image of the target file.

Base the decision on which debug information style to use on whether PDBs are necessary, whether other necessary features require PDBs (some types of precompiled headers and incremental compiles, for example), and whether an appropriate DO in your environment is likely to exist and be shareable.

Switching between PDBs and C7 debug information is simple. In the Visual C++ IDE:

1. Click Project > Settings.

2. Select the debug target in the Settings For tree.

3. Click the C/C++ tab.

4. In the Category list, click General.

5. In the Debug Info list, click either Program Database or C7 Compatible.

Using vcmake.mak to Prevent Reuse Mismatches

The makefile fragment vcmake.mak defines files with a .pdb or .idb extension as incremental repositories. Specifying these siblings, which may contain incomplete information, prevents the ClearCase build tool from incorrectly winking in their associated primary target.

To use the information in vcmake.mak, find your particular environment in Table 2 and follow the instructions.

If you do not use the appropriate procedure, DOs built in one environment cannot be shared with other environments, and you see error message like this one:

Cannot reuse ".\..\bin.pcu\jdsample.obj" - mismatch between config record flag and makefile directive for "\adept\src\pub\libjpeg\bin.pcu\vc50.idb"

Browser Files

The browser generator, bscmake, has a performance enhancement that can create problems with configuration records. By default, when bscmake runs, it truncates all existing browser information files (called SBRs). If you use C7 debug information to allow winkin to work automatically, running bscmake in the default mode causes winkin to fail. clearmake or omake never finds a DO that can be winked in: the SBR created when the object file was created is no longer available because bscmake overwrote it. A bscmake option is available to cause it to run in nonincremental mode, where it reads all existing SBR files without modifying them. Using this parameter with C7 debug mode permits winkin to work correctly.

To run bscmake in nonincremental mode, you must specify the /n parameter. Add this parameter on all release builds in which the DOs are versioned. To add /n using the IDE:

1. Click Project > Settings.

2. Select the desired target in the Settings For tree.

3. Click the Browse Info tab.

4. In the Project Options box, add /n.

Using the winkin Command

If you choose a method that disables automatic winkin, you may still gain the space and performance benefits of DOs and CRs by winking in DOs manually. The cleartool winkin command can wink in a specified DO or, with the -recurse parameter, wink in a DO and its sub-DOs. If your team runs nightly builds, an entire project can be winked in (even if PDBs and IDBs were used.) Issue a cleartool winkin -recurse do-pname command in the development view. You can use view-extended naming to select the do-pname. The target and all targets used to build it are winked in to the development view.

Because the winkin -recurse command winks in a hierarchy of DOs without regard to the makefile or config spec selections in the current view, run clearmake or omake after completing the manual winkin to ensure that all DOs are up to date. If the development view selects the same versions of files that were referenced during the nightly build, this build does not require anything to be rebuilt. If development has continued since the nightly build on a subset of the files, only the necessary objects need to be recompiled or relinked.

See the winkin reference page for more information.