Downloading and Compiling under Windows

From Arx Libertatis Wiki
Jump to navigation Jump to search

ℹ️  This page describes compiling Arx Libertatis from source under Windows and assumes some familiarity with the command-line. If you just want to play the game, it might be easier to grab a binary release or snapshot if available.

This page documents how to compile Arx Libertatis from https://github.com/arx/ArxLibertatis under Windows.

There are also instructions available for Linux / FreeBSD and macOS

This guide assumes use of Visual Studio 2013, but should also work with any version of Visual Studio. All file paths used here are an example (using C:\Code\Git as a base).

There's a YouTube video that goes through this process in depth: https://www.youtube.com/watch?v=2h9O82Zf3Gk

Step 1: Download Required Applications

Optional Applications

  • TortoiseGit: For better Git GUI.
  • Doxygen: For developer documentation.
  • Qt5: If you want to use the crash reporter or profiler.
    • You will need to append the full path for Qt's msvc2015_64, msvc2019 or msvc2019_64 directory to the CMAKE_PREFIX_PATH environment variable or CMake option (See below for instructions). This directory is in the Qt\[Version number] folder. Restart your shell for environment variable changes to take effect.

Step 2: Getting the dependencies

Getting all libraries to work under Windows used to require a lot of work and was error prone. Now we provide pre-built versions on the ArxWindows repo (both 32-bit and 64-bit) to simplify the process.

Windows Arx Libertatis depends on the following libraries:

  1. The ArxWindows repo only contains the Boost source. It doesn't contain any prebuilt libraries - those aren't needed for Arx Libertatis.
  1. Creative's OpenAL implementation is severely limited, which can cause missing sounds in Arx. OAL implementations from IHVs (Independent Hardware Vendors) are buggy and the cause of many crash reports.

All of the above can be obtained from the ArxWindows repo.

How to obtain them

In GitBash: 

cd /c/Code/git
git clone git://github.com/arx/ArxWindows.git --depth 1

Step 3: Getting the source code

The easiest way to get the ArxLibertatis source code for use with the ArxWindows repo is to use included git submodule config: 

cd /c/Code/git/ArxWindows
git submodule update --init --remote --recursive

Now you should have the current version of the ArxLibertis and ArxLibertatisData repositories available in the arx and data sub-directories respectively.

If you are planning to make changes to Arx Libertatis, it is a good idea to checkout the master branch at this point (git submodule update --remote will checkout the current commit for the master branch but leave repo in a detached HEAD state): 

cd /c/Code/git/ArxWindows/arx
git checkout master

Step 4: Generating the project files

We'll use CMake for that in GitBash: 

cd /c/Code/git/ArxWindows
mkdir build_vc12
cd build_vc12
cmake .. -G "Visual Studio 12"
  • "Visual Studio 12" in the command refers to using Visual Studio 2013 to generate the project. If you are using a different version, change it to the corresponding CMake generator name. Use cmake --help to check the available compilers on your computer.
  • This line will create 32-bit project files. If you wish to build Arx in x64, you will need to replace "Visual Studio 12" with "Visual Studio 12 2013 Win64" (varying the version number and year according to your VS version, of course).

If you run out of RAM during the build, disable the unity build by running cmake like this: 

cmake .. -G "Visual Studio 12" -DUNITY_BUILD=0

If you plan on adding code, it might be a good idea to use the developer mode instead: 

cmake .. -G "Visual Studio 12" -DDEVELOPER=1

This disables the unity build to allow for faster incremental builds and also enables runtime checks and debug output in the compiled binary.

Build Options

  • -DUNITY_BUILD=ON enables building of each program as one big source file. This is somewhat like link-time optimization but provides faster builds as each header only needs to be parsed once for the whole executable. It also prevents incremental builds - if you plan on using git bisect or trying a lot of small changes, consider leaving it out.
  • -DBUILD_TOOLS Defaults to ON and affects whether the project will build arxsavetool and arxunpak. Set this with the value =OFF to prevent these tools being built.
  • -DBUILD_IO_LIBRARY (default=ON): Affects building of the helper library for the Blender plugin.
  • -DBUILD_CRASHREPORTER (default=ON): Affects building of the crash reporter gui (default OFF for Mac). Note: This will not be built unless you have setup Qt.
  • -DDEBUG_EXTRA (default=OFF): Enables expensive debug options (on top of those enabled in regular debug builds).
  • -DBUILD_PROFILER_INSTRUMENT (Default =OFF): When built with this flag, Arx will dump profiler data when f12 is pressed in-game. This is useful for diagnosing performance issues. The file(s) generated will be stored in the Arx main folder as [date and time].arxprof and require the profiler to open.
  • -DBUILD_PROFILER : Builds the profiler GUI, for opening .arxprof files. Also requires Qt.

It is easier to add, remove and edit these options in the CMake GUI than in GitBash.

Step 5: Building Arx Libertatis

Now you can build the whole solution in Visual Studio. Open C:\Code\git\ArxWindows\build_vc12\ArxWindows.sln, and do as shown below.

BuildSolution.png

You can build the debug target (has debug symbols & can be debugged) or the release target (faster, but currently without debug information).

Step 6: Installing the data files

After getting the game data, you need to put the data files in a location where Arx Libertatis can find them.

By default, Arx Libertatis searches for data files (from the original game) under the following paths:

  • C:\Code\git\ArxWindows\build_vc12\arx <--preferred
  • C:\Code\git\ArxWindows\arx\data\core
  • C:\Users\[YOUR NAME]\Saved Games\Arx Libertatis

Simply place your data files into one of these directories.

    • If you want to specify your own data file location, create a Window registry key HKCU\Software\ArxLibertatis\DataDir with the value pointing to your game data directory.
    • Arx Libertatis only needs the following data files:
      • data.pak
      • data2.pak
      • loc.pak
      • sfx.pak
      • speech.pak

Finally, copy the necessary dlls to C:\Code\git\ArxWindows\build_vc12\arx\Debug because that's where your arx.exe is located 

C:\Code\git\ArxWindows\libs\sdl\bin\SDL32.dll  \\if you are using 32-bit Windows
C:\Code\git\ArxWindows\libs\sdl\bin\SDL64.dll  \\if you are using 64-bit Windows

The complete search path is described on the Data directories page.

Step 7: Running Arx Libertatis

Simply click on arx.exe under C:\Code\git\ArxWindows\build_vc12\arx\Debug or \build_vc12\arx\Release

Step 8: Debugging Arx Libertatis

  • Right click on the 'arx' project under the Solution Explorer in Visual Studio 2013
  • Select "Set as StartUp Project"
  • Change full_screen to false in %USERPROFILE%\Saved Games\Arx Libertatis\cfg.ini, as debugging in fullscreen is a pain.
    • Otherwise, you can change to full_screen after you run the game.
  • Click the "debug" button (F5) and enjoy :D
  • For Arx Libertatis debug explanation, please check out Debugging

Troubleshooting

Encounter any errors during this process? Easily done! First check you have all the necessary libraries in the right place and that their locations are all covered by the environment variables. Ensure you haven't simply copy-pasted the commands from this article; check you used the right VS version and folder paths for your setup. Configure the build in CMake GUI and pay close attention to the messages displayed at the bottom; if it doesn't complain and says it will build all the tools and options you have selected, there is probably nothing wrong with your libraries and build files.

Warnings

Visual Studio warnings are not a fatal issue, but a nuisance and sometimes avoidable. For instance, if you receive multiple instances of "Unknown compiler version - please run the configure tests and report the results", this is because your version of Visual Studio is newer than Boost. Download the latest release of Boost and replace the existing Boost folder in ArxWindows\libs with it.

Alternative ways of getting the source code

If you want to use a released source tarball or don't want to use git sub-modules, just get the Arx Libertatis source code using any of the methods listed below and replace the arx sub-directory of your ArxWindows checkout. Make sure that the arx directory directly contains CMakeLists.txt. For non-release versions, you may also need to replace the data directory with a ArxLibertatisData in order to avoid additional dependencies.


There are several methods to get the Arx Libertatis source code - choose the one that suits you best:

Downloading a released version

The easiest way to get the AL source code is to download a versioned release. This will get you a reasonably up to date copy of the source code that has been tested to work.

Cloning the repository

If you want the absolute latest version of the Arx Libertatis development code and stay up to date, you can clone the AL source code repository. Beware that this will give you the current master development branch that we are actively working on. While the code in that branch should always work, it hasn't undergone any significant testing. If you just want to play the game, consider using a released version instead.

To clone the repository, type: 

git clone git://github.com/arx/ArxLibertatis.git

This creates a directory called ArxLibertatis and downloads the current source code from github.

Later if you want to update your local copy of the source code, run 

git pull

The git repository does not contain raster images for the icon and logo. These will be generated from scalable versions when building Arx Libertatis, but doing so requires additional dependencies (Inkscape, ImageMagick and OptiPNG). To avoid this, you can instead get the generated images from the ArxLibertatisData repo: 

git clone --depth 1 git://github.com/arx/ArxLibertatisData.git

Downloading a snapshot

Alternatively you can download the current snapshot of the source code repository as a .zip or .tar.gz file and extract that:

This will give you the same code as cloning the repository, but won't let you update it without downloading everything again.

Building without the Arx Windows CMake helper script

If you want to build the ArxLibertatis repo directly but still want to use ArxWindows for dependencies, you will need to tell CMake where to find them: Add CMAKE_PREFIX_PATH to your environment variable with the following value: 

C:\Code\git\ArxWindows\libs\zlib;C:\Code\git\ArxWindows\libs\freetype;C:\Code\git\ArxWindows\libs\openal;C:\Code\git\ArxWindows\libs\boost;C:\Code\git\ArxWindows\libs\glm;C:\Code\git\ArxWindows\libs\opengl;C:\Code\git\ArxWindows\libs\sdl

On Windows 7 or later this can be done here:

Win7 env.png

After that, you'll need to start a new Gitbash prompt so that the new environment variables are available.

Run the following to check if you set the CMake path correctly or not: 

echo %CMAKE_PREFIX_PATH%

It should echo: 

C:\Code\git\ArxWindows\libs\zlib;C:\Code\git\ArxWindows\libs\freetype;C:\Code\git\ArxWindows\libs\openal;C:\Code\git\ArxWindows\libs\boost;C:\Code\git\ArxWindows\libs\glm;C:\Code\git\ArxWindows\libs\opengl;C:\Code\git\ArxWindows\libs\sdl

You may also need to grab a ArxLibertatisData checkout and use the DATA_FILES CMake option to tell the build system where to find it. This is only required for Arx Libertatis git checkouts - leave out this option if you are building from a release source archive or if you want to generate the icons yourself.

Building with MinGW or other non-MSVC compilers

Arx can be built using the MinGW compiler toolchain instead of MSVC with the following limitations:

  • Missing crash handler.
  • Incomplete Unicode filesystem support: MinGW does not support MSVC's std::fstream extension to open files using Unicode paths.
Retrieved from "https://wiki.arx-libertatis.org/index.php?title=Downloading_and_Compiling_under_Windows&oldid=6591"