154 lines
3.8 KiB
ReStructuredText
154 lines
3.8 KiB
ReStructuredText
.. _build-options:
|
|
|
|
#############
|
|
Build Options
|
|
#############
|
|
|
|
.. contents:: Typical Options
|
|
:local:
|
|
:depth: 1
|
|
|
|
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
|
|
|
|
.. admonition:: Modifying Build Options
|
|
|
|
You can typically run new cmake commands from your build directory to turn on/off options.
|
|
Of course the generator selection is not something you can change, but the rest are.
|
|
|
|
Additionally, you can edit the build settings in CMakeCache.txt. You also have cmake's
|
|
configuration utility ``ccmake``.
|
|
|
|
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
|
|
|
|
.. _building-documentation:
|
|
|
|
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.
|