Specifying pragmas in an addendum file

A pragma addendum file is a simple text file that lets you easily add pragmas (using #pragma ) to a build without modifying makefiles or other files, such as when you do not “own” those files. A pragma addendum file uses a subset of make syntax to declare pragmas on targets within the build. This syntax lets you use existing makefiles or other files unmodified while avoiding inconvenient makefile syntax such as tabs versus spaces, dollar-sign escapes, and eval.

The pragma addendum file format is similar to the make format. You must specify the pragmas and then the target to which they apply. All text content is treated as literal strings.

Using pragmas for builds with the eMake Ninja emulation mode enabled ( --emake-emulation=ninja ) requires a pragma addendum file. Pragma addendum files are optional with any other emulation mode.

Pragma addendum file restrictions

emake allows only comments, #pragma declarations, and target names to the left of colons. Commands and prereqs are not allowed.
You cannot use make-instance-level pragmas such as allserial and #pragma jobcache parse.
You cannot use variables. Instead, you must use path names that are absolute or relative to the current working directory (instead of using $(…) variable expansions).

Supported addendum file pragmas

The supported pragmas are:

Pragma Description

Pragma	Description
`jobcache`	Enables the JobCache feature, which can substantially reduce compilation time. `jobcache parse` is not supported. For details, see Job Caching.
noautodep	Disables the eDepend (autodep) feature. For details, see CloudBees Build Acceleration eDepend.
readdirconflicts	Enables directory-read conflicts on a per-job basis. You can apply it to targets or rules. This pragma incurs less overhead than the `--emake-readdir-conflicts=1` eMake option (which enables directory-read conflicts for an entire build). For details about directory-read conflicts, see Conflicts and Conflict Detection.
runlocal	Runs jobs locally on the host build machine instead of on an Agent in the cluster. For details, see Running a Local Job on the Make Machine.
runlocal -repopulate <dir1> [… -repopulate <dirN> ]	Tells eMake where to find files created by jobs instead of looking in the current working directory by default. For details, see Running a Local Job on the Make Machine.
runlocal sticky	Causes all jobs after a certain point in the build to run locally. For details, see Running a Local Job on the Make Machine.

jobcache

Enables the JobCache feature, which can substantially reduce compilation time. jobcache parse is not supported. For details, see Job Caching.

noautodep

Disables the eDepend (autodep) feature. For details, see CloudBees Build Acceleration eDepend.

readdirconflicts

Enables directory-read conflicts on a per-job basis. You can apply it to targets or rules. This pragma incurs less overhead than the --emake-readdir-conflicts=1 eMake option (which enables directory-read conflicts for an entire build). For details about directory-read conflicts, see Conflicts and Conflict Detection.

runlocal

Runs jobs locally on the host build machine instead of on an Agent in the cluster. For details, see Running a Local Job on the Make Machine.

runlocal -repopulate <dir1> [… -repopulate <dirN> ]

Tells eMake where to find files created by jobs instead of looking in the current working directory by default. For details, see Running a Local Job on the Make Machine.

runlocal sticky

Causes all jobs after a certain point in the build to run locally. For details, see Running a Local Job on the Make Machine.

Using patterns in a pragma addendum file

You can include gmake-style patterns in target names in the pragma addendum file so that you do not need to specify explicit target names. This includes “match anything” patterns such as % alone.

For example, to match all .o files, use:

#pragma jobcache gcc
%.o:▼

Also for example, to match everything, use:

#pragma noautodep ./out/build_number.txt
%:▼

Only the first % in the target name is treated as a wildcard. This means that you cannot specify a literal % in target names (in other words, you cannot escape the % so that it is not treated as a wildcard in this context).

Pragma addendum file examples

Following is an example pragma addendum file:

# system.img targets are runlocal because they do lots of I/O.
#
#pragma runlocal
out/target/product/generic/system.img:

#pragma runlocal
out/target/product/generic/obj/PACKAGING/systemimage_intermediates/system.img:

#pragma jobcache javadoc
out/target/common/docs/api-stubs-timestamp:▼

Following is an example pragma addendum file for Android 7.0.0:

#pragma runlocal
out/target/product/generic/obj/PACKAGING/systemimage_intermediates/system.img:

#pragma runlocal
out/target/product/generic/system.img:

#pragma jobcache kati
out/build-aosp_arm.ninja:

#pragma noautodep ./out/build_number.txt
out/target/common/docs/api-stubs-timestamp:

#pragma noautodep ./out/build_number.txt
out/target/common/docs/system-api-stubs-timestamp:

#pragma noautodep ./out/build_number.txt
out/target/common/docs/test-api-stubs-timestamp:

#pragma noautodep ./out/build_number.txt
out/target/product/generic/obj/ETC/system_build_prop_intermediates/build.prop:

#pragma noautodep ./out/build_number.txt
out/target/common/docs/apache-http-stubs-gen-timestamp:

#pragma noautodep ./out/build_number.txt
out/host/common/obj/JAVA_LIBRARIES/cts-tradefed_intermediates/com/android/compatibility/SuiteInfo.java:▼

This example sets the runlocal pragma on system.img This pragma lets you avoid the heavy I/O required to run it on the remote Agent. The jobcache pragma enables kati job caching for build-aosp_arm.ninja. The noautodep pragmas prevent unnecessary rebuilds just because the build number changed.

Specifying the pragma addendum file to use

You use the --emake-pragmafile option to specify the pragma addendum file to use. Following is an example eMake command line that uses a pragma addendum file:

emake --emake-emulation=ninja --emake-pragmafile=my_ninja_settings.pragma -f mybuild.ninja▼