Building on Windows

FSO uses CMake for setting up the Visual Studio solution files. Before you can build the engine you need to download it from here: https://cmake.org/download/ At the time of writing, the newest version is 3.16 RC3 but any version after and including 3.4 is supported at the moment.

Configuring the solution

Once you have installed CMake you need to start the CMake GUI. The command line works as well but this guide will describe the procedure for the GUI.

Fill in the location of the source directory in the first field. The second field specifies where the build files will be written to. Using the source directory as a build directory can lead to issues and FSO actively enforces a different build directory so you need to use another directory for that. Create a directory called build in the source code clone and point CMake to that directory. Click on Configure to start the procedure. A dialog box will pop up that want to know what generator to use. You must use the generator for your installed Visual Studio version here. CMake supports multiple platforms for each Visual Studio version. You can choose either 32-bit (no suffix) or 64-bit (has the Win64 suffix). ARM is not supported by FSO.

This is how the dialog should look on CMake 3.16, if you're using Visual Studio 2017 on a 64-bit system:

Click Finish and wait until CMake is finished. If you get an error that looks like this

CMake Error at CMakeLists.txt:50 (message):
  External submodules could not be found.  Please make sure you have updated
  your submodules.

then you forgot to download the git submodules. You can do that by running the command git submodule update --init --recursive or using the equivalent action in your Git GUI.

CMake may show a warning about defaulting to the Release configuration. Ignore that since it's not relevant for Visual Studio.

Once finished, the CMake window should look like this:

Before generating the solution you can adjust some CMake variables to customize the generated solutions:

• CMAKE_INSTALL_PREFIX: This variable controls where the installed binaries will be copied when the solution is installed. Set this to your FreeSpace 2 root directory.
• FSO_FREESPACE_PATH: If you plan on changing the engine code you should also set this variable to your FreeSpace root. It will allow you to run FSO directly from inside Visual Studio without copying the executables manually.

Make sure that CMAKE_INSTALL_PREFIX and FSO_FREESPACE_PATH use forward slashes (/ rather than \), or the build will fail. Sometimes when using Windows' directory picker it will default to backward slashes

They're the variables highlighted in the screenshot below:

Once you are finished with customizing the variables you can hit the Generate button for finally generating the solution files.

If everything works CMake will say Generating done at the end of the output window. You are now done with CMake and can close the window.

Compiling with Visual Studio

Start Visual Studio and use the Open Project / Solution action for loading the generated solution. Navigate to the build directory you specified in the CMake GUI and select the FS2_Open solution. After a short while the Visual Studio window should look like this:

What you need to do now depends on what you indent to do with the generated solutions.

I only want to compile a build

If you followed the recommendation from above and set the CMAKE_INSTALL_PREFIX variable to your FreeSpace path then all you need to do is "install" the executables. First, select the configuration you want to build from the Configurations box:

You will see three configurations there:

• Debug: This is only used for actually running the engine with a code debugger attached. Unless you want to find bugs in the engine you won't need this.
• FastDebug: This is a configuration that enables the debug checks for mod data but also optimizes the code which yields similar performance to release builds. If you are a modder then you probably want to build this solution.
• Release: This configuration uses all options available to optimize the engine code and removes unnecessary mod data checks. Use this if you want to play the game with the compiled executable.

After you selected the configuration, right click on the INSTALL target in the "CMakePredefinedTarget" folder and select Build:

This will start compiling the engine source code. Depending on how fast your CPU is this might take a while. Once it's done it will display something like this:

14>-- Install configuration: "Debug"
14>-- Installing: <FS2Path>/./avcodec-57.dll
14>-- Installing: <FS2Path>/./avformat-57.dll
14>-- Installing: <FS2Path>/./avutil-55.dll
14>-- Installing: <FS2Path>/./swscale-4.dll
14>-- Installing: <FS2Path>/./swresample-2.dll
14>-- Installing: <FS2Path>/./SDL2.dll
14>-- Installing: <FS2Path>/./README-SDL.txt
14>-- Installing: <FS2Path>/./fs2_open_3_7_5_x64_AVX-DEBUG.exe
14>-- Installing: <FS2Path>/./fred2_open_3_7_5_x64_AVX-DEBUG.exe
========== Build: 14 succeeded, 0 failed, 0 up-to-date, 0 skipped ==========

That's it! You now have your own builds of FreeSpace Open.

I want to change the engine source code

TODO