Incredibuild FAQ (snapshot)

... see http://www.xoreax.com/support_faq.htm for the actual FAQ

Incredibuild FAQ (snapshot)
- Index
- Q&A

We do our best to provide answers to try and answer the most frequently asked questions in this section. If you do not find an answer here, or find the information provided unsatisfying, please let us know by sending mail to support@xoreax.com and we will try to respond as promptly as possible.

Index

Pricing & Licensing

Technical Information

What is required from me in order to install IncrediBuild for evaluation in a networked environment?
Am I creating a dependency of any kind on IncrediBuild? Can I still use Visual Studio's Build command with IncrediBuild installed on my machine?
Am I required to make changes in my C++ project for IncrediBuild to work?
How will the MS Visual C++ environment change after installing IncrediBuild?
Can IncrediBuild be used from the command-line or from build scripts?
How can I know how effective IncrediBuild will be when used to compile my C++ project?
What types of file formats can IncrediBuild accept as input?
Can IncrediBuild alter the compilation or link process, potentially creating problems in the build output?
Can IncrediBuild slow down other user's machines in my organization as a result of the Distributed Compilations process?
What are the software prerequisites for installing IncrediBuild?
Won't IncrediBuild use up all of my LAN bandwidth?
My workstations do not share the same configuration. They have different operating systems, versions of MSVC, service packs, dll versions etc. Will this pose any problems?
I understand that IncrediBuild is using network protocols to move files around and execute programs. What precautions have you taken to make IncrediBuild safe from security threats?
My project makes use of the Precompiled Headers functionality to speed up compilation. Can IncrediBuild still help me?
I'm using Visual Studio's browse information functionality. Will this still be available to me if I use IncrediBuild?
Some of my projects contain custom build steps and post/pre-link steps. Will IncrediBuild cope with that?
My project uses COM objects, and requires DLL's and type libraries to compile some of my files. How does IncrediBuild handle this?
Some of my source files are located on network drives. How will this affect IncrediBuild's behavior and performance?
How does IncrediBuild determine which machines will participate in a build?
What happens if several Agents start a build simultaneously?
What happens if the Coordinator becomes unavailable for some reason during a build?
What happens if an Agent that is compiling for a remote machine suddenly becomes unavailable during a build?
I'm using a compiler/linker different from MSVC's for better code optimization. I still develop and build my project using Visual C++. Will IncrediBuild support the compiler I'm using?
What programming languages does IncrediBuild support?
Does IncrediBuild support multi-processor machines?
Does IncrediBuild support Microsoft Visual C++ .NET (7)?
Does IncrediBuild support Xbox projects?
Can I use IncrediBuild on a standalone machine?
Am I required to manually copy files between machines, register DLLs or perform any preliminary action after installing IncrediBuild for my project to compiler?
How many Agents can there be in an IncrediBuild environment?
Is it OK to put an Agent in the same machine as the Coordinator?

Troubleshooting

Q&A

Pricing & Licensing

Q: How many Coordinators and Agents should I buy?

A: This depends on the number of developers you wish to use IncrediBuild. The best way to figure out which license structure best suits your need is to try the IncrediBuild Purchase Assistant. This will give a detailed explanation as well as a price quote.

Q: What exactly does the number of Agents in the license determine?

A: The number of Agents in the license determines the number of computers that have IncrediBuild Agent installed. This includes both machines that are used to build projects and machines that are only used as a resource for other machines' compilations.

Q: Are site licenses available?

A: Yes, contact sales@xoreax.com for more details.

Q: How do I add more Agents to an existing license?

A: Send a mail to sales@xoreax.com stating your current license details and required change in the license. We will contact you and provide you with the updated license.

Q: After purchasing a license, can I change the machines that have Agents installed?

A: Yes. This will involve a simple process in which the old Agent must first be "unsubscribed" and the new one "subscribed". Both operations are performed centrally from the IncrediBuild Coordinator application.

Q: My trial period has expired, and I need a few more days to finalize the purchase procedure. Can I get an extension?

A: Sure. Just fill in the Trial Period Extension Form and you should receive a 2-week extension key within a couple of days.

General Information

Q: What is required from me in order to install IncrediBuild for evaluation in a networked environment?

A: Typically less than 15 minutes of your time. Upon downloading and running the Setup program, you will be required to install the Coordinator component on one computer (a desktop P.C. will do). After this simple wizard-based process, use the setup program to install the Agent component on some P.C.s connected to the local network (The setup of an Agent machine typically lasts less than a minute, not even requiring a reboot). That's it! IncrediBuild is ready to build.

Q: Am I creating a dependency of any kind on IncrediBuild? Can I still use Visual Studio's Build command with IncrediBuild installed on my machine?

A: MSVC's standard Build operations (from Visual C++'s graphical environment and from the command line) can be used at all times regardless of IncrediBuild's presence. What this means is that in the worst scenario you will always have the option to go back to building as usual. If build scripts are used, they will have to undergo a minor change (replacing VC's command-line build tool with IncrediBuild's).

Q: Am I required to make changes in my C++ project for IncrediBuild to work?

A: No. IncrediBuild will build any Win32 C/C++ project that can be built using Visual C++. Note that in some cases it will be necessary to add project dependency information to allow multiple projects to be built in the correct order.

Q: How will the Microsoft Visual C++ environment change after installing IncrediBuild?

A: An IncrediBuild menu and toolbar containing Build, Rebuild, Clean, Batch Build and Stop Current Build commands will become available. Simply use these commands instead of VC's. When building, the output will be displayed in a special "Build Monitor" display (also integrated with the environment), that will contain the build output as well as many other useful features such as a build progress bar, a visual display of the progress, timings and so on.

Q: Can IncrediBuild be used from the command-line or from build scripts?

A: Yes. IncrediBuild includes a strong command-line interface for building projects, which can easily be integrated in any script that either runs MSDEV to build projects or NMAKE to build MSDEV-generated makefiles.

Q: How can I know how effective IncrediBuild will be when used to compile my C++ project?

A: The best way is to simply try it. However, experience shows that in the vast majority of projects that are over just a few files in size, IncrediBuild will reduce full build time down to around 10%-30%, and incremental build times to anything between 10% and 75% (Depending on the number of files being recompiled).

Q: What types of file formats can IncrediBuild accept as input?

A: IncrediBuild is currently compatible with Microsoft Visual C++ 6.0 project (DSP) files and workspace (DSW) files. VC 7.0 (.NET) files and standard makefiles will be supported in the near future.

Q: Can IncrediBuild alter the compilation or link process, potentially creating problems in the build output?

A: No. IncrediBuild actually uses the same components used by MSVC to compile (cl.exe), link (link.exe), build browse information (bscmake.exe) etc. IncrediBuild is not a new compiler, but rather a more efficient method of using Visual C++'s existing compiler.

Q: Can IncrediBuild slow down other user's machines in my organization as a result of the Distributed Compilations process?

A: IncrediBuild Agents automatically adjust their behavior according to the activity level in the machine they are installed on. By default, Agents run compilations with a process priority that's lower than that of other processes in the system. This makes the operating system allocate less CPU resources to IncrediBuild than to user and operating system processes. So, a P.C. that is unused will be running IncrediBuild at full pace, while on a more active P.C. the Agent will maintain its activity at a lower level. Normally, users do not even feel the presence of an IncrediBuild Agent on their machine.

Q: What are the software prerequisites for installing IncrediBuild?

A: IncrediBuild runs on Windows NT, 2000 and XP versions, on any TCP/IP based network. Microsoft Visual C++ 6.0 is required for "active" Agents that initiate new build requests. Agents that are used only as a "passive" resource and do not initiate builds do not require any special software.

The recommended hardware configuration is a Pentium machine with a 450Mhz CPU , 128 Mb RAM and 10/100 Mbps network connection.

The Coordinator component does not have any software prerequisites.

Q: Won't IncrediBuild use up all of my LAN bandwidth?

A: No. A lot of effort has been put into network optimization tactics such as caching and compression to make sure network traffic will be kept at a minimum. In standard networks IncrediBuild's presence is hardly felt at all, even when several compilations are taking place.

Q: My workstations do not share the same configuration. They have different operating systems, versions of MSVC, service packs, dll versions etc. Will this pose any problems?

A: When executing build operations on a remote Agent, all actions are performed from a virtual environment that acts as a mirror of the original building machine. This means that all files taking part in the compilation will be taken from the building machine. In fact, they don't even have to exist on the remote Agent!

Q: I understand that IncrediBuild is using network protocols to move files around and execute programs. What precautions have you taken to make IncrediBuild safe from security threats?

A: First, IncrediBuild's license configuration lists the Agents that are "authorized" to participate in the system, protecting your environment from potential attempts to misuse the system from outside the authorized working group. A lot of attention has been put into making the network protocols as safe as possible from internal threats, as well. Finally, all file activity is done within a closed virtual environment, to make sure that that your files will not be harmed even in the case of these measures failing to stop an attempt to misuse the system. In addition to these measures IncrediBuild will also benefit from any security infrastructure (firewalls etc.) installed in your organization.

Q: My project makes use of the Precompiled Headers functionality to speed up compilation. Can IncrediBuild still help me?

A: Yes, IncrediBuild supports projects using Precompiled Headers.

Q: I'm using Visual Studio's browse information functionality. Will this still be available to me if I use IncrediBuild?

A: Yes, IncrediBuild supports the creation of browse information files.

Q: Some of my projects contain custom build steps and post/pre-link steps. Will IncrediBuild cope with that?

A: Yes. Custom build steps and pre/post-link steps are executed locally on the building machine.

Q: My project uses COM objects, and requires DLL's and type libraries to compile some of my files. How does IncrediBuild handle this?

A: All compilation is done from within a virtual mirror environment that acts as a copy of the building machine's environment. This means that regardless of what files and DLLs are on the remote machine, it will produce a compilation output that's based on the DLLs and files found on the original machine.

Q: Some of my source files are located on network drives. How will this affect IncrediBuild's behavior and performance?

A: IncrediBuild can access files located on the network. In fact, it is actually more effective in this case. Because of its caching mechanism, IncrediBuild will give even better results compared to VC's when compiling projects that include files located on the network.

Q: How does IncrediBuild determine which machines will participate in a build?

A: The IncrediBuild Coordinator is aware of each Agent's CPU strength, current CPU activity level, and other factors that can affect the Agent's effectiveness in compilation. When a build starts, the Coordinator assigns the most effective 8 Agents available to that build. This initial assignment may change throughout the build as the Agent's availability changes. For example, if a user starts a CPU-intensive task on a machine participating in a remote build, that machine will most probably stop compiling immediately, and another machine will be assigned to that build in its place.

Q: What happens if several Agents start a build simultaneously?

A: In this case, the IncrediBuild Coordinator will attempt to assign Agents to the builds in a manner that will give each of the builds an equally high share of the available CPU in the system.

Q: What happens if the Coordinator becomes unavailable for some reason during a build?

A: Although the Coordinator manages the resources available for remote compilation, it is not a critical component for builds to succeed. If a build has started and the Coordinator component is for some reason unavailable, the build will continue with its current Agent assignments until it is done building. Subsequent builds will work in standalone mode until the Coordinator becomes available again.

Q: What happens if an Agent that is compiling for a remote machine suddenly becomes unavailable during a build?

A: If the Agent becomes unavailable or is simply too busy to be effective in the compilation, it will simply stop working, and the file that it has been compiling will be reassigned to another Agent. The build will continue uninterrupted.

Q: I'm using a compiler/linker different from MSVC's for better code optimization. I still develop and build my project using Visual C++. Will IncrediBuild support the compiler I'm using?

A: IncrediBuild currently does not support compilers other than Microsoft Visual C++'s cl.exe. Some compilers may be supported in the future, though. To receive updates on this, join the IncrediBuild mailing list. Any other linker that's compatible with Microsoft's will be supported, though.

Q: What programming languages does IncrediBuild support?

A: IncrediBuild supports C and C++ projects stored in Microsoft Visual C++ format.

Q: Does IncrediBuild support multi-processor machines?

A: IncrediBuild can run on multi-processor machines, but will only exploit a single processor. Full multi processor support is planned in the future, though, and joining the IncrediBuild mailing list to get a note when this is out is recommended.

Q: Does IncrediBuild support Microsoft Visual C++ .NET (7)?

A: IncrediBuild currently supports MSVC 6.0. A .NET version of IncrediBuild is expected before the end of the year. Join the IncrediBuild mailing list to get a note when it is out. Xoreax Software is currently offering a FREE upgrade to IncrediBuild .NET with every purchase of IncrediBuild - click here for more details.

Q: Does IncrediBuild support Xbox projects?

A: IncrediBuild does not currently support Xbox projects. Xbox support is planned in the future, though, and joining the IncrediBuild mailing list to get updates on this is recommended.

Q: Can I use IncrediBuild on a standalone machine?

A: Yes, although you wouldn't be getting any speed improvements... You will still enjoy IncrediBuild's enhanced output and options.

Q: Am I required to manually copy files between machines, register DLLs or perform any preliminary action after installing IncrediBuild for my project to compiler?

A: No, IncrediBuild will handle all of the synchronization itself, and will do it within a virtual environment - the computer's file system will be left unchanged, no DLLs will be installed etc.

Q: How many Agents can there be in an IncrediBuild environment?

A: The IncrediBuild Coordinator will effectively serve up to 100 Agents. In cases where more Agents are required, we recommend splitting the environment into workgroups, each with its own Coordinator. For example, in a working environment of 120 developers, 3 workgroups containing 40 Agents each will give the best results.

Q: Is it OK to put an Agent in the same machine as the Coordinator?

A: It is perfectly OK, and even common practice. The Coordinator is a lightweight component that does not take a lot of resources. Try not putting both on a machine with particularly weak hardware, though.

Troubleshooting

Q: I've noticed some files with the "ib_" prefix appear in the intermediate directory of my project during the IncrediBuild operation. Why does this occur?

A: This is normal. IncrediBuild generates separate debug information files for each of the Agents participating in the build, and these are stored in the intermediate folder.

Q: I'm comparing OBJ/EXE files that MSVC created to those of IncrediBuild - and they're not the same. Why?

A: There are some differences between IncrediBuild's output and MSVC's, caused by debug information placement, timestamps in the binary files, OBJ file order in the linking phase and so on. This is normal and will not affect the application's behavior.

Q: How can a user disable its Agent temporarily to make sure IncrediBuild will not take any of his machine's CPU?

A: By right-clicking on the IncrediBuild tray-icon and choosing "Disable Agent". This can also be done remotely from the Coordinator application.

Q: I've changed some of the directories in the "Directories" tab under the tools/Options menu, and my change doesn't seem to have effect on IncrediBuild. Is this O.K.?

A: The directories in these settings should only be used for system-wide settings, as they will affect all projects compiled on that machine. Project-level settings should always be done via the "Project Settings" dialog. MSVC stores any new or modified directory information when it is closed, so in order for IncrediBuild to be aware of the new system directories MSVC must be closed once after modifying the information.

Q: I'm trying to run BuildConsole? from the command line but keep getting the "'BuildConsole' is not recognized as an internal or external command, operable program or batch file." error. Why?

A: The PATH environment variable is not set to the IncrediBuild installation folder. Note that you can only use BuildConsole? in computers that have Microsoft Visual Studio installed.

Q: It looks like some debug information is missing. Can this be related to IncrediBuild?

A: This may be related to use of the "Separate Types" linker option. The "Separate Types" option (located in the "Linker" page, under MSVC's Settings dialog) instructs the linker to leave debug information stored in the compiler generated PDB files, instead of generating a single PDB file for the entire project. When this option is used with IncrediBuild, separate PDB files are created for each Agent participating in the build. In this scenario, if you're using debug information files that have been copied using scripts, some PDB files may not have been copied, resulting in loss of debug information. The recommended resolution is to turn off the "Separate types" linker option in the project (you can also use the built-in override option in the Agent Settings dialog). This will always guarantee a single PDB file for the project. Another alternative is to fix the relevant scripts.

Q: When building projects, only my machine's Agent participates in the build!

A: This can be caused by a number of reasons:

The project contains a very small amount of files and therefore they do not get distributed between the Agents.
The Coordinator name or port set in the Agent Settings dialog in your machine is incorrect.
The Coordinator is currently unavailable, either because the machine it is running on is shut down or disconnected from the network, or because the Coordinator service is not active.
Your machine is disconnected from the network. Check network cable and settings.
Network security restrictions are blocking TCP/IP access from your machine to either the Coordinator machine or the Agent machines in the network.
Your trial period of IncrediBuild has expired.
The Agent on your machine is not subscribed on the Coordinator machine. Check with your system administrator to see if your license allows adding your machine to the list of subscribed Agents.

Q: I can't see the IncrediBuild tray-icon display. How do I restore it?

A: Select Programs files/Xoreax IncrediBuild/IncrediBuild Agent from the Start menu to restore the tray-icon display. If you wish the IncrediBuild tray-icon to always be displayed, verify that the "Enable tray-icon display on system start-up" option is selected in the Agent Settings dialog.

Q: I've disabled the IncrediBuild Agent on my machine, but my machine seems very unresponsive. When checking the running processes in the task manager, I see a cl.exe process, although I'm not running a build. What's the problem?

A: On some versions of Windows NT, the operating system reports the screen-saver as running even when it's not. Since IncrediBuild operates as a high-priority process when the screen-saver is active, this may noticeably reduce your computer's responsiveness. To avoid this situation, open the IncrediBuild Agent Settings dialog. You should immediately receive a message stating that the screen-saver is falsely reported as active, and the option that automatically enables the Agent when the screen-saver starts will be disabled.

Q: I can't see the IncrediBuild menu/toolbar in Microsoft Visual C++! Where's it gone?

A: The IncrediBuild add-in for Microsoft Visual C++ is installed per user. If you are using a different user than the one used for installing IncrediBuild, you will have to install the add-in for your user. This can be done using the "IDE Integration" tab in the Agent Settings dialog.

If only the toolbar is missing, the explanation could be that it is simply hidden. To check if this is the case, right-click on the toolbar section in Microsoft Visual C++ and verify that all listed toolbars beginning with the word "Toolbar" are checked.

Finally, it could be that the IncrediBuild menu or toolbar were somehow not installed properly. In this case, using the "Fix menu" or "Fix Toolbar" option in the "IDE Integration" tab in the Agent Settings dialog could solve the problem.

Q: Browse information is not generated when building a project with IncrediBuild, although it is generated when building with MSVC. Why?

A: IncrediBuild keeps a global setting to determine whether to generate browse information or not. This can be set from the "Build System" tab in the Agent Settings dialog. You may also override this setting for a particular project when building a project from the batch build dialog.

Q: My project uses the /Fd compiler option. When building it with IncrediBuild, I get a warning saying the /Fd switch is not supported. Why is that and what should I do?

A: The /Fd switch (rename compiler-generated PDB file) is not supported by IncrediBuild since IncrediBuild generates separate PDB files for every Agent participating in a build - and these files naturally cannot share the same name. The solution in this case is to uncheck the "Separate Types" linker option, and rename the linker-generated PDB file instead. This will cause debug information to be stored in a single PDB file (rather than two in MSVC compilations, and more in IncrediBuild compilations) for the entire project. Scripts will only have to copy the linker-generated PDB file to allow debugging on remote machines. See the "Separate Types" topic in the MSDN library for more information.

Q: I'm getting the following warning: "IncrediBuild: build system warning: #import directives in the precompiled header should use the no_implementation attribute. See FAQ section in documentation for more details.". What's wrong?

A: IncrediBuild is notifying you of an #import directive that was found in the precompiled header source file, without the "no_implementation" keyword. This is problematic for two reasons:

You may get "file not found" compilation errors when a source file #includes a .TLI file that was generated by this PCH. Using #import with the "no_implementation" flag in the PCH file, as described below, will solve this.
Not using this keyword may slow down compilation as a result of larger PCH files.

The following excerpt is from the MSDN Library "#import" topic:

"The implementation_only attribute is intended for use in conjunction with the no_implementation attribute as a way of keeping the implementations out of the precompiled header (PCH) file. An #import statement with the no_implementation attribute is placed in the source region used to create the PCH. The resulting PCH is used by a number of source files. An #import statement with the implementation_only attribute is then used outside the PCH region. You are required to use this statement only once in one of the source files. This will generate all the required wrapper member functions without additional recompilation for each source file."

Q: When compiling, I get a "No such file or directory" error on a header file/type library file.

A: Check if this file is generated by a custom build step or a MIDL step in another project in the workspace. If so, this may be caused by a missing inter-project dependency definition in the workspace. See the documentation section on "Dependency Issues" (under "Advanced Topics") for more information.

Q: When compiling, it seems that the compiler is using a different/out-of-date version of a header file/type library file.

A: see answer in previous question.

Q: When compiling, I get the following fatal build system error:

"The following intermediate directories are shared by more than one configuration.".

What's wrong?

A: IncrediBuild does not currently allows building multiple configurations that share the same intermediate folder. To build these configurations, either build each configuration separately or change one of the configuration's intermediate folder via the Project Settings dialog in MSVC.

Q: Looking at the Output view in the Build Monitor, it looks like the display is missing output for many files that have already been compiled. What's wrong?

A: During compilation, IncrediBuild buffers the build output for some of the configurations to make sure that different configurations' output doesn't mix up. To view all output messages for each configuration, use the Projects view (note that navigating to the next warning/error using the F4/Shift-F4 keys may be helpful in this context). As soon as the build is over, the output display will contain the entire build output.

Q: When running an incremental build with MSVC after building with IncrediBuild, I get the following build warning: "warning C4652: compiler option 'Generate Browser Info' inconsistent with precompiled header; current command-line option will override that defined in the precompiled header". What is wrong?

A: There is a conflict between IncrediBuild's browse information creation options and the way MSVC handles browse information for that project. To overcome this, do one of the following:

if you wish to use browse information:
1. Set the configuration's project settings to generate browse information (this is done by checking the browse info checkboxes on both the C/C++ page and the Browse info page in MSVC's project settings dialog).
2. Set IncrediBuild's browse information creation settings (in the Agent Settings dialog) to create browse information for this configuration (this can be done by selecting "Always" or "According to DSP file", or by using a matching search phrase).
3. Rebuild the project.
If you do not wish to use browse information:
1. Set the configuration's project settings NOT to generate browse information.
2. Set IncrediBuild's browse information creation settings (in the Agent Settings dialog) NOT to create browse information for this configuration (this can be done by selecting "Never" or "According to DSP file", or by using a matching search phrase).
3. Rebuild the project.

Q: The IncrediBuild Agent fails to start on my machine. What's wrong?

A: This could be happening for a number of reasons. Here are some initial steps to help understand the cause of this:

If the IncrediBuild Agent tray-icon display indicates an error graphic, click on the tray-icon once to display the last error encountered by the IncrediBuild Agent service, and see if this leads to the source of the problem.
Try replacing the following files, which should appear in your Windows/System32 folder, by copying them from another machine, with the same operating system, that has a working Agent installed:
- perfc009.dat
- perfd009.dat
- If not, run the Windows setup installation to restore these system files.
Contact support@xoreax.com and provide as much detail as you can about the problem.

Q: When running a build, some Agents start compiling files, but stop before the compilation is finished, causing the file's compilation bar to disappear. What's wrong?

A: This could be happening because of a network configuration error. For IncrediBuild to operate properly, all of the following tests should work:

Ping the problem Agent from the building machine, using its IP address.
Ping the problem Agent from the building machine, using its network name.
Ping the building machine from the problem Agent, using its IP address.
Ping the building machine from the problem Agent, using its network name.

Q: My machine fails to run distributed builds - all files are compiled locally. Other machines are working fine. Where's the problem?

A: Try the following:

Open the Agent Settings dialog 'Network' page, and make sure that the Coordinator name and port are set correctly.
Try the 'Test' button on this page. If the test fails, this indicates a network configuration error. To locate the problem, try running a network 'PING' between the Agent and Coordinator machines, both with IP addresses and network names. All should work.
If the Coordinator displays other Agents as being 'assigned' to your machine, but these Agents never reach the 'Working for' stage, there may be a problem with the connection between your machine and other Agent machines. Perform the test described in 2. between your machine and another Agent machine.
Your trial period may have expired.

b r a y d e n . o r g / Software

Incredibuild FAQ (snapshot)