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.
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.
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.
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.
For several major revisions, Visual Studio has included its own cmake support. This is also supported by FSO.
To use it, simply check out the code, then open the folder in VS. VS should detect the presence of cmake project files automatically and start generating a solution that it will then use, using default settings.
To configure the solution according to your needs, navigate here:
This will open the cmake settings dialog, which will allow you to set all the options that the standalone cmake supports. It is recommended that you create configurations for at least debug and release builds, something that unfortunately you have to do manually; luckily, this is simple.
In the settings dialog, click the "+" button to create a new configuration.
In the dialog that follows, select "x64 Release".
Set the Configuration Type to Release:
Then, scroll down to the "CMake variables and cache" section and click "Save and generate CMake cache to load variables" to populate the settings section.
-
FSO_BUILD_WXFRED2: Build the wxfred2 project, requires wxWidgets -
FSO_FREESPACE_PATH: Sets the path of your FreeSpace install, can be used to automatically run the generated executables with the correct working directory, this is an optional variable. By default this will use the value of theFS2PATHenvironment variable. -
FSO_BUILD_TOOLS: Build some tools related to FSO -
CMAKE_BUILD_TYPE: Sets the binary build type betweenDebugandRelease(default)
-
FSO_BUILD_FRED2: Build FRED2, requires a Visual Studio version that ships with MFC -
FSO_USE_SPEECH: Build a binary with text-to-speech support -
FSO_USE_VOICEREC: Build a binary with voice recognition support
You should only use these variables if you know what you're doing
-
FSO_CMAKE_DEBUG: Print CMake debugging informations -
FSO_BUILD_INCLUDED_LIBS: Build libraries from the included source -
FSO_USE_OPENALSOFT: Use OpenALSoft for OpenAL support -
FSO_USE_LUAJIT: Use luajit as a replacement for lua -
FSO_DEVELOPMENT_MODE: Toggles some development behavior, only use if you really need it. -
FSO_RUN_ARGUMENTS: If you run an executable from within the project, these arguments will also be passed to the executable -
FSO_BUILD_POSTFIX: Sets a postfix to be added to the executable name, may be useful for release candidates.
-
MSVC_USE_RUNTIME_DLL: Use the DLL version of the runtime, experimental and not well tested. -
MSVC_SIMD_INSTRUCTIONS: The instruction set the executables will be optimized for.
CMake can automatically generate installation packages of the project. To do this you will just need to run the package target of the build system and the package will be placed inside your build directory. On Windows you will have to install NSIS to use this.
- If your build fails with an error that says
file not found: code\sound\phrases.cfg, try disablingFSO_VOICE_RECon CMake and generating the project again.
TODO