omake

ClearCase build utility - maintain, update, and regenerate groups of programs

APPLICABILITY

ClearCase (command)

SYNOPSIS

omake [ -f makefile ...] [ -b builtins-file ...]

[ -akinservdphzADGM] [ -x file ] [ -OLWT ]
[ -EN | -EP | -EO] [ -#1] [ -#2] [ -#4] [ -#8]
[ macro=value ...] [ target_name ...]

DESCRIPTION

omake is a ClearCase utility for making (building) software. It includes many of the configuration management (CM) facilities provided by the clearmake utility. It also features emulation modes, which enable you to use omake with makefiles that were constructed for use with other popular make variants, including Microsoft NMAKE, Borland Make and the PVCS Configuration Builder (Polymake).

NOTE: omake is intended for use in dynamic views. You can use omake in a snapshot view, but none of the features that distinguish it from ordinary make programs - build avoidance, build auditing, derived object sharing, and so on - works in snapshot views. The rest of the information in this reference page assumes you are using omake in a dynamic view.

omake features a number of ClearCase extensions:

• Configuration Lookup - a build-avoidance scheme that is more sophisticated than the standard scheme based on the time-modified stamps of built objects. For example, this guarantees correct build behavior as C-language header files change, even if the header files are not listed as dependencies in the makefile.
• Derived Object Sharing - developers working in different views can share the files created by omake builds.
• Creation of Configuration Records - software bill-of-materials records that fully document a build and support rebuildability; also includes automatic dependency detection.

Related Reference Pages

The following reference pages include information related to omake operations and results:

See also Building Software with ClearCase.

View Context Required

For a build that uses the data in one or more VOBs, the command interpreter from which you invoke omake must have a view context-you must be on a drive assigned to a view or the dynamic-views drive (default: M:\). If you want derived objects to be shared among views, you should be on a drive assigned to a view.

You can build objects in a standard directory, without a view context, but this disables many of omake's special features.

omake AND MAKEFILES

omake is designed to read makefiles in a way that is compatible with other make variants. For details, see the ClearCase OMAKE Manual.

HOW BUILDS WORK

In many ways, ClearCase builds adhere closely to the standard make paradigm:

1. You invoke omake, optionally specifying the names of one or more targets. (Such explicitly-specified targets are termed goal targets.)
2. omake reads zero or more makefiles each of which contains targets and their associated build scripts.
3. omake supplements the makefile-based software build instructions with its own built-in rules. (And when it runs in a compatibility mode, omake also defines built-in rules specific to that mode.)
4. For each target, omake performs build avoidance, determining whether it actually needs to execute the associated build script ("perform a target rebuild"). It takes into account both source dependencies ("have any changes occurred in source files used in building the target?") and build dependencies ("must other targets be updated before this one?").

   The sources can be on the dependency list, or may be detected by omake. A source is a target or file that must exist and be up-to-date before the target is built. The dependency list is used to make decisions about build ordering (which targets need to be built and in which order). Detected dependencies (source dependencies detected automatically by omake) are also used to determine if a DO can be reused or is out of date.

   Like detected dependencies, predefined dependencies are used for DO reuse questions, but they are also used for determining which files should be built and when they should be built. For example, for a .exe file, you must predefine all the .obj files to ensure that they are built first; for an .obj file, you list the .c or .cpp files, but header files can be left off and omake still detects them.

   The difference is very important for a first build, when there are no existing DOs and only the makefile exists to define the dependencies and what target depends on what other target.

5. If it decides to perform a target rebuild, omake executes its build script.

The following sections describe special omake build features in more detail. Figure 17 illustrates the associated data flow.

Figure 17 Data Flow in an omake Build

CONFIGURATION RECORDS AND DERIVED OBJECTS

In conjunction with the MVFS file system, omake audits the execution of all build scripts, keeping track of file usage at the OS-system-call level. For each execution of a build script, it creates a configuration record (CR), which includes the versions of files and directories used in the build, the build script, build options, (for example, macro assignments) and other related information. A copy of the CR is stored in the VOB database of each VOB in which the script has built new objects.

A file created within a VOB by a build script is called a derived object (DO), and it can be shareable or nonshareable. When a shareable derived object is built in a view, a corresponding VOB database object is also created. This enables any view to access and possibly share (subject to access permissions) any derived object, no matter what view it was originally created in. When a build tool creates a nonshareable derived object, the tool does not write any information about the DO to the VOB. Therefore, the DO is invisible to other views and cannot be winked in by them. Builds that create nonshareable DOs are called express builds. For more information about using express builds, see Preventing Winkin to Other Views.

For each build script execution, ClearCase logically associates each DO that was created in that execution with the build script's CR.

You can suppress the creation of CRs and derived objects with the -L option and ClearCase-specific directives. See Building Software with ClearCase for details on CRs and derived objects, and see the ClearCase OMAKE Manual for information on ClearCase-specific directives.

(Files created in non-VOB directories are not derived objects - see the MVFS FILES AND OBJECTS OUTSIDE THE MVFS section.)

Configuration Record Hierarchies

A typical makefile has a hierarchical structure. Thus, a single invocation of omake to build a high-level target can cause multiple build scripts to be executed and, accordingly, multiple CRs to be created.

CONFIGURATION LOOKUP AND WINKIN

For directory targets, omake uses standard make logic.

When a target names a non-directory file in a VOB, omake (by default) uses configuration lookup to determine whether a build is required. This involves a comparison of the CRs of existing derived objects with the current build configuration:

• the versions of elements selected by the view's config spec
• the build options to be applied, as specified on the omake command line, in the environment, or in the makefile(s)
• the build script to be executed

In performing configuration lookup, omake considers a DO version (a derived object that has been checked in as a version of an element) only if the version was created in place. That is, if you copy a DO to a different location from where it was created and check it in there, omake will not consider the DO version.

omake first tries to avoid rebuilding by reusing a DO in the current view; this succeeds only if the CR of the candidate DO matches the current build configuration. For the purpose of rebuilding, a branch\0 version of a file selected by a view is considered to match its non-zero predecessor version in a CR.

omake can also avoid rebuilding by finding another DO, built in another view, whose CR matches the current build configuration. In this case, it will wink in that derived object, causing it to be shared among views. Other derived objects created by the same build script (termed siblings) are winked in at the same time. omake rebuilds a target only if it is unable to locate any existing derived object that matches the current build configuration.

NOTE: Certain special targets may prevent winkin even if the build configuration conditions are exactly the same. For example, if you are using .pdb files in Visual C++, winkin of any target that has a .pdb for a sibling will not occur, even though all versions of dependencies in the config record are selected by the view in which the build occurs.

The .cmake.state File

The .cmake.state file is a view-private cache of config records for derived objects built in the view during a particular build. omake creates this file in the directory that was current when the build started. During subsequent builds in the view, omake references the file instead of communicating with the VOB. This makes configuration lookup faster, improving omake performance.

You can delete .cmake.state files if they get too large. If omake looks for a .cmake.state file and it doesn't exist, no errors occur and omake creates a new file.

Suppressing Configuration Lookup

You can override the default configuration lookup behavior with command options and ClearCase-specific directives (see the ClearCase OMAKE Manual for information on these directives). For example, -L turns off configuration lookup, basing rebuild decisions on time-modified stamps, and -W disables winkin of DOs from other views.

Preventing Winkin to Other Views

You can prevent derived objects that you create from being winked in to other views. For more information, see Working with Derived Objects and Configuration Records in Building Software with ClearCase.

CACHING UNAVAILABLE VIEWS

When omake shops for a derived object to wink in to a build, it may find DOs from a view that is unavailable (because the view server host is down, the albd_server is not running on the server host, and so on). Attempting to fetch the DO's configuration record from the view causes a long time-out, and the build may attempt to contact the same view multiple times.

omake maintains a cache of tags of inaccessible views. For each view-tag, omake records the time of the first unsuccessful contact. Before trying to access a view, omake checks the cache. If the view's tag is not listed in the cache, omake tries to contact the view. If the view's tag is listed in the cache, omake compares the time elapsed since the last attempt with the time-out period specified by the CCASE_DNVW_RETRY environment variable. If the elapsed time is greater than the time-out period, omake removes the view-tag from the cache and tries to contact the view again.

NOTE: The cache is not persistent across omake sessions. Each recursive or individual invocation of omake attempts to contact a view whose tag may have been cached in a previous invocation.

The default time-out period is 60 minutes. To specify a different timeout period, set CCASE_DNVW_RETRY to another integer value (representing minutes). To disable the cache, set CCASE_DNVW_RETRY to 0.

MVFS FILES AND OBJECTS OUTSIDE THE MVFS

All files with pathnames below a VOB-tag (VOB mount point) are termed MVFS files:

• checked-in versions of file elements (data stored in VOB)
• checked-out versions of file elements (data stored in view)
• other view-private files
• derived objects

Conversely, a non-MVFS object is any file or directory whose pathname is not under a VOB-tag; such objects are not version controlled. By default, non-MVFS objects are not audited during omake builds.

OPTIONS AND ARGUMENTS

omake supports the options below. In general, standard make options are lowercase characters; omake extensions are uppercase. Options that do not take arguments can be ganged on the command line (for example, -rOi).

-f makefile

Use makefile as the input file. If you omit this option, omake looks for input files named makefile and Makefile (in that order) in the current working directory. You can use more than one -f makefile argument pair. Multiple input files are effectively concatenated.

-b file

Specify an initialization (built-ins) file to be read instead of the default. If file is the empty string, omake does not read an initialization file. Valid empty strings are "-b  " (one space), -b" ", or -b "".

NOTE: If you do not include the -b option, omake uses the file named by the OMAKECFG environment variable. If this environment variable is not set, omake looks for a file called make.ini in (in order) the current directory, ccase-home-dir\bin, and in directories specified by the INIT environment variable.

-a

Rebuild all goal targets specified on the command line, along with the recursive closure of their dependencies, regardless of whether or not they need to be rebuilt.

-k

Abandon work on the current entry if it fails, but continue on other targets that do not depend on that entry.

-i

Ignore error codes returned by commands.

-n

(no-execute) List command lines from the makefile for targets which need to be rebuilt, but do not execute them. Even lines beginning with an at-sign (@) character are listed.

To override this option for a recursive make, use the .MAKE target attribute. For example:

nt .MAKE :
cd nt.dir & $(MAKE) $(MFLAGS)

Typing the command omake -n nt does a cd nt.dir, then a recursive make with omake -n. Without the .MAKE attribute, omake would display but not execute the (cd nt.dir & $(MAKE) $(MFLAGS) line.

-s

(silent) Do not list command lines before executing them.

-e

Environment variables override macro assignments within the makefile. (But macro=value assignments on the command line override environment variables.)

-r

Do not use the built-in rules.

-v

(verbose) Slightly more verbose than the default output mode. Particularly useful features of verbose mode include:

-d

(debug) Quite verbose; appropriate only for debugging makefiles.

-p

Lists all target descriptions and all macro definitions, including target-specific macro definitions and implicit rules.

-h

Displays the command-line syntax.

-x file

Redirects error messages into file. If file is "-", the error messages are redirected to standard output.

-z

Ignore the MFLAGS macro.

-A

Use automatic dependencies. This option is enabled only if you are not using configuration lookup (because you are processing non-MVFS files or using the -W option).

-D

Keep-directory mode. The first access of a directory to look for a file results in the directory being read into memory.

-G

Restricts dependency checking to makefile dependencies only - those dependencies declared explicitly in the makefile or inferred from an inference rule. All detected dependencies are ignored. For safety, this automatically disables winkin of DOs from other views; it is quite likely that other views select different versions of detected dependencies.

For example, a derived object in your view may be reused even if it was built with a different version of a header file than is currently selected by your view. This option is mutually exclusive with -W.

-M

Makes the makefile before reading it.

-EN

Emulates Microsoft NMAKE utility.

-EP

Emulates PVCS Configuration Builder (PolyMake) utility.

-EO

Default emulation mode (that is, no emulation).

For details on emulation features, see the ClearCase OMAKE Manual.

-O

-L (mutually exclusive)

-O  compares only the names and versions of objects listed in the targets' CRs; it does not compare build scripts or build options. This is useful when this extra level of checking would force a rebuild that you do not want. Examples:

-L makes rebuild decisions using the standard algorithm, based on time-modified stamps; configuration lookup is disabled. Also suppresses creation of configuration records. All MVFS files created during the build will be view-private files, not derived objects.

-W

Restricts configuration lookup to the current view only. Winkin of DOs from other views is disabled.

-T

Examines sibling derived objects (objects created by the same build rule that created the target) when determining whether a target object in a VOB can be reused (is up to date). By default, when determining whether a target can be reused, omake ignores modifications to sibling derived objects. -T directs omake to consider a target out of date if its siblings have been modified or deleted.

-#1

Read-time debugging mode. Displays omake reading makefiles and interpreting conditional directives.

-#2

Displays a warning when omake tries to expand the value of an undefined macro.

-#4

Displays a warning when omake reads a makefile line that it can't understand.

-#8

Do not delete generated response files and batch files.

MAKE MACROS AND ENVIRONMENT VARIABLES

String-valued variables called make macros can be used anywhere in a makefile: in target lists, in dependency lists, and/or in build scripts. For example, the value of make macro CFLAGS can be incorporated into a build script as follows:

cl $(CFLAGS) msg.c

Conflict Resolution

Conflicts can occur in specifications of make macros and environment variables. For example, the same make macro might be specified both in a makefile and on the command line; or the same name might be specified both as a make macro and as an environment variable.

omake resolves such conflicts similarly to other make variants:

• Make macros specified on the command line override any other settings.
• Make macros specified in a makefile or make.ini file have the next highest priority.
• Builtin macros override EVs, which in turn have the lowest priority.

Using the -e option changes the precedence rules - EVs get higher priority than make macros specified in a makefile.

CONFLICT RESOLUTION DETAILS. The following discussion treats this topic more precisely (but less concisely).

omake starts by converting all EVs in its environment to make macros. These EVs will also be placed in the environment of the command interpreter process in which a build script executes. Then, it adds in the make macros declared in the makefile. If this produces name conflicts, they are resolved as follows:

• If omake was not invoked with the -e option, the make macro wins: the macro value overwrites the EV value in the environment.
• If omake was invoked with the -e option, the EV wins: the EV value becomes the value of the make macro.

Finally, omake adds make macros specified on the command line; these settings are also added to the environment. These assignments always override any others that conflict.

omake reads the following environment variable at startup:

CCASE_AUDIT_TMPDIR (or CLEARCASE_BLD_AUDIT_TMPDIR)

Sets the directory where omake creates temporary build audit files. If this variable is not set, omake creates these files in %tmp%. All temporary files are deleted when omake exits. CCASE_AUDIT_TMPDIR must not name a directory under a VOB-tag; if it does, omake prints an error message and exits.

BUILD REFERENCE TIME AND BUILD SESSIONS

omake takes into account the fact that software builds are not instantaneous. As your build progresses, other developers can continue to work on their files, and may check in new versions of elements that your build uses. If your build takes an hour to complete, you would not want build scripts executed early in the build to use version 6 of a header file, and scripts executed later to use version 7 or 8. To prevent such inconsistencies, omake locks out any version that meets both these conditions:

• The version is selected by a config spec rule that includes the LATEST version label.
• The version was checked in after the time the build began (the build reference time).

This reference-time facility applies to checked-in versions of elements only; it does not lock out changes to checked-out versions, other view-private files, and non-MVFS objects. omake automatically adjusts for the fact that the system clocks on different hosts in a network may be somewhat out of sync (clock skew).

For more information, see Pointers on Using ClearCase Build Tools in Building Software with ClearCase.

EXIT STATUS

omake returns a zero exit status if all goal targets are successfully processed. It returns various nonzero exit status values when the build is not successful. See the ClearCase OMAKE Manual.

EXAMPLES

• Build target hello.exe without checking build scripts or build options during configuration lookup. Be moderately verbose in generating status messages.

> omake -v -O hello.exe

• Build the default target in the default makefile, with a particular value of make macro INCL_DIR.

> omake INCL_DIR=c:\src\include_test

• Build target bgrs.exe, restricting configuration lookup to the current view only. Have environment variables override makefile macro assignments.

> omake -e -W bgrs.exe

• Unconditionally build the default target in a particular makefile, along with all its dependent targets.

> omake -a -f project.mk

FILES

ccase-home-dir\bin\builtins.cb
ccase-home-dir\bin\builtins.nm
ccase-home-dir\bin\make.ini

SEE ALSO

Building Software with ClearCase, ClearCase OMAKE Manual, clearmake, clearaudit, cleartool, config_spec, promote_server, scrubber