.. _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.