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

Fixing links, mostly

develop
Josh Cooper 2022-12-23 00:43:10 -04:00
parent c0d582c406
commit a9467f76ef
3 changed files with 37 additions and 114 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -17,7 +17,7 @@ Other pages that may be relevant include:
.. contents:: Contents .. contents:: Contents
:local: :local:
.. _architecture .. _architectural-diagrams:
Architecture diagrams Architecture diagrams
--------------------- ---------------------

120
docs/dev/building/Compile.rst
Unescape Escape View File

@ -9,7 +9,7 @@ Compilation
DFHack builds are available for all supported platforms; see `installing` for DFHack builds are available for all supported platforms; see `installing` for
installation instructions. If you are a DFHack end-user, modder, or plan on installation instructions. If you are a DFHack end-user, modder, or plan on
writing scripts [lua] (not plugins), it is generally recommended (and easier) to use writing scripts [lua] (not plugins), it is generally recommended (and easier) to use
these `builds<build-releases>` instead of compiling DFHack from source. these `builds <https://github.com/DFHack/dfhack/releases>`_ instead of compiling DFHack from source.
However, if you are looking to develop plugins, work on the DFHack core, make 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 complex changes to DF-structures, or anything else that requires compiling
@ -17,8 +17,6 @@ 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 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. pay close attention if this is your first time compiling DFHack.
.. _build-releases:https://github.com/DFHack/dfhack/releases
.. contents:: Contents .. contents:: Contents
:local: :local:
:depth: 2 :depth: 2
@ -109,7 +107,7 @@ 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 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. in the platform-specific sections below first, then come back here.
Be sure to check out common `compile options <compile-options>`. Be sure to check out common `build options <build-options>`.
Generator Generator
--------- ---------
@ -176,35 +174,38 @@ See our page on `build options<build-options>`
Instructions Instructions
============ ============
.. contents::
:local:
:depth: 1
.. _compile-linux: .. _compile-linux:
Linux Linux
----- -----
On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD. On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD.
Dependencies Build
~~~~~~~~~~~~ ~~~~~
You also need zlib, libsdl (1.2, not sdl2, like DF), perl, and the XML::LibXML Building is fairly straightforward. Enter the ``build`` folder (or create an
and XML::LibXSLT perl packages (for the code generation parts). You should be empty folder in the DFHack directory to use instead) and start the build like this::
able to find them in your distribution's repositories.
To build `stonesense`, you'll also need OpenGL headers.
Here are some package install commands for various distributions:
* On Arch linux:
* For the required Perl modules: ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``)
* On Ubuntu:: cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=<path to DF>
ninja install # or ninja -jX install to specify the number of cores (X) to use
apt-get install gcc cmake ninja-build git zlib1g-dev libsdl1.2-dev libxml-libxml-perl libxml-libxslt-perl <path to DF> should be a path to a copy of Dwarf Fortress, of the appropriate
version for the DFHack you are building. This will build the library along
with the normal set of plugins and install them into your DF folder.
* Other Debian-based distributions should have similar requirements. Alternatively, you can use ccmake instead of cmake::
* On Fedora:: cd build
ccmake .. -G Ninja
ninja install
yum install gcc-c++ cmake ninja-build git zlib-devel SDL-devel perl-core perl-XML-LibXML perl-XML-LibXSLT ruby This will show a curses-based interface that lets you set all of the
extra options. You can also use a cmake-friendly IDE like KDevelop 4
or the cmake-gui program.
Windows cross compiling from Linux Windows cross compiling from Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -291,79 +292,6 @@ host when you want to reattach::
If you edit code and need to rebuild, run ``dfhack-make`` and then ``ninja install``. If you edit code and need to rebuild, run ``dfhack-make`` and then ``ninja install``.
That will handle all the wineserver management for you. That will handle all the wineserver management for you.
Multilib dependencies
~~~~~~~~~~~~~~~~~~~~~
If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the
multilib development tools and libraries:
* ``gcc-multilib`` and ``g++-multilib``
* If you have installed a non-default version of GCC - for example, GCC 4.8 on a
distribution that defaults to 5.x - you may need to add the version number to
the multilib packages.
* For example, ``gcc-4.8-multilib`` and ``g++-4.8-multilib`` if installing for GCC 4.8
on a system that uses a later GCC version.
* This is definitely required on Ubuntu/Debian, check if using a different distribution.
* ``zlib1g-dev:i386`` (or a similar i386 zlib-dev package)
Note that installing a 32-bit GCC on 64-bit systems (e.g. ``gcc:i386`` on
Debian) will typically *not* work, as it depends on several other 32-bit
libraries that conflict with system libraries. Alternatively, you might be able
to use ``lxc`` to
:forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`.
Build
~~~~~
Building is fairly straightforward. Enter the ``build`` folder (or create an
empty folder in the DFHack directory to use instead) and start the build like this::
cd build
cmake .. -G Ninja -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=<path to DF>
ninja install # or ninja -jX install to specify the number of cores (X) to use
<path to DF> should be a path to a copy of Dwarf Fortress, of the appropriate
version for the DFHack you are building. This will build the library along
with the normal set of plugins and install them into your DF folder.
Alternatively, you can use ccmake instead of cmake::
cd build
ccmake .. -G Ninja
ninja install
This will show a curses-based interface that lets you set all of the
extra options. You can also use a cmake-friendly IDE like KDevelop 4
or the cmake-gui program.
.. _linux-incompatible-libstdcxx:
Incompatible libstdc++
~~~~~~~~~~~~~~~~~~~~~~
When compiling DFHack yourself, it builds against your system libstdc++. When
Dwarf Fortress runs, it uses a libstdc++ shipped in the ``libs`` folder, which
comes from GCC 4.8 and is incompatible with code compiled with newer GCC
versions. As of DFHack 0.42.05-alpha1, the ``dfhack`` launcher script attempts
to fix this by automatically removing the DF-provided libstdc++ on startup.
In rare cases, this may fail and cause errors such as:
.. code-block:: text
./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version
`GLIBCXX_3.4.18' not found (required by ./hack/libdfhack.so)
The easiest way to fix this is generally removing the libstdc++ shipped with
DF, which causes DF to use your system libstdc++ instead::
cd /path/to/DF/
rm libs/libstdc++.so.6
Note that distributing binaries compiled with newer GCC versions may result in
the opposite compatibility issue: users with *older* GCC versions may encounter
similar errors. This is why DFHack distributes both GCC 4.8 and GCC 7 builds. If
you are planning on distributing binaries to other users, we recommend using an
older GCC (but still at least 4.8) version if possible.
.. _compile-windows: .. _compile-windows:
Windows Windows
@ -507,8 +435,6 @@ Building
Notes for GCC 8+ or OS X 10.10+ users Notes for GCC 8+ or OS X 10.10+ users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If none of these situations apply to you, skip to `osx-setup`.
If you have issues building on OS X 10.10 (Yosemite) or above, try defining If you have issues building on OS X 10.10 (Yosemite) or above, try defining
the following environment variable:: the following environment variable::

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

@ -26,16 +26,16 @@ System packages:
* SDL (libsdl 1.2, not sdl2). * SDL (libsdl 1.2, not sdl2).
* cmake * cmake
* git (required for `contributions<pr-link>`) * git (required for `contributions <https://github.com/DFHack/dfhack/pulls>`_)
* ccache (**optional**, but recommended to improve build times) * ccache (**optional**, but recommended to improve build times)
* OpenGL headers (**optional**: to build `stonesense`) * OpenGL headers (**optional**: to build `stonesense`)
* zlib (compression library used for `xlsxioreader` -> `quickfort`) * zlib (compression library used for `xlsxreader-api` -> `quickfort`)
* build system (e.g. gcc & ninja, or Visual Studio) * build system (e.g. gcc & ninja, or Visual Studio)
.. ..
maybe the below should be talked about next to the bullets 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. **SDL** is used as an injection point which you can see more about in DFHack's `architectural <architectural-diagrams>` documentation & diagrams.
Perl packages: Perl packages:
@ -46,12 +46,11 @@ 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 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. used to generate C++ source code to define these structures for use in plugins and scripts.
.. _pr-link: https://github.com/DFHack/dfhack/pulls
Installing Installing
---------- ----------
.. contents:: Install Instructions .. contents::
:local: :local:
:depth: 2 :depth: 2
@ -168,9 +167,9 @@ What you'll need is as follows:
* Perl (required) * Perl (required)
* XML:LibXML (required) * XML:LibXML (required)
* XML:LibXLST (required) * XML:LibXLST (required)
* `Python <python-install>` (required for documentation, optional otherwise) * `Python`_ (required for documentation, optional otherwise)
* `Sphinx <sphinx-install>` * `Sphinx`_
Releases of Dwarf Fortress since roughly 2016 have been compiled for Windows using 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 Microsoft's Visual Studio 2015 C++ compiler. In order to guarantee ABI and STL compatibility
@ -191,7 +190,7 @@ Visual Studio to edit code.
With Choco With Choco
~~~~~~~~~~ ~~~~~~~~~~
Many of the dependencies are simple enough to download and install via the Many of the dependencies are simple enough to download and install via the
`chocolatey<chocolatey-link>` package manager on the command line. `chocolatey`_ package manager on the command line.
Here are some package install commands:: Here are some package install commands::
@ -202,7 +201,7 @@ Here are some package install commands::
choco install sphinx choco install sphinx
choco install visualstudio2022community choco install visualstudio2022community
.. _chocolatey-link: https://chocolatey.org/install .. _chocolatey: https://chocolatey.org/install
Visual Studio Visual Studio
~~~~~~~~~~~~~ ~~~~~~~~~~~~~
@ -230,7 +229,7 @@ If you prefer to install manually rather than using Chocolatey, details and
requirements are as below. If you do install manually, please ensure you requirements are as below. If you do install manually, please ensure you
have all **executables searchable in your PATH variable**. have all **executables searchable in your PATH variable**.
.. contents:: Windows .. contents::
:local: :local:
:depth: 1 :depth: 1
@ -267,15 +266,15 @@ install XML::LibXML and XML::LibXSLT for it using CPAN.
Python Python
^^^^^^ ^^^^^^
See `python-install`. See the `Python`_ website.
.. _python-install: https://www.python.org/downloads/ .. _Python: https://www.python.org/downloads/
Sphinx Sphinx
^^^^^^ ^^^^^^
See `sphinx-install` at https://www.sphinx-doc.org/ See the `Sphinx`_ website.
.. _sphinx-install: https://www.sphinx-doc.org/en/master/usage/installation.html .. _Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html
.. _install-visual-studio: .. _install-visual-studio:
@ -340,8 +339,6 @@ DFHack can officially be built on macOS only with GCC 4.8 or 7. Anything newer t
will require you to perform extra steps to get DFHack to run (see `osx-new-gcc-notes`), will require you to perform extra steps to get DFHack to run (see `osx-new-gcc-notes`),
and your build will likely not be redistributable. and your build will likely not be redistributable.
.. _osx-setup:
#. Download and unpack a copy of the latest DF #. Download and unpack a copy of the latest DF
#. Install Xcode from the Mac App Store #. Install Xcode from the Mac App Store