Special targets

Special targets for use in makefiles

You can learn the special targets to be used in makefiles.

Special targets for use in makefiles or BOS files

You can learn the special targets to be used in makefiles or BOS files.

You can use the following special targets either in the makefile itself or in a build options specification file. For more information, see Build options specification files.

.DEPENDENCY_IGNORED_FOR_REUSE: file ...

The dependencies you specify are ignored when clearmake determines whether a target object in a VOB is up-to-date and can be reused. By default, clearmake considers that a target cannot be reused if its dependencies have been modified or deleted since it was built. This target applies only to reuse, not to winkin. Also, this target applies only to detected dependencies, which are not declared explicitly in the makefile.

You can specify the list of files with a tail-matching pattern, for example, Templates.DB/%.module.

Unlike the files listed in most special targets, the files on this list refer to the names of dependencies and not the names of targets. As such, the special target might apply to the dependencies of many targets at once. This special target is most useful when identifying a class of dependencies found in a particular toolset for which common behavior is desired across all targets that have that dependency.

.DIRECTORY_AFFECTS_REUSE: tgt...

This special target can be used to specify a declared directory dependency for reuse. It overrides both the .DIRECTORY_IGNORED_FOR_REUSE special target and the CCASE_DIR_IGNORED_REUSE environment variable.

This target takes one or more (whitespace-separated) directory path names, and you can specify the path names with a tail-matching pattern, such as %bin.

.DIRECTORY_IGNORED_FOR_REUSE: tgt...

clearmake notes directories for reuse that are recorded in a config record as dependencies. This target can be used to selectively override a declared directory dependency.

This target takes one or more (whitespace-separated) directory path names, and you can specify the path names with a tail-matching pattern, such as %bin.

This special target has an equivalent environment variable called CCASE_DIR_IGNORED_REUSE which takes no arguments, but is either on or off. If on, this environment variable overrides the build avoidance treatment of all declared directory dependencies.

.INCREMENTAL_REPOSITORY_SIBLING: file ...

The files listed are incremental repository files created as siblings of a primary target and might contain incomplete configuration information. This special target is useful when a toolset creates an incremental sibling object and you want to prevent clearmake from winking in a primary target that has this sibling.

You can specify the list of files with a tail-matching pattern, for example, %.pdb.

Unlike the files listed in most special targets, the files on this list refer to the names of sibling objects and not the names of targets. As such, the special target might apply to the siblings of many targets at once. This special target is most useful when identifying a class of siblings found in a particular toolset for which common behavior is desired across all targets that have that sibling.

.INCREMENTAL_TARGET: tgt ...

This target performs incremental configuration record merging for the listed targets; in other words, it combines dependency information from instances of this target generated previously with the current build of this target. This special target is most useful when building library archives, because typically only some of the objects going into a library are read each time the library is updated.

You can specify the list of files with a tail-matching pattern; for example, %.a.

For information about restructuring a makefile to build incremental archive files, see Working with incremental update tools.

• Files built incrementally that are not makefile targets. For example, sibling objects like log files or template repositories.
• Files built incrementally from several different build scripts.

The general guideline is that if you are not building a library with ar in a single makefile rule, and you are not building an executable using an incremental linker, do not use .INCREMENTAL_TARGET.

.JAVA_TGTS: file ...

This special target is used to handle subclasses generated by Java compilers.

In the makefile, any file name that matches the pattern will allow a $ to be escaped by another $. For example, to specify a$x.class, you can specify the list of files with a tail-matching pattern, such as, %.class:

.JAVA_TGTS: %.class

.java.class:

javac $<

a$$x.class: a.class

Note that $$ mapping to a single $ is the default behavior in Gnu make compatibility mode. For more information, see the makefile_gnu reference page.

.JAVAC:

Use this special target to enable clearmake to use heuristics on audits of Java builds to accurately evaluate .class dependencies. These dependencies are then stored in .class.dep files for future clearmake runs, and they enable those runs to build .class targets in the same order that the Java compiler does.

This special target must be used with no dependencies and no build script:

JAVAC:

Other than that, makefiles must use implicit suffix or pattern rules. For example:

.SUFFIXES: .java .class

.java.class:

        rm -f $@

        $(JAVAC) $(JFLAGS) $<

For compatibility modes that support them, use implicit pattern rules. For example:

%.class: %.java

        rm -f $@

        $(JAVAC) $(JFLAGS) $?

The makefiles must also use absolute paths for .class targets. For example:

all_classes:/vobs/proj/src/pkg1/foo.class

clearmake contains a built-in macro function you can use to specify absolute paths:

$(javaclasses)

For more information about the .JAVAC special target, see Using VersionVault Build Tools with Java.

.MAKEFILES_AFFECT_REUSE:

By default, makefiles recorded by using the .MAKEFILES_IN_CONFIG_REC special target do not affect DO reuse. You can use the .MAKEFILES_AFFECT_REUSE special target to enable recorded makefiles to affect DO reuse. (If you want to have some recorded makefiles affect reuse, but not all, you can also use the .DEPENDENCY_IGNORED_FOR_REUSE special target in conjunction with this target.)

Makefiles recorded in a configuration record are labeled by mklabel -config. Makefiles that were recorded in a configuration record but that were not recorded by using .MAKEFILES_AFFECT_REUSE are ignored by catcr -critical_only and diffcr -critical_only.

.MAKEFILES_IN_CONFIG_REC: file ...

You can use this special target to record the versions of makefiles in the configuration records of derived objects.

This target takes an optional dependency list, which might be a pattern. When used without a dependency list, this target causes all makefiles read by a build session to be recorded in the configuration record of all derived objects built during that build session.

To conserve disk space, you might want to supply a dependency list to this target so that, for example, only DOs built for top-level targets have the makefiles recorded in their configuration records.

.NO_CMP_NON_MF_DEPS: tgt ...

The specified targets are built as if the -M option were specified; if a dependency is not declared in the makefile, it is not used in configuration lookup.

You can specify the list of files with a tail-matching pattern, for example, %.o.

.NO_CMP_SCRIPT : tgt ...

The specified targets are built as if the -O option were specified; build scripts are not compared during configuration lookup. This is useful when different makefiles (and, hence, different build scripts) are regularly used to build the same target.

You can specify the list of files with a tail-matching pattern, for example, %.o.

.NO_CONFIG_MATCH_SLINKS : tgt ...

When used, this special target specifies that clearmake does not attempt to apply CR-based build-avoidance to a target file when it is a symbolic link, but uses time stamps if applicable.

This special target takes one or more (whitespace-separated) target path names, which can be wildcarded using the % tail-matching syntax.

.NO_CONFIG_REC : tgt ...

The specified targets are built as if the -F option were specified; modification time is used for build avoidance, and no CRs or derived objects are created.

You can specify the list of files with a tail-matching pattern; for example, %.o.

.NO_DO_FOR_SIBLING : file ...

Use this target to disable the creation of a derived object for any file listed if that file is created as a sibling derived object (an object created by the same build rule that created the target). These sibling derived objects are left as view-private files.

You can specify the list of files with a tail-matching pattern, for example, ptrepository/_%.

Unlike the files listed in most special targets, the files on this list refer to the names of sibling objects and not the names of targets. As such, the special target might apply to the siblings of many targets at once. This special target is most useful when identifying a class of siblings found in a particular toolset for which common behavior is desired across all targets that have that sibling.

.NO_SIBLING_DO_CONTAINED_IN : dir ...

This special target suppresses the creation of derived object for any file that lives in or beneath a specified directory. For example, if the makefile has the following targets:

.NO_SIBLING_DO_CONTAINED_IN: sun5/%

objs/sun5/a.o: src/a.c

cc -o $@ -c $<

objs/sun5/subdir/a2.o: src/a2.c

cc -o $@ -c $<

objs/b.o: src/b.c

cc -o $@ -c $<

then the written files named a.o and a2.o will not become DOs, but b.o will.

For example, if a makefile has this:

.NO_SIBLING_DO_CONTAINED_IN: subdir%

all: subdir1/T1 subdir2/T2

subdir1/T1:

touch $@

touch $@.sibling

subdir2/T2:

touch $@

touch $@.sibling

It takes one or more (whitespace-separated) directory path names, which can be wildcarded using the % tail-matching syntax.

.NO_WINK_IN : tgt ...

The specified targets are built as if the -V option were specified; configuration lookup is restricted to the current view.

You can specify the list of files with a tail-matching pattern, for example, %.o.

.NOTPARALLEL:%.a

.NOTPARALLEL:acc1 acc2

clearmake does not build any .a file in parallel with any other .a file, and acc1 is not built in parallel with acc2. However, clearmake might build .a files in parallel with acc1 or acc2.

.NOTPARALLEL does not affect lower-level builds in a recursive make, unless you specify it in the makefiles for those builds or include it in a BOS file.

You can specify the list of files with a tail-matching pattern, for example, %.a.

For more information, see Setting up a parallel build.

.SIBLING_IGNORED_FOR_REUSE: file ...

The files are ignored when clearmake determines whether a target object in a VOB is up-to-date and can be reused. This is the default behavior, but this special target can be useful in conjunction with the .SIBLINGS_AFFECT_REUSE special target or -R command-line option. This target applies only to reuse, not to winkin.

You can specify the list of files with a tail-matching pattern, for example, Templates.DB/%.module.

Unlike the files listed in most special targets, the files on this list refer to the names of sibling objects and not the names of targets. As such, the special target might apply to the siblings of many targets at once. This directive is most useful when identifying a class of siblings found in a particular toolset for which common behavior is desired across all targets that have that sibling.

.SIBLINGS_AFFECT_REUSE:

Build as if the -R command line option were specified; examine sibling derived objects when determining whether a target object in a VOB can be reused (is up-to-date). By default, when determining whether a target is up-to-date, clearmake ignores modifications to objects created by the same build rule that created the target (sibling derived objects). This directive tells clearmake to consider a target out of date if its siblings have been modified or deleted.

.ONESHELL

The .ONESHELL special target is available only in the GNU compatibility mode, which tries to emulate the .ONESHELL special target available in GNU make 4.2 and later.

When .ONESHELL is available anywhere in the makefile, all lines of the build script are executed in a single invocation of the shell, whereas in the traditional make paradigm, each line of the build script is executed under a separate shell process. Only the leading special character (@, -, +) in the first line of the build script is considered. If the shell is identified as a POSIX shell, leading special characters in subsequent lines (lines other than the first line) are removed from the build script before processing. For more information, see Using One Shell.