eMake Command-Line Options, Variables, and Configuration File

14 minute read

You can configure eMake options from the command line for a specific build and can also use eMake environment variables or the emake.conf configuration file to make options persistent.

Following are caveats for using these methods for setting options:

  • The environment variable EMAKEFLAGS can be used to set any command-line option. For example, this emake invocation:

% emake --emake-cm=mycm --emake-root=/home/joe

is equivalent to the following in csh :

% setenv EMAKEFLAGS "--emake-cm=mycm --emake-root=/home/joe"
% emake

The Bash shell equivalent is:

$ export "EMAKEFLAGS=--emake-cm=mycm --emake-root=/home/joe"
$ emake

The Windows command shell equivalent is:

C:\> set EMAKEFLAGS=--emake-cm=mycm --emake-root=C:\home\joe
C:\> emake
  • The hierarchy or precedence for setting an eMake option is:

    • Command-line options

    • Options set using the EMAKEFLAGS environment variable

    • Options set using other Electric Cloud environment variables

      Command-line options as well as options in the EMAKEFLAGS environment variable override options in the emake.conf configuration file.

Editing the eMake Configuration File

The path to the eMake configuration file is <InstallDir>/<arch>/conf/emake.conf (on Linux and UNIX) or <InstallDir>\<arch>\conf\emake.conf (on Windows), where <InstallDir> is the top installation directory containing the eMake program, and <arch> is the architecture (such as i686_Linux or sun4u_SunOS ).

If you run an eMake executable that is not within an ElectricAccelerator installation, it will not use the installed configuration file (but will still use environment variables and options entered from the command line).

The configuration file has the following formatting rules:

  • Only eMake-specific command line arguments are allowed (not those specific to GNU Make, NMAKE, and so on).

  • One option (a switch-argument pair) is allowed per line.

  • All allowed switches must be separated from their arguments by = (an equal sign).

  • All text between = and the end of the line (including spaces and terminal spaces) is part of the argument.

  • File order determines the option order (for many kinds of options, the final occurrence overrides all earlier ones).

  • NUL characters are not allowed.

  • Empty lines are ignored.

  • Lines beginning with # are comment lines and are ignored.

Configuration file syntax errors (but not necessarily semantic ones) are warnings and cause the configuration file to be skipped (as if it was not present, except for the warnings).

List of eMake Command-Line Options

Command-line options are listed in alphabetical order except for platform-specific options that are listed after platform-independent options. Debug options are listed at the end of the table.

The --emake-volatile command-line option is deprecated and no longer has any effect. If the option is specified, it is ignored.
Command-line Options Environment Variables Description


Always set to local.

Specifies that an individual emake invocation on the Agent does not enter stub mode, but instead behaves like a local (non-cluster) make. eMake automatically uses local mode when the -n switch is specified.


Specifies the location of your Android source files. For details about Android builds, see the KBEA-00165 - Best Practices for Android Builds Using ElectricAccelerator 10.1 and Newer Versions KB article.


Specifies your Android version. The available values are 7.0.0, 8.0.0, or 9.0.0. For details about Android builds, see the KBEA-00165 - Best Practices for Android Builds Using ElectricAccelerator 10.1 and Newer Versions KB article.


Specifies the level of detail to include in annotation output—a comma-separated list for any of the following values: basic : Basic annotation (enabled by default in cluster mode). If the JobCache feature is enabled, basic annotation includes information about cache hits and misses.

env : Enhanced environment variables file : Files read or written history : Serialization details lookup : All file names accessed md5 : MD5 checksums for reads/writes registry : Updates to registry waiting : Jobs that waited none : Disables all annotation. Note that this value disables basic annotation, even when the --emake-annofile option is used.

This option overrides the build class annotation settings set on the Cluster Manager.


Specifies the name of the XML-formatted log output file. By default, the annotation file, emake.xml, is created in the directory where eMake is run. If specified, implies at least “basic” annotation details.

The following macros are available:

@ECLOUD_BUILD_ID@ expands into the unique eMake build ID.

@ECLOUD_BUILD_TAG@ expands into the build tag from the Cluster Manager (this is displayed in the Name column on the Build tab in the Cluster Manager UI).

@ECLOUD_BUILD_DATE@ expands into an 8-digit code that represents the local system date where the build began, in the form YYYYMMDD.

@ECLOUD_BUILD_TIME@ expands into a 6-digit code that represents the 24-hour local system time where the build began, in the form HHMMSS.

Example: --emake-annofile=annofile-@ECLOUD_BUILD_ID@ -@ECLOUD_BUILD_TAG@ -@ECLOUD_BUILD_DATE@-@ECLOUD_BUILD_TIME@.xml

results in: annofile-4 -default_4_20090220184128 -20090220-184128.xml


Enables ( 1 ) or disables ( 0 =default) annotation file upload on the Cluster Manager.

This option overrides the build class annotation upload setting set on the Cluster Manager.


Enables ( 1 ) or disables ( 0 =default) the eDepend feature.


Sets the minimum file size (in bytes) to send through Agent-to-Agent transfers for direct file sharing between hosts. Default= 10KB.



Sets a customized build label. These labels are literal strings and do not use available tags when defining labels for build classes.



Specifies the build class for the current build. The class must match an existing Cluster Manager class previously created by a user. If this option is not used, or if the class does not match, eMake assigns the default class to the build.



Turns on support for specified ClearCase features—a comma-separated list of any of the following values: symlink : symbolic links vobs : per-VOB caching (for speed) rofs : read-only file system


If no Agents are available when the build starts, this option specifies the number of seconds to try to acquire Agents before giving up. The default is ` -1 ` (infinite), so the build waits indefinitely for Agents.



Sets the host name (either the IP address or machine name) and port for Cluster Manager.

Note that you cannot use --emake-cm and --emake-localagents=y in the same eMake invocation.


Turns history collapsing on or off. When collapsing is enabled, dependencies between a single or several jobs in another make instance are replaced with a serialization between the job and the other Make instance. This action typically results in significant history file size reduction, but might cause some over-serialization. In most builds, this has little or no impact on build time. In some builds, disabling collapsing improves performance at the cost of increased history file size. Default=1 (on)


Comma-separated list of pragma directives to ignore—can be one or more of: allserial, runlocal, noautodep, or all to disable all pragmas.


Disables variable table pruning. Default= 0 (off)



Sets Make-type emulation to a specific mode. Default emulation type is gmake. You can rename emake.exe to nmake.exe or gmake.exe to change the emulation type for all builds automatically.

Available modes: gmake, gmake3.80, gmake3.81, gmake3.82, symbian, nmake, nmake7, nmake8, cygwin, ninja (Linux only), or ninja1.7.2 (Linux only)

If specifying gmake3.82, read the GNU Make 3.82 Note.

--emake-emulation-table= <table>

Configures default emulation modes for Make programs. TABLE is a comma-separated list of NAME=MODE, where NAME is the name of a Make executable and MODE is the emulation mode to use if emake is invoked as NAME.



Specifies which environment variables must not be replicated to the hosts.

--emake-hide-warning= <list>


Hides one or more Accelerator-generated warning numbers. list is a comma-separated list of numbers that you want to hide. The EC prefix of a warning number is optional and can be omitted.


Specifies the history mode creation model. Default= merge.


Honors history mode even if the build fails. Default= 1 (on)


Specifies which history file to use for a specific build. Allows you to change the default name and path for the history file emake.data set automatically by eMake.

The following macros are available:

@ECLOUD_BUILD_ID@ expands into the unique eMake build ID.

@ECLOUD_BUILD_TAG@ expands into the build tag from the Cluster Manager (this is displayed in the Name column on the Build tab in the Cluster Manager UI).

@ECLOUD_BUILD_DATE@ expands into an 8-digit code that represents the local system date where the build began, in the form YYYYMMDD.

@ECLOUD_BUILD_TIME@ expands into a 6-digit code that represents the 24-hour local system time where the build began, in the form HHMMSS.

Example: --emake-historyfile=historyfile-@ECLOUD_BUILD_ID@ -@ECLOUD_BUILD_TAG@ -@ECLOUD_BUILD_DATE@-@ECLOUD_BUILD_TIME@.xml

results in: historyfile-4 -default_4_20090220184128 -20090220-184128.xml


Sets the number of seconds ( N ) before idle Agents are released to the cluster. Default= 10


Causes eMake to not treat .SECONDARY targets having no prerequisites as meaning that all targets are intermediate. This option might increase performance on certain large builds with thousands of targets and reduce eMake runtime memory requirements (but breaks strict compatibility with GNU Make when emulating GNU Make 3.81 and later).

--emake-impersonate- user=<name>


Run the build as this Cluster Manager user.

Impersonate changes the user recorded by the Cluster Manager and that user’s permissions. This option does not affect OS user permissions.

For additional information, see the online help topic, “Permissions.”


Limits the maximum number of uncommitted jobs to N where 0 means unlimited. Default= 0

--emake-ledger=< valuelist>


Enables the ledger capability. Valuelist is a comma-separated list that includes one or more of: timestamp, size, command, nobackup, nonlocal, and unknown.

--emake-ledgerfile=< path/file>


The name of the ledger file. Default= emake.ledger


Limits the number of Agents used by this build. N=0 uses all available Agents. Default= 0

This option overrides the build class Max Agents setting if --emake-maxagents is set lower than the build class setting. This option does not override the build class setting if --emake-maxagents is set higher than the build class setting.

This behavior prevents a user from overriding the upper limit for a class that was set up by the build administrator.


Controls the amount of memory eMake devotes to uncommitted jobs. When the limit is exceeded, eMake stops parsing new Make instances. Default= `1,000,000,000 ` (1 GB).



Indicates whether to merge the stdout/stderr output streams, yes ( 1 ) or no ( 0 ). The default is merge the streams ( 1 ). For most situations, this is the correct value. If you re-direct standard output and standard error separately, specify no ( 0 ) for this option.

--emake-monitor <hostname/IP>:<port>

Sets the hostname/IP and port of the system from where you want to view the live monitor data in the Electric Cloud ElectricInsight® tool.

To monitor live build data, you must launch the ElectricInsight live monitor before you start the build.


Turns pedantic mode on ( 1 ) or off ( 0 =default). When pedantic mode is on, warnings appear when invalid switches are used, or potential problems are identified (for example, rules with no targets or reading from a variable that was not written). When pedantic mode is off, eMake ignores irrelevant switches or exits without warning if it encounters unresolvable errors.


Specifies the pragma addendum file to use. This is a file containing additional pragma declarations to apply to the build.

eMake with Ninja emulation supports pragmas. Using pragmas for builds with the eMake Ninja emulation mode enabled ( --emake-emulation=ninja ) requires an addendum file that contains the pragmas for Ninja targets.

Pragma addendum files are optional with any other emulation mode. For more information about pragma addendum files, see Specifying Pragmas in an Addendum File .


Sets the priority for the current build’s use of Agents in the cluster. When set to normal, the build uses at least the minimum number of Agents set in Cluster Manager. The default setting is determined by the Cluster Manager.

This option overrides the priority associated with a build class but can be used to lower the build priority only.



All paths starting at the directories specified in --emake-read-only will be marked as read-only file systems when they are accessed on the agent. On UNIX, any attempt to create new files or write to existing files under those directories will fail with EROFS, “Read-only file system”. On Windows, it will fail with ERROR_ACCESS_DENIED, “Access is denied.”


Explicitly enables conflict detection on directory-read operations (commonly called “glob conflicts,” which is only one manifestation of the problem). Allowed values are 0 ` (disabled, the default value) and ` 1 (enabled).

If your build is susceptible to readdir conflict failures, you can enable these checks and get a correct build even if you do not conduct a single-agent build. The resulting history file is identical to a single-agent build result. Though the initial run with this feature might be over-serialized (a consequence of readdir conflicts), a good history file allows builds to run full speed, without conflicts, the next time.

You do not want to enable this option all the time. Instead, you should enable it for one run if you suspect a globbing problem, and then disable it, but use the history file generated by the previous run.

Another possible strategy to use, if you are not familiar with your build, is to enable the option until you get a successful build, and then disable it after you have a complete, good history file.

As an alternative, you can use the #pragma readdirconflicts pragma to enable directory-read conflicts on a per-job basis. You can apply it to targets or rules in your makefiles. It incurs less overhead than --emake-readdir-conflicts=1 (which enables directory-read conflicts for an entire build). You can use this pragma in pragma addendum files as well as in standard makefiles.


This option defaults to 10. If set to 0, makefiles are not added as goals at all and no remaking occurs. Setting the value to 1 is equivalent to the deprecated --emake-multiemake=0.



The resource requirement for this build.

This option overrides the build class resource request setting set on the Cluster Manager.



Specifies the eMake root directory(s) location.

Particularly on Windows, this parameter should not be used to virtualize your toolchain. Tools should be installed on each agent host for performance reasons and to avoid having to virtualize registry parts.

The semi-colon is the delimiter between drives.


build@winbuild-cm$ emake --emake-cm=winbuild-cm --emake-emulation=cygwin --emake-root=/c/cygwin/tmp;/c/tmp

Starting build: 867 make: Nothing to be done for `foo'. Finished build: 867 Duration: 0:00 (m:s) ` `Cluster availability: 100%

In this example, the C: drive is mounted on /c.


Turns build information reporting on ( 1 =default) or off ( 0 ). Information includes build time to completion and average cluster utilization .


Enables ( 1 ) or disables ( 0 ) sorting of the eMake root directories in a history file, which are sorted alphabetically by default. This option lets you control whether the order of the directories in the history file follows the order specified via the --emake-root eMake option. The default is 1 (enabled).

If you switch the value of the --emake-sort-roots option, you must first delete your history file and remove the entire contents of your eMake asset directory (the .emake directory by default). This deletes all data for JobCache, scheduling, and dependency optimization.


T urns test case mode on ( 1 ) or off ( 0 ). This option enables an execution mode specifically for test acceleration. The default is 0 (off) .

In test case mode, file system (and registry for Windows) updates from each job are discarded to disable conflict detection, history, and file-level annotation. This mode discards intermediate test results to restore agents to a pristine file system state after each test to ensure that each job runs as if no other tests ran. The results on stdout and stderr as well as the exit code and optimization data are preserved.

You must create a makefile specifically for this mode. You can use this mode with eMake in any emulation mode.



Sets the eMake file temporary directory.

Caching Commands (Dependency Optimization, JobCache, Parse Avoidance, and Schedule Optimization)


Use the specified directory for cache locations for saved dependencies (for dependency optimization), JobCache, parse avoidance, and schedule optimization.

The default name of this directory is .emake. By default, this directory is in the working directory in which eMake is invoked.


Enables the JobCache feature for all make invocations in a build. This option works for recursive and nonrecursive builds.

You can specify any comma-separated list that includes one or more of the following values: cl, clang, clang-cl, gcc, jack, or javac. For details about these compiler options, see the “ Job Caching ” section.

--emake-optimize-deps= <0|1>

Use the saved dependency information file for a makefile when dependencies are the same and save new dependency information when appropriate.

--emake-optimize-schedule= <0|1>

Turns the schedule optimization feature on ( 1 =default) or off ( 0 ). This feature uses performance and dependency information from previous builds to optimize the runtime order of jobs in subsequent builds.

--emake-parse-avoidance= <0|1>

Avoid parsing makefiles when prior parse results remain up-to-date and cache new parse results when appropriate.


Ignore the named environment variable when searching for applicable cached parse results. To ignore more than one variable, use this option multiple times.


Ignore this file or directory when checking whether cached parse results are up-to-date. Append % for prefix matching. To ignore more than one path or prefix, use this option multiple times.

--emake-suppress-include= <pattern>

Skip matching makefile includes (such as generated dependencies). Generally, you should not suppress makefile includes unless they are generated dependency files, and you have enabled automatic dependencies as an alternative way of handling dependencies.

If the pattern does not have a directory separator, then the pattern is compared to the include’s file name component only. If the pattern has a directory separator, then the pattern is taken relative to the same working directory that applies to the include directive and compared to the included file’s entire path.

UNIX-Specific Commands


Use this option to choose a specific operating system, so Cluster Manager will use Linux or Solaris hosts, specifically.


Allows you to set the iconv locale. Use iconv -l to list the available locales.


If you receive an emake assertion failure that contains information similar to:

emake: ../util/StringUtilities.h:406: std::string to_utf8(const std::string&): Assertion `c != iconv_t(-1)' failed.

This could mean that your system is missing an internationalization package, or the locale package has a different name for ISO 8859-1. (This issue is because of the conversion between 8-bit strings and UTF-8.)

For example, your system recognizes “ISO8859-1”, “ISO_8859-1”, and “ISO-8859-1” only. Set ECLOUD_ICONV_LOCALE to one of those valid locale names.

Windows-Specific Commands


Sets case sensitivity for target and pattern name matching. This is inherited by all submakes in the build. The option applies when using gmake or cygwin emulation modes only; nmake and symbian modes are not affected.

The default for gmake and cygwin is on ( 1 ).



Y =requires cygwin1.dll N =ignore cygwin1.dll A =use cygwin1.dll if available Default= A, if launched from a Cygwin shell, if not, then N. Default= Y, if eMake emulation=cygwin was set.

--emake-ignore- cygwin-mounts= <mounts>


Comma-separated list of Cygwin mounts to ignore. Unless listed, Cygwin mount points are replicated on the Agent.


Limits the number of registry keys sent automatically for each key. Default= 50.


Sets the registry virtualization path on Windows machines. The syntax is --emake-reg-roots=path[;path].

Do not use this parameter to virtualize your toolchain. Tools must be installed on each agent host for performance reasons and to avoid figuring out which registry parts to virtualize.

Debug Commands



Sets the local debug log level(s). For a list of possible values, see the `emake --help ` message.



Sets the debug log file name. Default is stderr.

The following macros are available:

@ECLOUD_BUILD_ID@ expands into the unique eMake build ID.

@ECLOUD_BUILD_TAG@ expands into the build tag from the Cluster Manager (this is displayed in the Name column on the Build tab in the Cluster Manager UI).

@ECLOUD_BUILD_DATE@ expands into an 8-digit code that represents the local system date where the build began, in the form YYYYMMDD.

@ECLOUD_BUILD_TIME@ expands into a 6-digit code that represents the 24-hour local system time where the build began, in the form HHMMSS.


results in: logfile-4- default_4_20090220184128- 20090220-184128.xml



Sets the remote debug log level(s). For a list of possible values, see the emake --help message.

Enabling this option disables parse avoidance.



Sets the directory for remote debug logs.

Local Agent Commands


Instructs eMake to use any available local agents

  1. The default is:

    • y if you specified a Cluster Manager or if agents appear to be running

    • n if you did not request a Cluster Manager and it appears that local agents are unavailable

If you have installed local agents (and they are currently running), but you do not want to use them, then specify --emake-localagents=n (with or without the --emake-cm option). This lets you use cluster agents only (without needing to shut down running local agents).

If neither is specified but eMake detects that agents are running on the host, eMake uses them as if you specified --emake-localagents=y. The Cluster Manager prefers to allocate agents to eMake that are on the same host as eMake.

You cannot use --emake-cm and --emake-localagents=y in the same eMake invocation.

Local agents appear on the Cluster Manager with no special configuration needed. You can enable and disable local agents from cmtool just like remote agents.

“Sharing” local agents is only minimally supported without a Cluster Manager. You can run multiple eMake instances and explicitly limit them to a subset of the total local agents, but more dynamic sharing does not occur. If you want more sophisticated sharing, then you should use a Cluster Manager.


Limits the number of local agents used. N=0 uses all available agents (default 0).


If using more than N local agents, eMake releases the number of agents over N every T seconds so they can be used by another eMake that is looking for local agents.