CloudBees Build Acceleration virtualization

Files are the most important resource to distribute to hosts. When eMake starts, it is given a directory (or list of directories) called EMAKE_ROOT. All files in eMake root(s) are automatically mirrored on cluster hosts for the build duration. This powerful feature means you do not need to configure file sharing between the build system and the cluster—simply specify the EMAKE_ROOT and the hosts can access files on the host build system.

Almost any file visible to the host build system can be mirrored to the cluster — regardless of how the host system accesses that file (local disk, network mount, and so on). Both sources and tools can be mirrored, but there are important flexibility/performance “trade-offs” to consider when you include tools in the eMake root. See Configuring Your Build.

When the build completes, EFS is unmounted and the files are no longer visible on the hosts — this ensures builds do not interfere with local host configuration.

Generally, EMAKE_ROOT can be set to include any existing directory on the host build machine. Files in these directories are automatically accessible by commands run by agents. The exceptions are detailed in Setting the eMake Root Directory.

A side effect of running builds on Windows: Windows might execute tools that modify the system registry. For example, a build job step might install a program that includes registry modifications that are executed by a subsequent step. If job steps are run on different Agents without registry virtualization, the build might fail because registry modifications on one machine are not visible on another. CloudBees Build Acceleration solves this situation by mirroring the Windows registry in addition to the file system. You can specify a registry root using the command line --emake-reg-roots=<path>. Just as EMAKE_ROOT specifies a host file system subset to mirror, the registry root specifies which registry keys should be virtualized to Agents (for example, HKEY_LOCAL_MACHINE\Software\My Product ). Access and modifications to keys and values under the registry root on Agents are then sent back to the host build system to ensure correct values are propagated to other Agents.

As with the file system, registry mirroring is active during the build only. After the build completes, the registry returns to its original configuration. Processes not running under an Agent on a host cannot see mirrored files and registry entries—they will see only the usual view of the machine.

The same user ID is used by the Electric Agent [running on each host, executing processes] and the eMake process started on the host build system. Using the same user ID ensures processes have the same permission and obtain the same results from system calls (such as getuid ) as they would running serially on the user machine. On Windows, processes are executed by the Electric Agent service user.

The Agent user can be configured at installation time, see the CloudBees Build Acceleration Installation Guide.

When eMake sends commands for execution to the Agent, it also sends environment variables. In most cases, this automatic environment virtualization is sufficient. Typically, variables that specify output locations, target architecture, debug-vs.-optimized, and so on, are propagated to tools on the host and their remote behavior correctly matches what they do locally. By default, environment variables sent by eMake override system-wide settings on the host.

For certain variables, override behavior is not desirable. For the build to operate correctly, tools running on the hosts must see the value from the local Agent, not the host build system. For example, the Windows SYSTEMROOT variable depends on the directory where Windows was installed on that machine—values might vary in different Window releases. The SYSTEMROOT value from the host build system is frequently different than the value from the local Agent.

To accommodate these instances, eMake allows you to exclude specific environment variables from virtualization. In addition to variables you might explicitly choose to exclude, eMake automatically excludes the TMP,TEMP, and TMPDIR variables on all platforms; and the COMSPEC and SYSTEMROOT variables on Windows. For a complete description of environment variables, see eMake Command-Line Options, Variables, and Configuration File