Build Options¶
There are a variety of other settings which you can find in CMakeCache.txt in
your build folder or by running ccmake
(or another CMake GUI). Most
DFHack-specific settings begin with BUILD_
and control which parts of DFHack
are built.
Typical usage may look like:
# Plugin development with updated documentation
cmake ./ -G Ninja -B builds/debug-info/ -DCMAKE_INSTALL_PREFIX=<path to DF> -DCMAKE_BUILD_TYPE:string=RelWithDebInfo -DBUILD_DOCS:bool=ON -DBUILD_PLUGINS=1
# Core DFHack only
cmake ../ -G Ninja -DCMAKE_INSTALL_PREFIX=<path to DF> -DCMAKE_BUILD_TYPE:string=RelWithDebInfo -DBUILD_TESTS -DBUILD_DOCS:0 -DBUILD_PLUGINS=0
Generator¶
For the uninitiated, the generator is what allows cmake to, of course, generate visual studio solution & project files, a makefile, or anything else. Your selection of generator comes down to preference and availability.
Visual Studio¶
To generate visual studio project files, you’ll need to select a particular version of
visual studio, and match that to your system’s generator list viewed with cmake --help
example:
cmake .. -G "Visual Studio 17 2022"
Ninja¶
The generally preferred build system where available.
example:
cmake .. -G Ninja
Install Location¶
This is the location where DFHack will be installed.
Variable: CMAKE_INSTALL_PREFIX
Usage:
cmake .. -DCMAKE_INSTALL_PREFIX=<path to df>
The path to df will of course depend on your system. If the directory exists it is
recommended to use ~/.dwarffortress
to avoid permission troubles.
Build type¶
This is the type of build you want. This controls what information about symbols and line numbers the debugger will have available to it.
Variable: CMAKE_BUILD_TYPE
Usage:
cmake .. -DCMAKE_BUILD_TYPE:string=RelWithDebInfo
Options:
Release
RelWithDebInfo
Target architecture (32/64-bit)¶
You can set this if you need 32-bit binaries or are looking to be explicit about building 64-bit.
Variable: DFHACK_BUILD_ARCH
Usage:
cmake .. -DDFHACK_BUILD_ARCH=32
Options:
‘32’
‘64’ (default option)
Library¶
This will only be useful if you’re looking to avoid building the library core, as it builds by default.
Variable: BUILD_LIBRARY
Usage:
cmake .. -DBUILD_LIBRARY:bool=OFF
cmake .. -DBUILD_LIBRARY=0
Testing¶
Regression testing will be arriving in the future, but for now there are only tests written in lua.
Variables:
BUILD_TESTING
(will build unit tests, in the future)BUILD_TESTS
(installs lua tests)
Usage:
cmake .. -DBUILD_TESTS:bool=ON
cmake .. -DBUILD_TESTS=1
Plugins¶
If you’re doing plugin development.
Variable: BUILD_PLUGINS
Usage:
cmake .. -DBUILD_PLUGINS:bool=ON
cmake .. -DBUILD_PLUGINS=1
Documentation¶
If you need to build documentation. Documentation can be built as HTML, and PDF, but there are also plain text files generated for in-game.
Variable: BUILD_DOCS
Usage:
cmake .. -DBUILD_DOCS:bool=ON
cmake .. -DBUILD_DOCS=1
The generated documentation is stored in docs/html
and docs/text
(respectively)
in the root DFHack folder, and they will both be installed to hack/docs
when you
install DFHack. The html and txt files will intermingle, but will not interfere with
one another.