Using the Proxy Command
Normally, eMake sends commands to the agents for execution. In some cases, however, it might not be desirable or possible to execute a particular command on the agents.
During installation, the
proxyCmd binary is installed on every host:
When invoked by the Agent, it is:
proxyCmd <program> <arg1> …
CloudBees Build Acceleration executes < program > on the host build system and proxies the result back to the Agent so it can continue remote execution.
You can use the “proxy command” feature to run a command locally on the eMake machine if both of the following are true :
You have a command that cannot run on the Agent, either because it returns incorrect results or because it is not available.
The command in question does not read or write build sources or output —it only makes external [outside of the build] read-only queries.
The second item is particularly important because the command runs on the host build machine, outside of the virtualized file system. Because CloudBees Build Acceleration cannot track the activity of this process, the dependency and conflict resolution mechanisms that prevent build output corruption are circumvented. It is also important that the process is read-only [that the command make no changes to whatever system it is querying] because in parallel builds with conflicts, eMake could rerun the job producing unintended side effects.
|For these reasons, it is important to use the “proxy command” only when necessary. Where possible, try to ensure cluster hosts have the same tools installed as the build system.|
The simplest safe use of the
proxyCmd is a source control system query. For example, a particular build step queries the source control system for branch identification using a tool called
getbranch that it embeds in a version string:
foo.o: gcc -c -DBRANCH=`getbranch` foo.c
It is preferable to avoid installing and configuring a full deployment of the source control system on the host when only this simple query command is needed.
In the following example, the
proxyCmd provides an efficient solution. By replacing
proxyCmd getbranch, you avoid having to install the
getbranch tool and its associated components on the host:
foo.o: gcc -c -DBRANCH=`proxyCmd getbranch` foo.c
A less invasive implementation that does not require makefile modifications and allows compatibility with non- CloudBees Build Acceleration builds is to create a link on all agent machines using the name of the tool [for example, 'getbranch'] found on the eMake host to
proxyCmd. For Windows operating systems that do not support
symlinks, use the
copy command. When invoked under a different name,
proxyCmd knows to treat the linked name as the < program > to execute:
# ln -s /opt/ecloud/i686_Linux/bin/proxyCmd /usr/bin/getbranch