Skip to content

CompilingFirstSteps

Jump to bottom
David Jewsbury edited this page Feb 6, 2016 · 17 revisions

#Getting started compiling XLE

The first few steps for compiling XLE are a little complicated. Engines are big, and there's a lot of surface-area to make compilation difficult.

In many cases, XLE can be compiled without any special changes. But here is a step-by-step process.

##Basic requirements (Windows)

XLE currently only includes project files for VS2013 (with Update 3). However, VS2015 is also supported (see below) If you need Visual Studio, you can get a "community edition" from http://www.visualstudio.com.

For windows development, you should have the following installed:

  • Windows SDK 8.1 or Windows SDK 10 (search for Windows SDK on MSDN.microsoft.com)
  • XLE compiles against DX11.1 -- so you will need recent DirectX headers
  • Java runtime (https://java.com/download)

(You also need .Net 4.0. But that should be included with Visual Studio).

###Important note

Building in Visual Studio will execute a javascript script that will modify some of the .obj files. This is for recording build time and date. On some PCs it's possible that executing javascript will be disabled for security. That's ok, it just means that build date and some version information won't be available. To see the scripts, look in Solutions\BuildScripts.js. Note that this script will execute "git describe" so it needs to be able to find a version of git.exe to execute. I use javascript and the Windows Script Host for this because it's available on all Windows PCs without any extra dependencies (though these particular scripts are limited to Windows PCs)

##First Steps

There are some (optional) environment variables that you can use to customize your environment.

Variable Value
WINSDK_DIR The install directory for the Windows 8.1 SDK (default: C:\Program Files (x86)\Windows Kits\8.1). This can be skipped if the SDK directories are setup in Visual Studio options. See x86.props and x64.props for details about how this is referenced.
XLE_DIR Root XLE directory (eg, c:\XLE). This can be skipped if just compiling the samples for XLE. But game code that uses XLE won't sit in the same directory structure as XLE, so we need this define to find XLE header #included from game code.

You must make sure that Visual Studio can find java.exe.

  • You can add java to your path
  • or you can use the "Executable Directories" part of your Microsoft.Cpp.*.user.props

Java is used to execute Antlr, which is used for the shader parser. This is executed via a custom build step from Visual Studio. You don't need this for normal usage. If you don't want to install Java, feel free to remove all of the projects from the "Tools/ShaderTool" folder in the solution.

##Optional installs

XLE can link against the ambient occlusion dll from nVidia's Gameworks Visual FX. It's a quite good ambient occlusion implementation, and it's used in a number of high end games.

In fact, nVidia's solution is so good, I haven't bothered to implement a separate AO implementation in XLE. I recommend grabbing the nvidia solution from here: https://developer.nvidia.com/shadowworks.

Install to the folder:

  • XLE\ForeignNonDist\GFSDK

You can enable it by setting the define AO_IMPLEMENTATION to AO_IMPLEMENTATION_GFSDK in SceneEngine\AmbientOcclusion.cpp

You may need to copy the .dll files to the XLE\Finals_* directories

##Windows 10 notes

To run in debug mode, you need to install the "DirectX 11 Debug Layer for Windows 10." This is an important debugging library for graphics development. DirectX will complain if you don't have it installed.

The easiest way to get it is to install the Windows 10 SDK (from Microsoft). This should automatically install and enable it (but search on Stack Exchange if you still have problems)

##Visual Studio 2015

XLE can be compiled in Visual Studio 2015. However, the project files are still in VS2013 format. To use VS2015, follow these steps:

  1. Use the automatic conversion to upgrade to VS 2015 (ie, this will be an option when first opening the solution -- or "Retarget" the project in the solution explorer)
  2. Recompile DirectXTex libraries (by opening Foreign/DirectXTex/DirectXTex/DirectXTex_Desktop_2013.sln and doing a batch rebuild of all targets)

At the moment XLE is attempting to maintain support for both VS2013 & VS015. So please be aware that VS2015 supports some C++11/14/17 features that VS2013 does not.

##Starting compilation

Open Solutions\Global.sln. This is called "global.sln" because it contains all elements of XLE, including multiple start-up projects. XLE is split up into many smaller projects. In a game large project, the solution file may become too big to contain all of XLE as well as the game, so it's recommended to use multiple solution files for very big projects.

There is a "HelloWorld" sample. This is a good place to start. Look in the "Samples" folder of the solution.

If you've just got the latest version from git, there's a chance that there is a compile error in one of the configurations. In general, "Debug|x64" should be the best reliable configuration.

##Check for d3dcompiler_47.dll

d3dcompiler_47.dll needs to be reachable for shader compilation. If the engine can't find this, no shaders will be compiled. I've included this dll in the repository to make this step easier (it's covered under a permissive Microsoft redistribution license). However, if you're using a different output directory, you'll need to make sure this dll is accessible.

##Common errors

You may encounter one of the following errors while compiling for the first time.

Errors & Solutions
Cannot open include file: 'd3d11_1.h'
This header is part of DirectX11.1, which is distributed in Windows SDK 8.1 (or SDK 10). XLE needs some way to know where your Windows SDK is. You have 2 options. You can:
  • set your WINSDK_DIR environment variable.
  • Or (if you know what you're doing), you can modify your Microsoft.Cpp.Win32.user.props & Microsoft.Cpp.x64.user.props files to point to the "shared" and "um" include and library folders in the sdk
fatal error C1192: #using failed on '..\Finals_Debug64\LevelEditorCore.dll'
This can happen when attempt to compile a Level Editor project in Win32 configuration. The level editor is only enabled to compile in x64 builds. You can run the projects in the "Samples" folder in Win32 builds. But you must use a x64 configuration to run the LevelEditor.
warning msb3245: Could not resolve this reference. Could not locate the assembly "Microsoft.Windows.Shell"
Visual Studio must be trying to recompile a "ribbon" for a toolbar in a GUI app. This should not normally happen. But you can compile the ribbon by installing Microsoft Ribbon For WPF. See https://msdn.microsoft.com/en-us/library/ff799534.aspx
Failure during conversion to COFF: file invalid or corrupt
This is a known bug in some versions of Visual Studio. You may need to upgrade to the latest version of Visual Studio. Search on www.visualstudio.com.
After running, just get a lot of InvalidResource exceptions
Make sure you have d3dcompiler_47.dll in the same directory as your executable. See the section on this page.

If your OS is set to certain code pages, you might also see UTF-8 related compile errors. This happens if there is an extended character in a source file. If the character is in a comment, feel free to delete the comment. Otherwise you can try loading Visual Studio in the en-US locale.

##Dev team contact

The build process is complicated, so you may encounter problems. If you can't compile, please contact the dev team at: xle@xlgames.com.

##Improvements required

Future improvements to make it a little easier

  • Setup precompiled headers for faster compiles

XLE

Back to Home

Recommended pages:

Also:

Appveyor CI page BuildStatusBadge

Clone this wiki locally