To allow parallel building of Windows code, CloudBees Build Acceleration virtualizes the registry and the file system. The following sections discuss important registry information.
There are two relevant areas of registry usage during a build. By default, CloudBees Build Acceleration virtualizes HKEY_CLASSES_ROOT (except HKEY_CLASSES_ROOT\Installer and HKEY_CLASSES_ROOT\Licenses).
HKEY_CLASSES_ROOT
This key contains file name extensions and the COM class registration (https://learn.microsoft.com/en-us/windows/win32/sysinfo/hkey-classes-root-key). Configuration data is stored under the program IDs, CLSID, Interface, TypeLib, AppId, and so on.
For entities created during the build, this information must be virtualized to all involved agents.
The following information is registered for a type library:
\TypeLib\{libUUID} \TypeLib\{libUUID}\major.minor = human_readable_string \TypeLib\{libUUID}\major.minor\HELPDIR = [helpfile_path] \TypeLib\{libUUID}\major.minor\Flags = typelib_flags \TypeLib\{libUUID}\major.minor\lcid\platform = localized_typelib_filename
Other entities that are registered by UUID are registered in different places:
A ProgID("ApplicationName") maps to and from a CLSID(GUID). The CLSID maps to the actual ActiveX component ("APP.EXE"). The type library is available from the CLSID:
\CLSID\TypeLib = {UUID of type library} \CLSID\{UUID} = human_readable_string \CLSID\{UUID}\ProgID = AppName.ObjectName.VersionNumber \CLSID\{UUID}\VersionIndependentProgID = AppName.ObjectName \CLSID\{UUID}\LocalServer[32] = filepath[/Automation] \CLSID\{UUID}\InProcServer[32] = filepath[/Automation]
Applications that add interfaces must register the interfaces, so that OLE can find the appropriate remoting code for interprocess communication. By default, Automation registers dispinterfaces that appear in the .odl file. It also registers remote Automation-compatible interfaces that are not registered elsewhere in the system registry under the label ProxyStubClsid32 (or ProxyStubClsid on 16-bit systems).
The syntax of the information registered for an interface is as follows:
\Interface\{UUID} = InterfaceName \Interface\{UUID}\Typelib = LIBID \Interface\{UUID}\ProxyStubClsid[32] = CLSID
All other keys
Other keys are probably not relevant to the build. HKEY_LOCAL_MACHINE, HKEY_CURRENT_USER, HKEY_USERS, and HKEY_CURRENT_USER are machine specific. If other areas must be virtualized, you should add them to the emake-reg-root option.
When a process in the build requests information from the registry, EFS first checks if the requested key is present in its cache. If the key is not present, EFS relays the request to the agent, which then sends the request to eMake. After receiving the response from eMake, the agent loads the key into the EFS cache, subject to the following conditions:
-
If the key is not in the local registry on the agent host, the value from the eMake response is used unconditionally.
-
If the key is in the local registry, the value from the local registry has precedence over the initial value from eMake, but not any value set by prior commands in the build. That is, if the key changes during the course of the build, the new value is used instead of any value from the local registry.
The order of precedence is (lowest to highest):
-
Value from eMake host registry before the build starts
-
Value from the agent host registry, if any
-
Value set by an earlier job in the build
The additional checking of precedence lets CloudBees Build Acceleration operate with tools that store host-specific licensing information in the registry. If the agent simply used the value from eMake unconditionally in all cases, such tools would fail to operate correctly.
CloudBees strongly recommends against running builds locally on agent host machines. Running builds locally on agent host machines might add relevant keys to the local machine, which take precedence over the eMake machine’s keys. If a key that should come from the eMake machine (such as the typelib information for a lib generated during the build) is already present on the agent because of a local build, the wrong information is used, which might break a build.If an agent machine has locally-created keys, remove the typelibs that are created during the build from the registry. Any typelib with an invalid path name associated with it is a likely candidate for an “underlayed” lookup.
Ideally, typelibs created by a build are known. At this point, you should check for their existence on the cluster. If an error occurs that indicates the direction of this problem (for example, a library/typelib cannot be found), investigate the failing agent’s registry.
You can add a multistring registry value to the agent host inside HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ElectricFS to exclude processes from interfering with EFS and causing a crash. The ExcludeProcessList entry can list processes from McAfee AntiVirus (for example, Mcshield.exe and mfevtps.exe) or other antivirus software.
| Make these registry changes only if the system crashed previously. |