possibly the last expected changes

docs/dev/Memory-research.rst

@@ -50,7 +50,7 @@ Plugins
 
 There are a few development plugins useful for low-level memory research. They
 are not built by default, but can be built by setting the ``BUILD_DEVEL``
-`CMake option <compile-build-options>`. These include:
+`CMake option <build-options>`. These include:
 
 - ``check-structures-sanity``, which performs sanity checks on the given DF
   object. Note that this will crash in several cases, some intentional, so using
@@ -85,7 +85,7 @@ You should not count on DF being stable when using this.
 
 DFHack's implementation of sizecheck is currently only tested on Linux, although
 it probably also works on macOS. It can be built with the ``BUILD_SIZECHECK``
-`CMake option <compile-build-options>`, which produces a ``libsizecheck``
+`CMake option <build-options>`, which produces a ``libsizecheck``
 library installed in the ``hack`` folder. On Linux, passing ``--sc`` as the
 first argument to the ``dfhack`` launcher script will load this library on
 startup. On other platforms, or when passing a different argument to the

docs/dev/building/Compile.rst

@@ -109,68 +109,6 @@ in the platform-specific sections below first, then come back here.
 
 Be sure to check out common `build options <build-options>`.
 
-Generator
----------
-
-The ``Ninja`` CMake build generator is the preferred build method on Linux and
-macOS, instead of ``Unix Makefiles``, which is the default. You can select Ninja
-by passing ``-G Ninja`` to CMake. Incremental builds using Unix Makefiles can be
-much slower than Ninja builds. Note that you will probably need to install
-Ninja; see the platform-specific sections for details.
-
-::
-
-    cmake .. -G Ninja
-
-.. warning::
-
-  Most other CMake settings can be changed by running ``cmake`` again, but the
-  generator cannot be changed after ``cmake`` has been run without creating a
-  new build folder. Do not forget to specify this option.
-
-  CMake versions 3.6 and older, and possibly as recent as 3.9, are known to
-  produce project files with dependency cycles that fail to build
-  (see :issue:`1369`). Obtaining a recent version of CMake is recommended, either from
-  `cmake.org <https://cmake.org/download/>`_ or through a package manager. See
-  the sections below for more platform-specific directions for installing CMake.
-
-Build type
-----------
-
-``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable::
-
-    cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
-
-Valid and useful build types include 'Release' and 'RelWithDebInfo'. The default
-build type is 'Release'.
-
-Target architecture (32-bit vs. 64-bit)
----------------------------------------
-
-Set DFHACK_BUILD_ARCH to either ``32`` or ``64`` to build a 32-bit or 64-bit
-version of DFHack (respectively). The default is currently ``64``, so you will
-need to specify this explicitly for 32-bit builds. Specifying it is a good idea
-in any case.
-
-::
-
-    cmake .. -DDFHACK_BUILD_ARCH=32
-
-*or*
-::
-
-    cmake .. -DDFHACK_BUILD_ARCH=64
-
-Note that the scripts in the "build" folder on Windows will set the architecture
-automatically.
-
-.. _compile-build-options:
-
-Other settings
---------------
-See our page on `build options<build-options>`
-
-
 Instructions
 ============
 

docs/dev/building/Options.rst

@@ -4,6 +4,10 @@
 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
@@ -12,10 +16,18 @@ 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
+    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
@@ -29,51 +41,112 @@ visual studio, and match that to your system's generator list viewed with ``cmak
 
 example::
 
-    cmake . -G "Visual Studio 17 2022"
+    cmake .. -G "Visual Studio 17 2022"
 
 Ninja
 =====
 The generally preferred build system where available.
 
-Core
+example::
-----
+
-todo:
+    cmake .. -G Ninja
+
+Install Location
+----------------
+This of course uses the default cmake variable.
+
+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
+----------
+Release/Debug, 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=RelWithDebugInfo
+
+Options:
+
+* Release
+* RelWithDebugInfo
+
+Target architecture (32/64-bit)
+---------------------------------------
+If 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
 -------
-todo:
+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.
 
-Enabling the ``BUILD_DOCS`` CMake option will cause the documentation to be built
+Variable: ``BUILD_DOCS``
-whenever it changes as part of the normal DFHack build process. There are several
-ways to do this:
-
-* When initially running CMake, add ``-DBUILD_DOCS:bool=ON`` to your ``cmake``
-  command. For example::
-
-    cmake .. -DCMAKE_BUILD_TYPE:string=Release -DBUILD_DOCS:bool=ON -DCMAKE_INSTALL_PREFIX=<path to DF>
 
-* If you have already run CMake, you can simply run it again from your build
+Usage::
-  folder to update your configuration::
 
     cmake .. -DBUILD_DOCS:bool=ON
+    cmake .. -DBUILD_DOCS=1
 
-* You can edit the ``BUILD_DOCS`` setting in CMakeCache.txt directly
-
-* You can use the CMake GUI or ``ccmake`` to change the ``BUILD_DOCS`` setting
-
-* On Windows, if you prefer to use the batch scripts, you can run
-  ``generate-msvc-gui.bat`` and set ``BUILD_DOCS`` through the GUI. If you are
-  running another file, such as ``generate-msvc-all.bat``, you will need to edit
-  the batch script to add the flag. You can also run ``cmake`` on the command line,
-  similar to other platforms.
 
-By default, both HTML and text docs are built by CMake. The generated
+The generated documentation is stored in ``docs/html`` and ``docs/text`` (respectively)
-documentation is stored in ``docs/html`` and ``docs/text`` (respectively) in the
+in the root DFHack folder, and they will both be installed to ``hack/docs`` when you
-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
-install DFHack. The html and txt files will intermingle, but will not interfere
+one another.
-with one another.