CMake Build Guide
Long term users will notice that the win32 folder, the .sln file, and .vcproj files are all gone. In their place: CMakeLists.txt files in every folder that has something to be built. Don't worry, Visual Studio 2017 and Visual Studio 2019 have CMake built-in.
First, open Visual Studio. You will see the welcome screen:
If you had topaz in Open recent, the configuration will begin automatically.
If you selected Continue without code; follow these steps and open the CMakeLists.txt file in the root of the repo.
File > Open > Folder in the repo root will also work.
CMake will think for a moment and then start the configuration step of your build.
...
1> Working directory: C:\topaz\topaz\out\build\x86-Debug
1> [CMake] -- The CXX compiler identification is MSVC 19.27.29112.0
1> [CMake] -- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx86/x86/cl.exe
1> [CMake] -- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx86/x86/cl.exe - works
1> [CMake] -- Detecting CXX compiler ABI info
...
After a little time, the output log should present you with:
...
1> [CMake] -- Configuring done
1> [CMake] -- Generating done
1> [CMake] -- Build files have been written to: C:/topaz/topaz/out/build/x86-Debug
1> Extracted CMake variables.
1> Extracted source files and headers.
1> Extracted code model.
1> Extracted includes paths.
1> CMake generation finished.
Configuration is now done!
You can select your build type here:
If you want to build everything, you can go here:
If you want to build and debug a specific executable, you can go here:
Debug paths, executable output paths etc. are all handled automatically, unlike the old .sln files which didn't work for debugging 'out-of-the-box'.
Make sure you have CMake available to use in your PATH through some means.
mkdir build
cd build
cmake .. && cmake --build .
The default is x64, you can force 32-bit with: cmake .. -A Win32 && cmake --build .
Make sure you have CMake available to use in your PATH through some means.
If for some reason you want a .sln file, you can generate one with:
cmake -G "Visual Studio 16 2019" .. or cmake -G "Visual Studio 15 2017" ..
The same CMake steps as before (make sure you have CMake installed with sudo apt install cmake or similar):
mkdir build
cd build
cmake ..
make -j $(nproc)
Previously, the build could fail on paths that contain spaces. While it works now, it isn't recommended.
It appears as though the build will fail if you try to launch it from a raw drive letter (eg. D:/). Instead, use a subfolder: D:/topaz.
On Windows, if you have versions of our external libraries installed on your machine, CMake might try to use them. You'll be able to catch this during configuration when CMake reports:
-- MYSQL_LIBRARY: C:\mysql-ver-1.0\lib
-- MYSQL_INCLUDE_DIR: C:\mysql-ver-1.0\include
This should be reporting the bundled versions we keep, something like this:
-- MYSQL_LIBRARY: C:\dev\topaz\ext\lib\mysql
-- MYSQL_INCLUDE_DIR: C:\dev\topaz\ext\include\mysql
If this happens, you can override these paths when you configure CMake:
cmake .. -DMYSQL_INCLUDE_DIR=C:\dev\topaz\ext\lib\mysql -DMYSQL_LIBRARY=C:\dev\topaz\ext\lib\libmariadb.lib
Historically, we've had 3 build systems: VS Solution, Linux makefile and CMake. On all platforms, when you wanted to add a file you had to add them to the VS .sln file, often by hand. This made cross-platform development annoying, and merge conflicts on the XML-based .sln files were a pain. CMake files are simple and allow us to more easily split the project into logical chunks to build and apply different build settings to.
This first version is recreating the original build as closely as possible. Now that it's complete, it will allow us to:
- Make sure build flags and warning/error settings are the same on platforms.
- Add/remove/upgrade external dependencies more easily.
- Apply tools like
UBSanandValgrindto the build more easily. - Easily apply performance benchmarking tools like
OrbitorTracy. - Add/split-out new executables more easily, reusing existing code.
Add the .h and the .cpp file to the SOURCES list in the CMakeLists.txt file in the folder where the new files live.
If you use Visual Studio or CLion, they will automatically pick up this change and regenerate your CMake cache. On Linux you will need to update your cache by running cmake .. in your build folder before you run make.