MetzNet
/
dfhack
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

a small screen commit message about a lot of organization changes

develop
Josh Cooper 2022-12-21 18:09:37 -04:00
parent 86ed5ae17a
commit e60030e85e
9 changed files with 175 additions and 123 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
Unescape Escape View File

@ -7,6 +7,7 @@
# any build folders
build*/
!docs/dev/building/
nix
buntu
build/VC2010

2
LICENSE.rst
Unescape Escape View File

@ -36,6 +36,7 @@ tinyxml_ Zlib \(c\) 2000-2006, Lee Thomason
UTF-8-decoder_ MIT \(c\) 2008-2010, Bjoern Hoehrmann
xlsxio_ MIT \(c\) 2016-2020, Brecht Sanders
alt-getopt_ MIT \(c\) 2009 Aleksey Cheusov
googletest_ BSD 3-Clause \(c\) 2008, Google Inc.
=============== ============= =================================================
.. _DFHack: https://github.com/DFHack/dfhack
@ -56,6 +57,7 @@ alt-getopt_ MIT \(c\) 2009 Aleksey Cheusov
.. _UTF-8-decoder: http://bjoern.hoehrmann.de/utf-8/decoder/dfa
.. _xlsxio: https://github.com/brechtsanders/xlsxio
.. _alt-getopt: https://github.com/LuaDist/alt-getopt
.. _googletest: https://github.com/google/googletest
.. _CC-BY-SA: http://creativecommons.org/licenses/by/3.0/deed.en_US

6
docs/dev/Dev-intro.rst
Unescape Escape View File

@ -8,6 +8,7 @@ likely the most straightforward choice.
Other pages that may be relevant include:
- `building-dfhack-index`
- `contributing`
- `documentation`
- `license`
@ -16,6 +17,8 @@ Other pages that may be relevant include:
.. contents:: Contents
:local:
.. _architecture
Architecture diagrams
---------------------
@ -28,6 +31,9 @@ together:
:target: https://drive.google.com/file/d/1-2yeNMC7WHgMfZ9iQsDQ0dEbLukd_xyU
:align: center
As seen in the diagram Dwarf Fortress utilizes the SDL library, this provides us with an easy to isolate
injection point for DFHack.
.. image:: https://drive.google.com/uc?export=download&id=1--JoEQbzKpVUOkRKDD9HxvuCqtom780F
:alt: DFHack tool call graph
:target: https://drive.google.com/file/d/1--JoEQbzKpVUOkRKDD9HxvuCqtom780F

30
docs/dev/Documentation.rst
Unescape Escape View File

@ -434,35 +434,7 @@ Sphinx to build the docs:
Using CMake
-----------
Enabling the ``BUILD_DOCS`` CMake option will cause the documentation to be built
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
folder to update your configuration::
cmake .. -DBUILD_DOCS:bool=ON
* 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
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.
See our page on `build options <building-documentation>`
Running Sphinx manually
-----------------------

90
docs/dev/Compile.rst → docs/dev/building/Compile.rst
Unescape Escape View File

@ -9,7 +9,7 @@ Compiling DFHack
DFHack builds are available for all supported platforms; see `installing` for
installation instructions. If you are a DFHack end-user, modder, or plan on
writing scripts (not plugins), it is generally recommended (and easier) to use
these builds instead of compiling DFHack from source.
these `builds<build-releases>` instead of compiling DFHack from source.
However, if you are looking to develop plugins, work on the DFHack core, make
complex changes to DF-structures, or anything else that requires compiling
@ -17,9 +17,11 @@ DFHack from source, this document will walk you through the build process. Note
that some steps may be unconventional compared to other projects, so be sure to
pay close attention if this is your first time compiling DFHack.
.. _build-releases:https://github.com/DFHack/dfhack/releases
.. contents:: Contents
:local:
:depth: 1
:depth: 2
.. _compile-how-to-get-the-code:
@ -86,6 +88,12 @@ assistance.
are also able to help with any submodule-related (or Git-related) issues
you may encounter.
Dependencies
------------
If you haven't already checked, this would be a good point to ensure you have
all the `dependencies <build-dependencies>`.
Contributing to DFHack
----------------------
@ -101,6 +109,8 @@ This section describes build configuration options that apply to all platforms.
If you don't have a working build environment set up yet, follow the instructions
in the platform-specific sections below first, then come back here.
Be sure to check out common `compile options <compile-options>`.
Generator
---------
@ -160,10 +170,8 @@ automatically.
Other settings
--------------
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.
See our page on `build options<build-options>`
.. _compile-linux:
@ -174,29 +182,7 @@ On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PR
Dependencies
------------
DFHack is meant to be installed into an existing DF folder, so get one ready.
We assume that any Linux platform will have ``git`` available (though it may
need to be installed with your package manager.)
To build DFHack, you need GCC 4.8 or newer. GCC 4.8 has the benefit of avoiding
`libstdc++ compatibility issues <linux-incompatible-libstdcxx>`, but can be hard
to obtain on modern distributions, and working around these issues is done
automatically by the ``dfhack`` launcher script. As long as your system-provided
GCC is new enough, it should work. Note that extremely new GCC versions may not
have been used to build DFHack yet, so if you run into issues with these, please
let us know (e.g. by opening a GitHub issue).
Before you can build anything, you'll also need ``cmake``. It is advisable to
also get ``ccmake`` on distributions that split the cmake package into multiple
parts. As mentioned above, ``ninja`` is recommended (many distributions call
this package ``ninja-build``).
You will need pthread; most systems should have this already. Note that older
CMake versions may have trouble detecting pthread, so if you run into
pthread-related errors and pthread is installed, you may need to upgrade CMake,
either by downloading it from `cmake.org <https://cmake.org/download/>`_ or
through your package manager, if possible.
You also need zlib, libsdl (1.2, not sdl2, like DF), perl, and the XML::LibXML
and XML::LibXSLT perl packages (for the code generation parts). You should be
@ -609,50 +595,6 @@ manually uninstall the version you have already and re-install via Chocolatey,
which will ensure the PATH are set up right and will allow Chocolatey to manage
that program for you in future.
Additional dependencies: installing manually
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you prefer to install manually rather than using Chocolatey, details and
requirements are as below. If you do install manually, please ensure you
have all PATHs set up correctly.
Git
^^^
Some examples:
* `Git for Windows <https://git-for-windows.github.io>`_ (command-line and GUI)
* `tortoisegit <https://tortoisegit.org>`_ (GUI and File Explorer integration)
CMake
^^^^^
You can get the win32 installer version from
`the official site <https://cmake.org/download/>`_.
It has the usual installer wizard. Make sure you let it add its binary folder
to your binary search PATH so the tool can be later run from anywhere.
Perl / Strawberry Perl
^^^^^^^^^^^^^^^^^^^^^^
For the code generation stage of the build process, you'll need Perl 5 with
XML::LibXML and XML::LibXSLT. `Strawberry Perl <http://strawberryperl.com>`_ is
recommended as it includes all of the required packages in a single, easy
install.
After install, ensure Perl is in your user's PATH. This can be edited from
``Control Panel -> System -> Advanced System Settings -> Environment Variables``.
The following directories must be in your PATH, in this order:
* ``<path to perl>\c\bin``
* ``<path to perl>\perl\site\bin``
* ``<path to perl>\perl\bin``
* ``<path to perl>\perl\vendor\lib\auto\XML\LibXML`` (may only be required on some systems)
Be sure to close and re-open any existing ``cmd.exe`` windows after updating
your PATH.
If you already have a different version of Perl installed (for example, from Cygwin),
you can run into some trouble. Either remove the other Perl install from PATH, or
install XML::LibXML and XML::LibXSLT for it using CPAN.
Build
-----
There are several different batch files in the ``win32`` and ``win64``
@ -825,7 +767,7 @@ Building the documentation
==========================
The steps above will not build DFHack's documentation by default. If you are
editing documentation, see `documentation` for details on how to build it.
changing documentation, see `documentation` for details on how to build it.
Misc. Notes
===========

72
docs/dev/building/Dependencies.rst
Unescape Escape View File

@ -1,8 +1,18 @@
.. _dependencies:
.. _build-dependencies:
###################
DFHack Dependencies
###################
############
Dependencies
############
The most immediate consideration is of course that DFHack is meant to be installed into an **existing DF folder**.
So it is prudent that one is ready.
.. contents:: Contents
:local:
:depth: 2
Build Dependencies
------------------
..
DFHack is quite large, so I've attempted to
@ -15,11 +25,16 @@ however there are some system dependencies as well. They are as follows:
System packages:
* SDL (libsdl 1.2, not sdl2).
* zlib
* OpenGL headers (optional: to build `stonesense`)
* cmake
* ccache (**optional**, but recommended to improve build times)
* OpenGL headers (**optional**: to build `stonesense`)
* zlib (compression library used for `xlsxioreader`)
* build system
..
maybe the below should be talked about next to the bullets
**SDL** is used as an injection point which you can see more about in DFHack's `architecture` documentation & diagrams.
The **zlib** dependency is a compression library which is part of a chain of dependencies ultimately used by `quickfort` and `xlsxioreader`.
Perl packages:
@ -30,10 +45,6 @@ These perl packages are used in code generation. DFHack has many structures that
files to define and update these structures. Then during the configuration process [running cmake] these xml files are
used to generate C++ source code to define these structures for use in plugins and scripts.
.. contents:: Contents
:local:
:depth: 2
.. _linux-dependency-instructions:
Linux
@ -43,7 +54,7 @@ Here are some package install commands for various distributions:
* On Arch linux::
pacman -Sy gcc cmake ninja git dwarffortress zlib perl-xml-libxml perl-xml-libxslt
pacman -Sy gcc cmake ccmake ninja git dwarffortress zlib perl-xml-libxml perl-xml-libxslt
* The ``dwarffortress`` package provides the necessary SDL packages.
* For the required Perl modules: ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``)
@ -58,6 +69,25 @@ Here are some package install commands for various distributions:
yum install gcc-c++ cmake ninja-build git zlib-devel SDL-devel perl-core perl-XML-LibXML perl-XML-LibXSLT ruby
To build DFHack, you need GCC 4.8 or newer. GCC 4.8 has the benefit of avoiding
`libstdc++ compatibility issues <linux-incompatible-libstdcxx>`, but can be hard
to obtain on modern distributions, and working around these issues is done
automatically by the ``dfhack`` launcher script. As long as your system-provided
GCC is new enough, it should work. Note that extremely new GCC versions may not
have been used to build DFHack yet, so if you run into issues with these, please
let us know (e.g. by opening a GitHub issue).
Before you can build anything, you'll also need ``cmake``. It is advisable to
also get ``ccmake`` on distributions that split the cmake package into multiple
parts. As mentioned above, ``ninja`` is recommended (many distributions call
this package ``ninja-build``).
You will need pthread; most systems should have this already. Note that older
CMake versions may have trouble detecting pthread, so if you run into
pthread-related errors and pthread is installed, you may need to upgrade CMake,
either by downloading it from `cmake.org <https://cmake.org/download/>`_ or
through your package manager, if possible.
Building 32-bit Binaries
========================
If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the
@ -198,27 +228,31 @@ What you'll need is as follows:
* i.e. Microsoft Visual C++ 2015 Build Tools
* Git (optional)
* CMake
* StrawberryPerl (optional, see nested)
* StrawberryPerl, OR CPAN (optional, see nested)
* Perl (required)
* XML:LibXML (required)
* XML:LibXLST (required)
* Python (required for documentation, optional otherwise)
* `Python <python-install>` (required for documentation, optional otherwise)
* `Sphinx <sphinx-install>`
Releases of Dwarf Fortress since roughly 2016 have been compiled for Windows using
Microsoft's Visual Studio 2015 C++ compiler. In order to guarantee ABI and STL compatibility
with Dwarf Fortress, DFHack has to be compiled with the same compiler.
Visual Studio 2015 is no longer supported by Microsoft and it can be difficult to obtain
working installers for this product today. As of 2022, the recommended approach
is to use Visual Studio 2022 or Visual Studio 2019, installing additional optional
Visual Studio components which provide the required support for using
Visual Studio 2015's toolchain. All of the required tools are available from Microsoft as part of
Visual Studio's Community Edition at no charge.
working installers for this product today. The recommended approach is to use a modern community
version of Visual Studio such as 2022 or 2019, installing additional optional Visual Studio
components which provide the required support for using Visual Studio 2015's toolchain.
All of the required tools are available from Microsoft as part of Visual Studio's Community
Edition at no charge.
You can also download just the Visual C++ 2015 `build tools`_ if you aren't going to use
Visual Studio to edit code.
.. _build tools: https://my.visualstudio.com/Downloads?q=visual%20studio%202015&wt.mc_id=o~msft~vscom~older-downloads
Installing Dependencies
=======================

79
docs/dev/building/Options.rst
Unescape Escape View File

@ -0,0 +1,79 @@
.. _build-options:
#############
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.
Core
----
todo:
Plugins
-------
todo:
.. _building-documentation:
Documentation
-------------
Enabling the ``BUILD_DOCS`` CMake option will cause the documentation to be built
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
folder to update your configuration::
cmake .. -DBUILD_DOCS:bool=ON
* 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
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.

14
docs/dev/building/index.rst
Unescape Escape View File

@ -0,0 +1,14 @@
.. _building-dfhack-index:
===============
Building DFHack
===============
Those seeking to compile the source code for DFHack, and or plugins, can refer to the following help pages.
.. toctree::
:maxdepth: 2
/docs/dev/building/Dependencies
/docs/dev/building/Compile
/docs/dev/building/Options

4
docs/dev/index.rst
Unescape Escape View File

@ -1,3 +1,5 @@
========================
DFHack development guide
========================
@ -8,7 +10,7 @@ These are pages relevant to people developing for DFHack.
:maxdepth: 1
/docs/dev/Dev-intro
/docs/dev/Compile
/docs/dev/building/index
/docs/dev/Contributing
/docs/dev/Documentation
/docs/api/index