Code compilation

When you implement Enlighten you can almost always just use the precompiled libraries and sample applications. In rare circumstances you may wish to compile the libraries and sample applications from source.

You can compile in any version of Visual Studio using the provided Enlighten.sln file.

Compilation on the command line

The code is built by a custom tool called the CodeBuildTool. This can be found in the BuildTools folder of the distribution. The inputs to the tool are:

• A .vcxproj file containing the source file list.
• An .xml file containing metadata about the project.
• (Internally) Descriptions of the tool chains that can be used.

For example:

CD /d E:\Enlighten_3.XX
BuildTools\CodeBuildTool build DEBUG_WIN32_2010 Src\Samples\Programs\GeoRadiosity\GeoRadiosity.vcxproj

Build targets

The build target name is case insensitive, and broken into three parts: <Configuration><Platform><ToolSet>

Configuration

The debug configurations differ from the release configuration in these respects:

• Debug configurations use the debug version of the CRT on platforms that support it
• On Visual Studio, the STL defined _ITERATOR_DEBUG_LEVEL and _SECURE_SCL symbols will be defined with their debug or release defaults accordingly.
• The Unchecked configuration is the same as the Debug configuration except that _ITERATOR_DEBUG_LEVEL=0 is set.
• The Checked configuration is the same as the Release configuration except that _SECURE_SCL is set.
• Debug configurations test internal assertions and will report (non-blocking) warnings if these fail using the LOG_ASSERT log type. These internal assertions are not intended for use as an error reporting mechanism, and there should be no additional warnings in normal use. Please notify Enlighten Support if you encounter any.

All configurations are optimised, but the Release configuration will outperform the Debug build. We recommend you use the configuration type that matches your CRT and STL usage.

Enlighten 3 Platforms

32 bit builds are supported for a limited subset of projects:

• Core libraries: Enlighten3, Enlighten3HLRT, EnlightenPppi, IntelTBB, Zlib.
• Sample framework libraries: GeoRender, GeoScene, GeoEn2Support, GeoRuntime, GeoPipeline, GeoExport.
• Sample framework applications: GeoViewer.

There are some platforms that cannot be built with this external tool; the MacOS and iOS implementations. Compilation instructions for these are given below.

Use and compilation of Android and iOS libraries are documented as part of the mobile documentation. Note that Android and iOS libraries are distributed separately to the default distribution package.

Toolset

Many platforms have multiple tool chains available, and Enlighten supports as many as possible natively. Where a toolset is not specified above, this section of the build target should be skipped. Whatever the current SDK environment variables point to will be used, and if this is unsupported by Enlighten an error message will be presented.

The 2017 toolset builds with MSVC compiler version 14.14 by default. To build with a different compiler, specify the compiler version: e.g. toolset 1416 builds with the 14.16 compiler.
By default, Visual Studio 2017 builds use Windows SDK 10.0.15063. You can override this in the toolset name: e.g. 1415-15063.

Packaging

The core EnlightenSDK package contains the build tools, API documentation, third party libraries and public headers for all platforms. It also contains the most common Windows binaries and libraries. Support for additional platforms are supplied in Overlays; additional zip files that are extracted to the same root folder. These Overlays include the WindowsExtra package, which includes the less common versions of the Windows libraries (all Checked and Static builds).

There are a small subset of platforms whose NDA requires that all mention of them be removed from code that is sent to unapproved developers; the packages for these include modified headers that replace those in the EnlightenSDK baseline. Usage is identical; it should be extracted to the same root folder and you must select the 'overwrite existing files' option when indicated.

Platform Specifics

Compilation on Linux

The CodeBuildTool is a .NET application, which runs under Mono 4.0.x on both Linux and OS X. On Linux all the functionality remains, accessed by the same command line arguments. All that is required is to prefix the command line with mono. For example:

cd ~/Enlighten_3.xx
mono BuildTools/CodeBuildTool.exe build DEBUG_LINUX32_GCC Src/Samples/Programs/GeoRadiosity/GeoRadiosity.vcxproj

Note that at the time of writing, Mono 4.0.x is not currently available in the Ubuntu 14.04 LTS repos, and so you will need to follow the steps at Mono to get it.

Compilation on OS X

Enlighten API and sample framework projects provided as source must be compiled on OS X using Xcode. The CodeBuildTool can be used to generate Xcode projects for you on Windows, or on OS X and Linux using mono. For example, on OS X you would open a Terminal window, change to the Enlighten-3.xx directory and execute the following command:

mono BuildTools/CodeBuildTool.exe CreateProjects OSX Src/Enlighten.sln

This will create Xcode projects for all Enlighten API source libraries and sample projects in Enlighten.sln that are supported on OS X, and then add them to an Xcode workspace called Enlighten-OSX.xcworkspace, located in the Enlighten SDK root directory. However, before you can build any of the targets you will need to do the following:

1. In the Locations tab of the Xcode Preferences window ensure that the DerivedData option is set to Relative so that the build products are built in a location that is relative to the Enlighten-OSX.xcworkspace.
2. Extract the contents of EnlightenSDK_OSX_iOS-3.x.x.zip and copy the Enlighten libraries that are not provided as source from the OSX-Debug and OSX-Release directories into the Xcode workspace build products directory. By default, for a debug build configuration, the destination directory will be EnlightenSDK-3.x.x/DerivedData/Enlighten-OSX/Build/Products/Debug/
3. Extract EffectsBuildTool_OSX.zip and copy the contents of the BuildTools directory into the EnlightenSDK-3.x.x/BuildTools directory.

Compilation for Android

When building the libraries, only the Android NDK r10d is required, but when building APKs for applications such as GeoMobileDemo, the CodeBuildTool has the following extra prerequisites:

• JDK 6
• Android SDK (android-18 and android-21 platforms, as well as the standard tools)
• Apache Ant
• KeyTool and Jarsigner (for release builds)

In order to locate the NDK, the CodeBuildTool looks for the environment variable ANDROID_NDK_ROOT to determine the root folder, and will attempt to use the Clang 3.5 compiler. For example, to locate clang++ it will look in:

"$ANDROID_NDK_ROOT/toolchains/llvm-3.5/prebuilt/windows-x86_64/bin/clang++.exe"

Similarly, the CodeBuildTool builds for the android-18 SDK platform for 32 bit, and android-21 SDK platform for 64 bit, and assumes the following directory exists for 32 bit or 64 bit respectively:

"$ANDROID_NDK_ROOT/platforms/android-18/*"
"$ANDROID_NDK_ROOT/platforms/android-21/*"

NEON intrinsics, GCC & Clang

Enlighten on ARM requires a processor that supports the NEON vector instruction set. The vast majority of modern ARM tablets and phones have this. Unfortunately, the GCC compiler version 4.4.3 that is shipped as part of the Android NDK fails with internal compiler errors. Later versions of GCC fix this issue but produce incorrect results for enough uses of NEON intrinsics that we cannot use it in practice. However, the Clang compiler, version 3.1 of which has been included in the Android NDK since revision 8c does not suffer from any of these problems, reduces compilation time and most importantly gives a significant performance improvement for Enlighten on Android.

We ship pre-built libraries (.a) and applications built with Clang 3.5 as part of the Enlighten Mobile distribution that are compatible with alternative Android toolchains. Although Enlighten does not use STL containers, algorithmic content such as <algorithm> is included from the GNU STL.

If you do use GCC version 4.4.3 you should avoid excessive use of the Geo::v128 type (an alias for the NEON vector type) to avoid triggering the internal compiler error.

If you wish to build the Enlighten libraries and sample applications for Android from source, or wish to make use of the Geo::v128 type, you will need to build with Clang, using the supplied CodeBuildTool. For example, to build a release ARM 32 bit build:

CD /d E:\EnlightenRootDir
BuildTools\CodeBuildTool build Release_Android Projects\GeoMobileDemo\GeoMobileDemo.vcxproj

Building APKs

The Release_Android configuration enables compiler optimisation level -O3 and uses Ant to sign the APK using a keystore and private key generated using KeyTool. Place your .keystore file in the EnlightenSDK-2.XX\Src\Samples\Programs\<app name>\Android\Apk directory and then in the same place create a file called ant.properties. Inside ant.properties add the following parameters to specify which keystore and private key Ant should use to sign the APK:

key.store=<your keystore name>.keystore
key.alias=<your key alias>
key.store.password=<your keystore password>
key.alias.password=<your private key password>

A successful build will create an APK in EnlightenSDK-3.XX\Src\build\Output\<config>_Android\Bin\ and copy any necessary resource files into a folder alongside it. A batch file called Install_<app name>_Android.bat will also be copied to that location which can be used to install the app and copy its resources to the device.

Compilation for iOS

Pre-built Enlighten libraries compatible with both iOS devices and the iOS Simulator are provided, some of which are also shipped as source. If you would like to build these libraries and the sample applications (such as GeoMobileDemo) from source you will need to create the appropriate Xcode projects and workspace. The CodeBuildTool can be used to automate this process for you on Windows, or on OS X and Linux using Mono 4.0.x. For example, on Mac OS X you would open a Terminal window, change to the Enlighten-2.xx directory and execute the following command:

mono BuildTools/CodeBuildTool.exe CreateProjects IOS Src/Enlighten.sln

This will create Xcode projects for all Enlighten source libraries and sample projects in Enlighten.sln that are supported on iOS, and then add them to an Xcode workspace called Enlighten-IOS.xcworkspace located in the Enlighten SDK root directory. Before you can build any of the sample projects you will need to do two things:

1. Extract the contents of EnlightenSDK_OSX_iOS-3.x.x.zip and copy the Enlighten libraries that are not provided as source from the IOS-Debug and IOS-Release directories into the Xcode workspace build products directory. By default, for a debug build configuration, the destination directory will be EnlightenSDK-3.x.x/DerivedData/Enlighten-IOS/Build/Products/Debug-iphoneos/
2. Copy the EffectsBuildTool_OSX directory from EnlightenSDK_OSX_iOS-3.x.x into the EnlightenSDK-3.x.x/BuildTools directory.

External libraries

When you run the CodeBuildTool for the first time, it reports any missing libraries in the output. Libraries are found by looking for environment variables, such as DXSDK_DIR. If any are not set, or set incorrectly, they will be reported and the build will stop.

Sample Framework tools

In order to rebuild the shaders and related support files for the Sample Framework applications, there are some platform-specific tools included in the distribution. As long as the individual platform support packages are extracted over the SDK, these should be found automatically.

C# compiler warnings

The MSBuild environment of Visual Studio expects you to have selected the ATL/MFC components during installation, and adds these paths to the C++ linker path. When we build C# projects from the C++ project, we inherit these paths. Even though the C# compiler doesn't use them, it checks all the entries in $(LibraryPath) and quits if any are missing. The possible fixes are:

• Build from the command line rather than Visual Studio, or
• Clear the Library directories of the GeoRadiosity/GeoPrecomp2/etc projects in Visual Studio (right-click project, VC++ Directories), or
• Install the ATL/MFC components, or
• Create an empty directory at the location specified

IDE usage

The Visual Studio solution provided can build all the above target configurations, but it may be necessary for you to edit a configuration file if you wish to use a specific toolset. For example, in the solution window there is only one entry for Win32, so we provide a mapping for what toolset to use in the BuildTools/Geomerics.Cpp.props file. If you change here what $(Platform)=='Win32' equates to, you can build VS2012 from VS2010 and vice-versa. Note that we do not automatically change the toolset we compile with when you change IDEs.

Compilation flags

You can see the exact command line used, and therefore all options passed to the compiler, by setting an environment variable before the build:

CD /d E:\Enlighten_3.xx
SET geo.PrintDebugInfo=true
BuildTools\CodeBuildTool build DEBUG_WIN32_2010 Projects\GeoRadiosity\GeoRadiosity.vcxproj

This allows you to inspect all flags and #defines passed to the compiler, as well as any library locations found.

For advanced debugging, .cmd batch files can be found in the build/Intermediate folder. The build generates these files for each tool (compiler/linker/etc.) invocation. These files show the exact command line used, but note that they are a side-effect of the dependency tracking system and are written (but not executed) on each run.