CloudBees Build Acceleration normally executes all build commands on the cluster hosts. Any file access by commands is served by the in-memory EFS cache or fetched from eMake and monitored to ensure that dependency information is captured to guarantee correct results.
Normally, CloudBees Build Acceleration executes all build commands on the Agents. Any file access by commands is served by in-memory EFS cache or fetched from eMake and monitored to ensure dependency information is captured, thus ensuring correct results. Sometimes running a command on an Agent (which could be in the cluster or local) is not preferred. For example, a command could exercise heavy file I/O, which would create overhead that degrades performance significantly. In these instances, you can use the #pragma runlocal directive in a makefile to run it locally on the host build machine (where no EFS exists to virtualize and monitor file access) instead of remotely. Sometimes it is not desirable to run a command on an Agent. In these instances, you can use the #pragma runlocal directive. In a makefile, the #pragma runlocal directive lets you specify a job to run locally on the host build machine.
| After a “run-local” job, eMake reloads the file system state for the current working directory of the Make, not the job. |
Local jobs use “forced-serial” mode. This means that eMake executes a run-local job when all previous commands are complete. Then it does not let other commands run until the run-local job is complete. In other words, while the run-local job is running, no other build steps are executed.
Jobs that are suited to running locally
Running locally is intended only for jobs that:
-
Perform heavy I/O (these jobs are inefficient to run remotely)
-
Execute near the end of the build (for example, forcing the build into serial mode would have minimal performance impact)
-
Logically produce a final output not used by steps later in the build
Therefore, final linking or packaging steps are typically the only commands that you should run locally.
Running locally is not intended for jobs that change the registry in a way that later parts of the build depend on. This is because these changes would not be visible to later jobs in the build.
Specifying jobs to run locally
To mark a job run locally, precede its rule in the makefile with #pragma runlocal. For example:
#pragma runlocalmyexecutable: $(CC) -o $@ $(OBJS) ...
You can specify #pragma runlocal for a pattern rule. In this case, all jobs instantiated from that rule are marked as run-local:
#pragma runlocal%.exe: %.obj $(CC) -o $@ $*
You can run jobs locally after a certain point in the build by using #pragma runlocal sticky. This variant specifies that all jobs later in the serial order than the job specifically marked with #pragma runlocal sticky should be run locally as if #pragma runlocal applied to all of them. This is not the same as “all jobs declared after this job in the makefile.” The order of job declaration in a makefile is not related to the serial order of those jobs.
Making eMake detect files outside the current working directory
By default, eMake cannot detect files that were created by a run-local job. Instead, it attempts to find any new files in the current working directory after the job has run. This means that by default, the run-local job must not make changes outside of its current working directory. This is because if changes occur, subsequent jobs will not see the output outside of the current working directory and could fail because precise interaction depends on the file system state when the job begins.
Sometimes, however, jobs create files outside of the current working directory. If this is the case, you must use the -repopulate option to #runlocal to tell eMake where to find them instead. This is critical if later jobs that run on agents must access the output of the run-local job. You can use the -repopulate option to tell eMake to look in one or more directories.
The -repopulate option works only when #runlocal is specified inside an eMake pragma addendum file. For details about pragma addendum files, see the “ Specifying Pragmas in an Addendum File ” section in the “Additional eMake Settings and Features” chapter.
The syntax for using the -repopulate option is:
#pragma runlocal -repopulate <dir1> [... -repopulate <dirN> ]
For example:
#pragma runlocal -repopulate ./out -repopulate ./abc/def sticky