a small screen commit message about a lot of organization changes

2022-12-21 18:09:37 -04:00 · 2022-12-21 18:09:37 -04:00 · e60030e85e
parent 86ed5ae17a
commit e60030e85e
9 changed files with 175 additions and 123 deletions
--- a/.gitignore
+++ b/.gitignore
@ -7,6 +7,7 @@
 # any build folders
 build*/
 !docs/dev/building/
 nix
 buntu
 build/VC2010
--- a/LICENSE.rst
+++ b/LICENSE.rst
@ -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
--- a/docs/dev/Dev-intro.rst
+++ b/docs/dev/Dev-intro.rst
@ -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
--- a/docs/dev/Documentation.rst
+++ b/docs/dev/Documentation.rst
@ -434,35 +434,7 @@ Sphinx to build the docs:
 Using CMake
 -----------
-Enabling the ``BUILD_DOCS`` CMake option will cause the documentation to be built
+See our page on `build options <building-documentation>`
 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.
 Running Sphinx manually
 -----------------------
--- a/docs/dev/building/Compile.rst
+++ b/docs/dev/building/Compile.rst
@ -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
+See our page on `build options<build-options>`
-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.
 .. _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
 ===========
--- a/docs/dev/building/Dependencies.rst
+++ b/docs/dev/building/Dependencies.rst
@ -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
+* cmake
-* OpenGL headers (optional: to build `stonesense`)
+* 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
+working installers for this product today. The recommended approach is to use a modern community
-is to use Visual Studio 2022 or Visual Studio 2019, installing additional optional
+version of Visual Studio such as 2022 or 2019, installing additional optional Visual Studio
-Visual Studio components which provide the required support for using
+components which provide the required support for using Visual Studio 2015's toolchain.
-Visual Studio 2015's toolchain. All of the required tools are available from Microsoft as part of
+All of the required tools are available from Microsoft as part of Visual Studio's Community
-Visual Studio's Community Edition at no charge.
+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
 =======================
--- a/docs/dev/building/Options.rst
+++ b/docs/dev/building/Options.rst
@ -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.
--- a/docs/dev/building/index.rst
+++ b/docs/dev/building/index.rst
@ -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
--- a/docs/dev/index.rst
+++ b/docs/dev/index.rst
@ -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