Source code compiling/CMake
|This article or section is badly written and in need of a rewrite. You can help the SRB2 Wiki by Manual of Style.this article to meet with the standards described by the|
This is a guide for compiling the source code using CMake. CMake is a meta build system for C and C++ projects that generates project files for the target system, allowing a single set of well engineered build scripts to replace individual project files and Makefiles for each supported platform of a project. This streamlines the compiling process across different platforms. SRB2's CMake support also includes an automatic packaging system. This guide will assume that you have already cloned the public repository from GitHub or GitLab.
First of all, you will need the following installed on your system:
- CMake. On Linux, you should install it through your package manager. On Mac OS X, it is recommended to install from the
.dmgon their site, but you may also install from Homebrew if you are comfortable with that.
- Your compiler and development environment of choice. For Windows, you have a lot of options. If this is your first time compiling the source code, Visual Studio Community Edition is recommended.
- SDL2 and SDL2_mixer development libraries for your target. On Linux, you can get them from the package manager. On Windows, you can get SDL2 from here and SDL2_mixer from here. Note that there are separate versions for MinGW and Microsoft Visual C++ (MSVC) – download the version that matches your compiler. On Windows, use the 32-bit libraries, even on 64-bit systems. The 32-bit libraries can be found in the "i686-w64-mingw32" subfolder for MinGW and in the "x86" subfolder for MSVC, respectively. Note that there is a bug in SDL2 version 2.0.3 that will cause compilation to fail on Windows 7 and earlier. To fix this, download this patch and put it into the include folder ("i686-w64-mingw32/include/SDL2" for MinGW, "x86/include" for MSVC), overwriting
- The assets to the current version of SRB2. These are
music.dta. Put these in the the assets directory in your sources, and don't ever commit them to your GitHub fork! They're massive! CMake will generate the MD5 checksums of these files and put them in a generated
config.hfile, along with the Git revision description in the version string.
Optionally, you can install these components as well:
- YASM or NASM assembler (for optimized tmap routines under x86)
- libpng and zlib (for PNG screenshots under OpenGL)
Configuring and generating with CMake
Once you have everything in order, open the CMake GUI and select the cloned source directory in "Where is the source code:". Note that this box shouldn't be set to the
src folder but the directory that contains the
src folder. The second box is crucial – you need to set your build directory to something other than the source directory. This is where your project files will be generated and binaries will be compiled. You can clear this just by deleting your build directory and reconfiguring.
Click Configure and choose the appropriate generator. There are lots of generators available depending on your platform. Currently, only the MSVC, MSYS, Xcode and Code::Blocks Makefiles (for Windows, Windows, Mac and Linux respectively) have been tested to work, but other generators should work as well. You'll likely be prompted with an error message saying a library or framework wasn't found when on Windows or Mac – just look for the appropriate variables and point them to the right location. You might want to look in the SRB2 group (with variables Grouped) to set various configuration options, including enabling or disabling features you don't have libraries for. The bare minimum is SDL2, however.
SDL2_LIBRARY– Point this to
SDL2.libon Windows, for example.
SDL2_INCLUDE_DIR– Point this to the include directory from your SDL2 installation.
- Other libraries are set up similarly like the SDL2 example above.
CMAKE_INSTALL_PREFIX– Set this to the folder where you want your "distribution" of SRB2 to exist. You only have to set this if you are making a Release type build (i.e., no debugging symbols). Under Debug, the location of your source directory's assets/directory will be compiled directly into the game's search path. For this reason it is not recommended to distribute Debug builds from CMake.
Once you've configured successfully, hit Generate to create the project files. You can then open up the build directory and find them.
Do not have any spaces in the path to your source and build directories when using MinGW and MSYS on Windows. Otherwise compilation will fail.
Warning: Do not change anything in the generated project files. Your changes will simply be overwritten by CMake when it runs prior to building any target.
Note: MSVC builds are not confirmed to work in multiplayer. There may be major connectivity issues. Builds from VS 2015 Professional Preview have been confirm to work, but other versions of Visual Studio are untested.
From here, it depends on which generator you chose. Under MSVC, you're going to open
SRB2.sln and simply right-click the SRB2 project and click Build. You can change between Debug and Release in one of the toolbars at the top. If you want to debug from MSVC, you should set SRB2 as your startup project by right clicking it.
With Makefiles, you should navigate to the build directory in your terminal and type
make. (On Linux and Mac, you can enable parallel compilation by passing the
-j4 flag, but this will prevent you from viewing compilation progress correctly as it compiles sources). You'll want to set
CMAKE_BUILD_TYPE to Debug or Release depending on what you need. It should default to Debug for non-IDE targets in general.
With Xcode, you will open the generated
SRB2.xcodeproj, click the Scheme dropdown at the type and select "srb2", and hit Command+B to compile. This compiles very fast compared to other systems.
Install and packaging
This is a new feature that comes with CMake; it can generate distributable packages of the game easily. This is especially nice for OS X, which will pack the asset files into an Application Bundle that can be installed simply by dragging the icon into your Applications.
To install, make sure you change the
CMAKE_INSTALL_PREFIX variable in
CMakeCache.txt or the CMake GUI to somewhere reasonable, and build the
INSTALL target. This will copy the assets and binaries (including selected DLLs on Windows) to the chosen install directory.
To package, simply build the
PACKAGE target. On Windows generators, this will make a
.zip with the binary and game assets for the current build type (You should definitely pick Release for this!), named
SRB2-(Version).zip or something similar. For Linux, a
.tar.gz archive is generated similarly. On Mac OS X, a
.dmg image with the application bundle and a symlink to Applications is made, just like you might expect from a Mac application installer image, so you can easily drag the
Sonic Robo Blast 2.app to your Applications for installation.
DirectDraw builds currently cannot be compiled with CMake. If you need DirectDraw support, follow the Makefiles guide for more traditional compilation.