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 <enlighten root>
BuildTools\CodeBuildTool build DEBUG_WIN64_2019 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 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.

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.16 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.

The 2019 configuration builds with toolset 14.29. To build with a different toolset, specify the toolset version: e.g. configuration 1428 builds with the 14.28 toolset.

By default, Enlighten builds against Windows SDK 10.0.19041. You can override this in the configuration name: e.g. 1428-19041.

The 2022 configuration builds with toolset 14.39. To build with a different toolset, specify the toolset version: e.g. configuration 1439 builds with the 14.39 toolset.

By default, Enlighten builds against Windows SDK 10.0.22000. You can override this in the configuration name: e.g. 1439-22000.

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.

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 Win64, so we provide a mapping for what toolset to use in the BuildTools/Geomerics.Cpp.props file. If you change here what $(Platform)=='Win64' equates to, you can compile with a toolset from a different version of Visual Studio. The toolset used by CodeBuildTool is entirely independent of the IDE version.

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 <enlighten root>
SET geo.PrintDebugInfo=true
BuildTools\CodeBuildTool build DEBUG_WIN64_2019 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.