Home >> Programming >> Irrlicht >> Irrlicht Unity Build

Irrlicht Unity Build

Irrlicht 1.4.2 - Unity Build


  1. Revision Log
  2. Introduction
  3. Installation
  4. Compilation Timings
  5. Further Improvements
  6. Links

1. Revision Log

Version 1.0 - 9 Nov 2008

  • Initial release

2. Introduction

This is a project build configuration to compile Irrlicht engine using "Unity build" configuration.

Unity build is a compiler optimisation technique to speed up compilation time of large project with multiple source files. See the section "Compilation Timings" to see how much speed improvement this has brought about, and "Further Improvements" for ways to possibly improve it.

The basic idea is to reduce build times through reducing file i/o. To achieve that, use preprocessor #include to collect many .cpp files together into a larger "compilation unit"/"unity" .cpp file before compiling them. The time savings come from (my guess)

  • fewer .obj files created
  • fewer files to link together
  • fewer files for anti-virus to scan
  • fewer process startup and shutdown overhead, since one instance of cl.exe is executed for each .cpp file that is being compiled

The approach for Irrlicht unity build here is to be as unobtrusive to the project as possible (i.e. not to touch any of the original Irrlicht files if possible). So a separate Irrlicht project with identical configuration is created and modified to

  • manually handcode in the unity cpp files
  • manually exclude irrlicht source files from compilation

In the first link below, the approach is to create new unity build configurations. That could be something for the developers to do since it means having to modify the Irrlicht .vcproj file

3. Installation


  • Irrlicht 1.4.2 SDK
  • Note: Only Visual C++ 2005 project file is included


  • Irrlicht8.0_Unity.vcproj
  • Unity_all.cpp
  • Unity_gui.cpp
  • Unity_io.cpp
  • Unity_irr.cpp
  • Unity_scene.cpp
  • Unity_video.cpp
  • readme.txt

Using the Files:

  1. Create a folder Irrlicht_Unity in %Irrlicht_root%\source
  2. Put all the files listed above into this folder
  3. Add Irrlicht8.0_Unity.vcproj into %Irrlicht_root%\source\Irrlicht\Irrlicht8.0.sln
    For other Visual C++ editions, create a new Visual Studio project with exactly the same configuration as the default Irrlicht project, and apply the difference found between Irrlicht8.0.vcproj and Irrlicht8.0_Unity.vcproj
  4. (You may want to enable build timings to compare the build durations) Compile both projects, and compare the build times

4. Compilation Timings

Test Machine Configuration:

  • AMD Athlon XP 3000+ (2.4 GHz)
  • 1 GB DDR RAM
  • Seagate 200GB SATA I HDD
  • Windows Vista
  • Visual C++ 2005
  • Note: Direct X 8 and 9 video drivers are turned off due to no DirectX SDK installed, so all built times below will actually be higher with DirectX video drivers compiled. And also as a consequence, the unity build was not optimised for DirectX video drivers

Build Timings (in Minutes:Seconds)

 Irrlicht (normal)Irrlicht (unity)
Release Build2:001:04
Debug Build1:230:28

5. Further Improvements

  1. 1. Using precompiled libs for external libraries (eg libjpeg, libpng, zlib)
    • Assuming these external libs are used unmodified, it makes no sense to build them all over again with each engine rebuild. Of course these files do not get rebuild after the first time, after which only incremental changes are made to the project files
  2. 2. Fix the codes that prevents certain .cpp files from getting included in the unity build project
    • Because unity build is simply putting many .cpp files into a few larger .cpp files and compiling them, certain variable/macro declarations could get redefined in the unity files, resulting in compiler errors. With careful symbol declarations and their careful placements, these compiler errors can be eliminated. So far, the main groups of files with this problems are:
      • libjpeg
      • zlib
      • OpenGL video driver (due to it using libjpeg)
      • Burning video driver (due to enum redefinitions of ETriangleRenderer in EBurningFFShader in IBurningShader.h)
      • DirectX 8 & 9 video drivers (There are simply untested)
  3. 3. Make use of Visual Studio 2005/8's concurrent build capability for multi-core machines
    • Split up the engine into multiple lib/dll projects so Visual C++ 2005 can compile each project concurrently
    • Visual C++ 2008 can compile .cpp files concurrently, so using a few unity cpp files can do the trick
  4. 4. Use a script that is triggered pre-build to create the unity files. This will reduce the amount of housekeeping when adding/removing files from the project during the normal course of project development

6. Links