2015-09-22 08:06:56 -06:00
|
|
|
################
|
|
|
|
Compiling DFHack
|
|
|
|
################
|
|
|
|
|
2020-05-13 20:25:42 -06:00
|
|
|
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.
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2020-05-13 20:25:42 -06:00
|
|
|
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
|
|
|
|
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.
|
2010-07-19 21:27:12 -06:00
|
|
|
|
|
|
|
.. contents::
|
2015-11-05 03:40:09 -07:00
|
|
|
:depth: 2
|
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
.. _compile-how-to-get-the-code:
|
2011-07-30 21:50:37 -06:00
|
|
|
|
2012-02-24 12:25:53 -07:00
|
|
|
How to get the code
|
|
|
|
===================
|
2020-05-13 20:25:42 -06:00
|
|
|
DFHack uses Git for source control; instructions for installing Git can be found
|
|
|
|
in the platform-specific sections below. The code is hosted on
|
|
|
|
`GitHub <https://github.com/DFHack/dfhack>`_, and can be downloaded with::
|
2015-07-24 08:49:17 -06:00
|
|
|
|
|
|
|
git clone --recursive https://github.com/DFHack/dfhack
|
|
|
|
cd dfhack
|
|
|
|
|
2020-05-13 20:25:42 -06:00
|
|
|
If your version of Git does not support the ``--recursive`` flag, you will need
|
|
|
|
to omit it and run ``git submodule update --init`` after entering the dfhack
|
|
|
|
directory.
|
2015-07-24 08:49:17 -06:00
|
|
|
|
2020-05-13 20:25:42 -06:00
|
|
|
This will check out the code on the default branch of the GitHub repo, currently
|
|
|
|
``develop``, which may be unstable. If you want code for the latest stable
|
|
|
|
release, you can check out the ``master`` branch instead::
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2020-05-13 20:25:42 -06:00
|
|
|
git checkout master
|
2015-12-14 20:30:08 -07:00
|
|
|
git submodule update
|
|
|
|
|
2020-05-13 20:25:42 -06:00
|
|
|
In general, a single DFHack clone is suitable for development - most Git
|
|
|
|
operations such as switching branches can be done on an existing clone. If you
|
|
|
|
find yourself cloning DFHack frequently as part of your development process, or
|
|
|
|
getting stuck on anything else Git-related, feel free to reach out to us for
|
|
|
|
assistance.
|
|
|
|
|
|
|
|
.. admonition:: A note on submodules
|
|
|
|
|
|
|
|
DFHack uses submodules extensively to manage its subprojects (including the
|
|
|
|
``scripts`` folder and DF-structures in ``library/xml``). Failing to keep
|
|
|
|
submodules in sync when switching between branches can result in build errors
|
|
|
|
or scripts that don't work. In general, you should always update submodules
|
|
|
|
whenever you switch between branches in the main DFHack repo with
|
|
|
|
``git submodule update``. (If you are working on bleeding-edge DFHack and
|
|
|
|
have checked out the master branch of some submodules, running ``git pull``
|
|
|
|
in those submodules is also an option.)
|
|
|
|
|
|
|
|
Rarely, we add or remove submodules. If there are any changes to the existence
|
|
|
|
of submodules when you switch between branches, you should run
|
|
|
|
``git submodule update --init`` instead (adding ``--init`` to the above
|
|
|
|
command).
|
|
|
|
|
|
|
|
Some common errors that can arise when failing to update submodules include:
|
|
|
|
|
|
|
|
* ``fatal: <some path> does not exist`` when performing Git operations
|
|
|
|
* Build errors, particularly referring to structures in the ``df::`` namespace
|
|
|
|
or the ``library/include/df`` folder
|
|
|
|
* ``Not a known DF version`` when starting DF
|
|
|
|
* ``Run 'git submodule update --init'`` when running CMake
|
|
|
|
|
|
|
|
Submodules are a particularly confusing feature of Git. The
|
|
|
|
`Git Book <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ has a
|
|
|
|
thorough explanation of them (as well as of many other aspects of Git) and
|
|
|
|
is a recommended resource if you run into any issues. Other DFHack developers
|
|
|
|
are also able to help with any submodule-related (or Git-related) issues
|
|
|
|
you may encounter.
|
2016-06-29 17:38:15 -06:00
|
|
|
|
2017-03-01 18:44:47 -07:00
|
|
|
**More notes**:
|
2016-06-29 17:38:15 -06:00
|
|
|
|
2017-03-01 19:29:17 -07:00
|
|
|
* `note-offline-builds` - read this if your build machine may not have an internet connection!
|
2017-03-01 18:44:47 -07:00
|
|
|
* `note-old-git-and-dfhack`
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
Contributing to DFHack
|
|
|
|
======================
|
2020-05-13 20:25:42 -06:00
|
|
|
To contribute to DFHack on GitHub, you will need a GitHub account. Only some
|
|
|
|
DFHack developers can push directly to the DFHack repositories; we recommend
|
|
|
|
making a fork of whatever repos you are interested in contributing to, making
|
|
|
|
changes there, and submitting pull requests. `GitHub's pull request tutorial
|
|
|
|
<https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests>`_
|
|
|
|
is a good resource for getting started with pull requests (some things to note:
|
|
|
|
our work mainly happens on the ``develop`` branch, and you will need to use
|
|
|
|
your own fork, assuming that you don't have write access to the DFHack repos).
|
|
|
|
|
|
|
|
Most development-related discussion happens on IRC or in individual GitHub
|
|
|
|
issues and pull requests, but there are also other ways to reach out - see
|
|
|
|
`support` for details.
|
|
|
|
|
|
|
|
For more details on contributing to DFHack, including pull requests, code
|
|
|
|
format, and more, please see `contributing-code`.
|
2015-12-14 23:08:25 -07:00
|
|
|
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2016-10-08 14:57:33 -06:00
|
|
|
Build settings
|
|
|
|
==============
|
|
|
|
|
2019-07-16 17:33:33 -06:00
|
|
|
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.
|
|
|
|
|
2018-07-16 22:58:49 -06:00
|
|
|
Generator
|
|
|
|
---------
|
|
|
|
|
|
|
|
The ``Ninja`` CMake build generator is the prefered 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.
|
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
2019-07-16 17:33:33 -06:00
|
|
|
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.
|
|
|
|
|
2016-10-08 14:57:33 -06:00
|
|
|
Build type
|
|
|
|
----------
|
|
|
|
|
2015-11-05 22:58:58 -07:00
|
|
|
``cmake`` allows you to pick a build type by changing the ``CMAKE_BUILD_TYPE`` variable::
|
2015-09-22 08:06:56 -06:00
|
|
|
|
|
|
|
cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
|
|
|
|
|
2018-07-16 22:58:49 -06:00
|
|
|
Valid and useful build types include 'Release' and 'RelWithDebInfo'. The default
|
2018-07-13 08:33:01 -06:00
|
|
|
build type is 'Release'.
|
2016-10-08 14:57:33 -06:00
|
|
|
|
|
|
|
Target architecture (32-bit vs. 64-bit)
|
|
|
|
---------------------------------------
|
|
|
|
|
|
|
|
Set DFHACK_BUILD_ARCH to either ``32`` or ``64`` to build a 32-bit or 64-bit
|
2018-07-17 09:10:46 -06:00
|
|
|
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.
|
2016-10-08 14:57:33 -06:00
|
|
|
|
|
|
|
::
|
|
|
|
|
|
|
|
cmake .. -DDFHACK_BUILD_ARCH=32
|
|
|
|
|
|
|
|
*or*
|
|
|
|
::
|
|
|
|
|
|
|
|
cmake .. -DDFHACK_BUILD_ARCH=64
|
2015-07-24 08:49:17 -06:00
|
|
|
|
2017-03-01 18:35:27 -07:00
|
|
|
Note that the scripts in the "build" folder on Windows will set the architecture
|
|
|
|
automatically.
|
|
|
|
|
2016-10-08 14:57:33 -06:00
|
|
|
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.
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2015-07-24 08:49:17 -06:00
|
|
|
Linux
|
|
|
|
=====
|
|
|
|
On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD.
|
2012-02-24 12:25:53 -07:00
|
|
|
|
2010-07-19 21:27:12 -06:00
|
|
|
Dependencies
|
2015-11-05 03:40:09 -07:00
|
|
|
------------
|
2011-07-30 21:50:37 -06:00
|
|
|
DFHack is meant to be installed into an existing DF folder, so get one ready.
|
2010-07-19 21:27:12 -06:00
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
We assume that any Linux platform will have ``git`` available (though it may
|
2016-08-23 13:43:32 -06:00
|
|
|
need to be installed with your package manager.)
|
2015-11-05 22:58:58 -07:00
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
To build DFHack you need GCC version 4.8 or later. GCC 4.8 is easiest to work
|
|
|
|
with due to avoiding libstdc++ issues (see below), but any version from 4.8
|
|
|
|
onwards (including 5.x) will work.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
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.
|
2011-07-30 21:50:37 -06:00
|
|
|
|
2019-07-20 15:11:11 -06:00
|
|
|
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.
|
|
|
|
|
2018-05-09 20:47:42 -06:00
|
|
|
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
|
|
|
|
able to find them in your distro repositories.
|
2011-12-24 06:44:14 -07:00
|
|
|
|
2016-03-18 06:30:04 -06:00
|
|
|
To build `stonesense`, you'll also need OpenGL headers.
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
Here are some package install commands for various platforms:
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
* On Arch linux:
|
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
* For the required Perl modules: ``perl-xml-libxml`` and ``perl-xml-libxslt`` (or through ``cpan``)
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
* On Ubuntu::
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2018-07-13 08:33:01 -06:00
|
|
|
apt-get install gcc cmake ninja-build git zlib1g-dev libsdl1.2-dev libxml-libxml-perl libxml-libxslt-perl
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2019-02-09 04:36:53 -07:00
|
|
|
* On Fedora::
|
|
|
|
|
|
|
|
yum install gcc-c++ cmake ninja-build git zlib-devel SDL-devel perl-core perl-XML-LibXML perl-XML-LibXSLT ruby
|
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
* Debian and derived distros should have similar requirements to Ubuntu.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
Multilib dependencies
|
|
|
|
---------------------
|
|
|
|
If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the
|
|
|
|
multilib development tools and libraries:
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
* ``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>`.
|
2015-08-10 08:12:40 -06:00
|
|
|
|
2011-07-30 21:50:37 -06:00
|
|
|
Build
|
2015-11-05 03:40:09 -07:00
|
|
|
-----
|
2015-09-24 04:17:58 -06:00
|
|
|
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::
|
2015-03-04 15:33:12 -07:00
|
|
|
|
2010-07-19 21:27:12 -06:00
|
|
|
cd build
|
2018-07-13 08:33:01 -06:00
|
|
|
cmake .. -G Ninja -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=<path to DF>
|
2018-07-16 22:58:49 -06:00
|
|
|
ninja install # or ninja -jX install to specify the number of cores (X) to use
|
2011-03-13 12:38:32 -06:00
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
<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.
|
2011-03-13 12:38:32 -06:00
|
|
|
|
2011-07-30 21:50:37 -06:00
|
|
|
Alternatively, you can use ccmake instead of cmake::
|
2015-03-04 15:33:12 -07:00
|
|
|
|
2011-03-13 12:38:32 -06:00
|
|
|
cd build
|
2018-07-13 08:33:01 -06:00
|
|
|
ccmake .. -G Ninja
|
|
|
|
ninja install
|
2011-03-13 12:38:32 -06:00
|
|
|
|
|
|
|
This will show a curses-based interface that lets you set all of the
|
2015-12-14 23:08:25 -07:00
|
|
|
extra options. You can also use a cmake-friendly IDE like KDevelop 4
|
2015-11-05 22:58:58 -07:00
|
|
|
or the cmake-gui program.
|
2011-03-13 12:38:32 -06:00
|
|
|
|
2015-11-05 22:58:58 -07:00
|
|
|
Incompatible libstdc++
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
2016-08-23 13:43:32 -06:00
|
|
|
When compiling dfhack yourself, it builds against your system libstdc++. When
|
|
|
|
Dwarf Fortress runs, it uses a libstdc++ shipped with the binary, which comes
|
|
|
|
from GCC 4.8 and is incompatible with code compiled with newer GCC versions. If
|
|
|
|
you compile DFHack with a GCC version newer than 4.8, you will see an error
|
|
|
|
message such as::
|
2013-04-03 14:28:11 -06:00
|
|
|
|
|
|
|
./libs/Dwarf_Fortress: /pathToDF/libs/libstdc++.so.6: version
|
2016-08-23 13:43:32 -06:00
|
|
|
`GLIBCXX_3.4.18' not found (required by ./hack/libdfhack.so)
|
2013-04-03 14:28:11 -06:00
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
To fix this you can compile with GCC 4.8 or remove the libstdc++ shipped with
|
2015-11-07 15:18:50 -07:00
|
|
|
DF, which causes DF to use your system libstdc++ instead::
|
2013-04-03 14:28:11 -06:00
|
|
|
|
|
|
|
cd /path/to/DF/
|
|
|
|
rm libs/libstdc++.so.6
|
|
|
|
|
2015-11-07 15:18:50 -07:00
|
|
|
Note that distributing binaries compiled with newer GCC versions requires end-
|
|
|
|
users to delete libstdc++ themselves and have a libstdc++ on their system from
|
|
|
|
the same GCC version or newer. For this reason, distributing anything compiled
|
2016-08-23 13:43:32 -06:00
|
|
|
with GCC versions newer than 4.8 is discouraged. In the future we may start
|
2015-12-14 23:08:25 -07:00
|
|
|
bundling a later libstdc++ as part of the DFHack package, so as to enable
|
2016-08-23 13:43:32 -06:00
|
|
|
compilation-for-distribution with a GCC newer than 4.8.
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2012-10-16 13:58:34 -06:00
|
|
|
Mac OS X
|
|
|
|
========
|
2015-07-24 08:49:17 -06:00
|
|
|
DFHack functions similarly on OS X and Linux, and the majority of the
|
2018-07-13 08:33:01 -06:00
|
|
|
information above regarding the build process (cmake and ninja) applies here
|
2015-07-24 08:49:17 -06:00
|
|
|
as well.
|
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
DFHack can officially be built on OS X with GCC 4.8 or 7. Anything newer than 7
|
2017-01-05 16:32:12 -07:00
|
|
|
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.
|
2016-08-23 13:43:32 -06:00
|
|
|
|
|
|
|
.. _osx-new-gcc-notes:
|
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
Notes for GCC 8+ or OS X 10.10+ users
|
|
|
|
-------------------------------------
|
2016-08-23 13:43:32 -06:00
|
|
|
|
|
|
|
If none of these situations apply to you, skip to `osx-setup`.
|
|
|
|
|
2017-01-05 16:32:12 -07:00
|
|
|
If you have issues building on OS X 10.10 (Yosemite) or above, try definining
|
|
|
|
the following environment variable::
|
2013-03-14 12:42:15 -06:00
|
|
|
|
2015-11-05 03:40:09 -07:00
|
|
|
export MACOSX_DEPLOYMENT_TARGET=10.9
|
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
If you build with a GCC version newer than 7, DFHack will probably crash
|
2016-08-23 13:43:32 -06:00
|
|
|
immediately on startup, or soon after. To fix this, you will need to replace
|
|
|
|
``hack/libstdc++.6.dylib`` with a symlink to the ``libstdc++.6.dylib`` included
|
|
|
|
in your version of GCC::
|
2015-12-18 18:59:23 -07:00
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
cd <path to df>/hack && mv libstdc++.6.dylib libstdc++.6.dylib.orig &&
|
|
|
|
ln -s [PATH_TO_LIBSTDC++] .
|
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
For example, with GCC 6.3.0, ``PATH_TO_LIBSTDC++`` would be::
|
2016-08-23 13:43:32 -06:00
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
/usr/local/Cellar/gcc@6/6.3.0/lib/gcc/6/libstdc++.6.dylib # for 64-bit DFHack
|
|
|
|
/usr/local/Cellar/gcc@6/6.3.0/lib/gcc/6/i386/libstdc++.6.dylib # for 32-bit DFHack
|
2016-08-23 13:43:32 -06:00
|
|
|
|
|
|
|
**Note:** If you build with a version of GCC that requires this, your DFHack
|
|
|
|
build will *not* be redistributable. (Even if you copy the ``libstdc++.6.dylib``
|
|
|
|
from your GCC version and distribute that too, it will fail on older OS X
|
|
|
|
versions.) For this reason, if you plan on distributing DFHack, it is highly
|
2018-04-04 18:01:52 -06:00
|
|
|
recommended to use GCC 4.8 or 7.
|
2016-08-23 13:43:32 -06:00
|
|
|
|
|
|
|
.. _osx-setup:
|
2015-12-18 18:59:23 -07:00
|
|
|
|
|
|
|
Dependencies and system set-up
|
|
|
|
------------------------------
|
|
|
|
|
|
|
|
#. Download and unpack a copy of the latest DF
|
2016-08-23 13:43:32 -06:00
|
|
|
#. Install Xcode from the Mac App Store
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-18 18:59:23 -07:00
|
|
|
#. Install the XCode Command Line Tools by running the following command::
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
xcode-select --install
|
|
|
|
|
2015-12-18 18:59:23 -07:00
|
|
|
#. Install dependencies
|
2012-10-20 07:06:33 -06:00
|
|
|
|
2016-08-23 13:43:32 -06:00
|
|
|
It is recommended to use Homebrew instead of MacPorts, as it is generally
|
|
|
|
cleaner, quicker, and smarter. For example, installing MacPort's GCC will
|
|
|
|
install more than twice as many dependencies as Homebrew's will, and all in
|
|
|
|
both 32-bit and 64-bit variants. Homebrew also doesn't require constant use
|
|
|
|
of sudo.
|
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
Using `Homebrew <http://brew.sh/>`_ (recommended)::
|
2015-07-24 08:49:17 -06:00
|
|
|
|
2015-11-05 03:40:09 -07:00
|
|
|
brew tap homebrew/versions
|
|
|
|
brew install git
|
|
|
|
brew install cmake
|
2018-07-13 08:33:01 -06:00
|
|
|
brew install ninja
|
2018-04-04 18:01:52 -06:00
|
|
|
brew install gcc@7
|
2015-07-24 08:49:17 -06:00
|
|
|
|
2015-11-06 17:35:44 -07:00
|
|
|
Using `MacPorts <https://www.macports.org>`_::
|
2015-03-04 15:33:12 -07:00
|
|
|
|
2018-07-13 08:33:01 -06:00
|
|
|
sudo port install gcc7 +universal cmake +universal git-core +universal ninja +universal
|
2015-03-04 15:33:12 -07:00
|
|
|
|
2015-11-05 03:40:09 -07:00
|
|
|
Macports will take some time - maybe hours. At some point it may ask
|
|
|
|
you to install a Java environment; let it do so.
|
2012-10-20 07:06:33 -06:00
|
|
|
|
2015-12-18 18:59:23 -07:00
|
|
|
#. Install Perl dependencies
|
2015-12-14 23:08:25 -07:00
|
|
|
|
|
|
|
* Using system Perl
|
|
|
|
|
|
|
|
* ``sudo cpan``
|
|
|
|
|
|
|
|
If this is the first time you've run cpan, you will need to go through the setup
|
|
|
|
process. Just stick with the defaults for everything and you'll be fine.
|
|
|
|
|
|
|
|
If you are running OS X 10.6 (Snow Leopard) or earlier, good luck!
|
|
|
|
You'll need to open a separate Terminal window and run::
|
|
|
|
|
|
|
|
sudo ln -s /usr/include/libxml2/libxml /usr/include/libxml
|
2012-10-20 07:06:33 -06:00
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
* ``install XML::LibXML``
|
|
|
|
* ``install XML::LibXSLT``
|
2012-10-20 07:06:33 -06:00
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
* In a separate, local Perl install
|
2012-10-20 07:06:33 -06:00
|
|
|
|
2015-12-15 07:16:51 -07:00
|
|
|
Rather than using system Perl, you might also want to consider
|
|
|
|
the Perl manager, `Perlbrew <http://perlbrew.pl>`_.
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2015-12-15 11:50:59 -07:00
|
|
|
This manages Perl 5 locally under ``~/perl5/``, providing an easy
|
|
|
|
way to install Perl and run CPAN against it without ``sudo``.
|
2015-12-15 11:51:37 -07:00
|
|
|
It can maintain multiple Perl installs and being local has the
|
|
|
|
benefit of easy migration and insulation from OS issues and upgrades.
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2015-12-15 07:16:51 -07:00
|
|
|
See http://perlbrew.pl/ for more details.
|
2015-12-14 23:08:25 -07:00
|
|
|
|
2015-12-18 18:59:23 -07:00
|
|
|
Building
|
|
|
|
--------
|
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
* Get the DFHack source as per section `compile-how-to-get-the-code`, above.
|
|
|
|
* Set environment variables
|
|
|
|
|
|
|
|
Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``)::
|
2015-07-24 08:49:17 -06:00
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
export CC=/usr/local/bin/gcc-7
|
|
|
|
export CXX=/usr/local/bin/g++-7
|
2015-07-24 08:49:17 -06:00
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
Macports::
|
2012-10-20 07:06:33 -06:00
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
export CC=/opt/local/bin/gcc-mp-7
|
|
|
|
export CXX=/opt/local/bin/g++-mp-7
|
2014-02-24 15:46:08 -07:00
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
Change the version numbers appropriately if you installed a different version of GCC.
|
|
|
|
|
2018-04-04 18:01:52 -06:00
|
|
|
If you are confident that you have GCC in your path, you can omit the absolute paths::
|
|
|
|
|
|
|
|
export CC=gcc-7
|
|
|
|
export CXX=g++-7
|
|
|
|
|
|
|
|
etc.
|
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
* Build dfhack::
|
2012-10-20 07:06:33 -06:00
|
|
|
|
|
|
|
mkdir build-osx
|
|
|
|
cd build-osx
|
2018-07-13 08:33:01 -06:00
|
|
|
cmake .. -G Ninja -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=<path to DF>
|
2018-07-16 22:58:49 -06:00
|
|
|
ninja install # or ninja -jX install to specify the number of cores (X) to use
|
2015-12-18 18:59:23 -07:00
|
|
|
|
2015-12-18 19:39:03 -07:00
|
|
|
<path to DF> should be a path to a copy of Dwarf Fortress, of the appropriate
|
|
|
|
version for the DFHack you are building.
|
2012-10-16 13:58:34 -06:00
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
.. _compile-windows:
|
2013-03-14 12:42:15 -06:00
|
|
|
|
2012-02-24 12:25:53 -07:00
|
|
|
Windows
|
|
|
|
=======
|
2012-02-24 12:28:17 -07:00
|
|
|
On Windows, DFHack replaces the SDL library distributed with DF.
|
2012-02-24 12:25:53 -07:00
|
|
|
|
|
|
|
Dependencies
|
2015-11-05 03:40:09 -07:00
|
|
|
------------
|
2015-12-14 20:30:08 -07:00
|
|
|
You will need the following:
|
|
|
|
|
2018-07-11 19:29:11 -06:00
|
|
|
* Microsoft Visual C++ 2015 or 2017
|
2015-12-14 20:30:08 -07:00
|
|
|
* Git
|
|
|
|
* CMake
|
|
|
|
* Perl with XML::LibXML and XML::LibXSLT
|
|
|
|
|
|
|
|
* It is recommended to install StrawberryPerl, which includes both.
|
|
|
|
|
2017-03-01 18:35:27 -07:00
|
|
|
* Python (for documentation; optional, except for release builds)
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2017-03-01 18:35:27 -07:00
|
|
|
Microsoft Visual Studio 2015
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2018-07-11 19:29:11 -06:00
|
|
|
DFHack has to be compiled with the Microsoft Visual C++ 2015 or 2017 toolchain on Windows;
|
|
|
|
other versions won't work against Dwarf Fortress due to ABI and STL incompatibilities.
|
2015-12-20 14:25:25 -07:00
|
|
|
|
2018-07-11 19:29:11 -06:00
|
|
|
You can install Visual Studio 2015_ or 2017_ Community edition for free, which
|
|
|
|
include all the features needed by DFHack. You can also download just the
|
|
|
|
`build tools`_ if you aren't going to use Visual Studio to edit code.
|
|
|
|
|
|
|
|
.. _2015: https://visualstudio.microsoft.com/vs/older-downloads/#visual-studio-2015-and-other-products
|
|
|
|
.. _2017: https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&rel=15
|
|
|
|
.. _build tools: https://visualstudio.microsoft.com/vs/older-downloads/#microsoft-build-tools-2015-update-3
|
2015-12-20 14:25:25 -07:00
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
Additional dependencies: installing with the Chocolatey Package Manager
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2017-03-01 18:35:27 -07:00
|
|
|
|
|
|
|
The remainder of dependencies - Git, CMake, StrawberryPerl, and Python - can be
|
|
|
|
most easily installed using the Chocolatey Package Manger. Chocolatey is a
|
2015-12-19 07:17:39 -07:00
|
|
|
\*nix-style package manager for Windows. It's fast, small (8-20MB on disk)
|
|
|
|
and very capable. Think "``apt-get`` for Windows."
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2017-03-01 18:35:27 -07:00
|
|
|
Chocolatey is a recommended way of installing the required dependencies
|
|
|
|
as it's quicker, requires less effort, and will install known-good utilities
|
2015-12-19 07:17:39 -07:00
|
|
|
guaranteed to have the correct setup (especially PATH).
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
To install Chocolatey and the required dependencies:
|
|
|
|
|
|
|
|
* Go to https://chocolatey.org in a web browser
|
|
|
|
* At the top of the page it will give you the install command to copy
|
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
* Copy the first one, which starts ``@powershell ...``
|
2015-12-14 20:30:08 -07:00
|
|
|
* It won't be repeated here in case it changes in future Chocolatey releases.
|
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
* Open an elevated (Admin) ``cmd.exe`` window
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
* On Windows 8 and later this can be easily achieved by:
|
|
|
|
|
|
|
|
* right-clicking on the Start Menu, or pressing Win+X.
|
|
|
|
* choosing "Command Prompt (Admin)"
|
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
* On earlier Windows: find ``cmd.exe`` in Start Menu, right click
|
2015-12-14 20:30:08 -07:00
|
|
|
and choose Open As Administrator.
|
|
|
|
|
2015-12-19 07:17:39 -07:00
|
|
|
* Paste in the Chocolatey install command and hit enter
|
2015-12-15 13:21:22 -07:00
|
|
|
* Close this ``cmd.exe`` window and open another Admin ``cmd.exe`` in the same way
|
2015-12-14 20:30:08 -07:00
|
|
|
* Run the following command::
|
|
|
|
|
2015-12-23 15:31:23 -07:00
|
|
|
choco install git cmake.portable strawberryperl -y
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
* Close the Admin ``cmd.exe`` window; you're done!
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
You can now use all of these utilities from any normal ``cmd.exe`` window.
|
|
|
|
You only need Admin/elevated ``cmd.exe`` for running ``choco install`` commands;
|
2015-12-14 23:08:25 -07:00
|
|
|
for all other purposes, including compiling DFHack, you should use
|
2015-12-19 07:17:39 -07:00
|
|
|
a normal ``cmd.exe`` (or, better, an improved terminal like `Cmder <http://cmder.net/>`_;
|
|
|
|
details below, under Build.)
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-19 07:17:39 -07:00
|
|
|
**NOTE**: you can run the above ``choco install`` command even if you already have
|
|
|
|
Git, CMake or StrawberryPerl installed. Chocolatey will inform you if any software
|
|
|
|
is already installed and won't re-install it. In that case, please check the PATHs
|
|
|
|
are correct for that utility as listed in the manual instructions below. Or, better,
|
|
|
|
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.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
Additional dependencies: installing manually
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2015-12-19 07:17:39 -07:00
|
|
|
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.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
Git
|
|
|
|
^^^
|
|
|
|
Some examples:
|
2010-07-19 21:27:12 -06:00
|
|
|
|
2015-11-05 22:58:58 -07:00
|
|
|
* `Git for Windows <https://git-for-windows.github.io>`_ (command-line and GUI)
|
|
|
|
* `tortoisegit <https://tortoisegit.org>`_ (GUI and File Explorer integration)
|
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
CMake
|
|
|
|
^^^^^
|
|
|
|
You can get the win32 installer version from
|
2015-11-05 22:58:58 -07:00
|
|
|
`the official site <http://www.cmake.org/cmake/resources/software.html>`_.
|
2011-07-30 21:50:37 -06:00
|
|
|
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.
|
2010-07-19 21:27:12 -06:00
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
Perl / Strawberry Perl
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
2015-12-15 13:21:22 -07:00
|
|
|
For the code generation parts 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.
|
2011-12-24 06:44:14 -07:00
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
After install, ensure Perl is in your user's PATH. This can be edited from
|
|
|
|
``Control Panel -> System -> Advanced System Settings -> Environment Variables``.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
The following three directories must be in PATH, in this order:
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
* ``<path to perl>\c\bin``
|
|
|
|
* ``<path to perl>\perl\site\bin``
|
|
|
|
* ``<path to perl>\perl\bin``
|
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
Be sure to close and re-open any existing ``cmd.exe`` windows after updating
|
|
|
|
your PATH.
|
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
If you already have a different version of Perl (for example the one from Cygwin),
|
2015-12-15 13:21:22 -07:00
|
|
|
you can run into some trouble. Either remove the other Perl install from PATH, or
|
2015-12-14 20:30:08 -07:00
|
|
|
install XML::LibXML and XML::LibXSLT for it using CPAN.
|
2012-02-04 20:28:20 -07:00
|
|
|
|
2011-07-30 21:50:37 -06:00
|
|
|
Build
|
2015-11-05 03:40:09 -07:00
|
|
|
-----
|
2017-03-01 18:35:27 -07:00
|
|
|
There are several different batch files in the ``win32`` and ``win64``
|
|
|
|
subfolders in the ``build`` folder, along with a script that's used for picking
|
|
|
|
the DF path. Use the subfolder corresponding to the architecture that you want
|
|
|
|
to build for.
|
2012-02-04 20:28:20 -07:00
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
First, run ``set_df_path.vbs`` and point the dialog that pops up at
|
|
|
|
a suitable DF installation which is of the appropriate version for the DFHack
|
2015-12-15 13:21:22 -07:00
|
|
|
you are compiling. The result is the creation of the file ``DF_PATH.txt`` in
|
|
|
|
the build directory. It contains the full path to the destination directory.
|
|
|
|
You could therefore also create this file manually - or copy in a pre-prepared
|
|
|
|
version - if you prefer.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
Next, run one of the scripts with ``generate`` prefix. These create the MSVC
|
|
|
|
solution file(s):
|
2012-02-04 20:28:20 -07:00
|
|
|
|
|
|
|
* ``all`` will create a solution with everything enabled (and the kitchen sink).
|
2015-12-15 13:21:22 -07:00
|
|
|
* ``gui`` will pop up the CMake GUI and let you choose what to build.
|
2015-11-05 03:40:09 -07:00
|
|
|
This is probably what you want most of the time. Set the options you are interested
|
|
|
|
in, then hit configure, then generate. More options can appear after the configure step.
|
|
|
|
* ``minimal`` will create a minimal solution with just the bare necessities -
|
|
|
|
the main library and standard plugins.
|
2017-03-01 18:35:27 -07:00
|
|
|
* ``release`` will create a solution with everything that should be included in
|
|
|
|
release builds of DFHack. Note that this includes documentation, which requires
|
|
|
|
Python.
|
2010-07-19 21:27:12 -06:00
|
|
|
|
2012-02-04 20:28:20 -07:00
|
|
|
Then you can either open the solution with MSVC or use one of the msbuild scripts:
|
2010-07-19 21:27:12 -06:00
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
Building/installing from the command line:
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2015-12-15 13:21:22 -07:00
|
|
|
In the build directory you will find several ``.bat`` files:
|
|
|
|
|
2015-11-05 03:40:09 -07:00
|
|
|
* Scripts with ``build`` prefix will only build DFHack.
|
2012-02-04 20:28:20 -07:00
|
|
|
* Scripts with ``install`` prefix will build DFHack and install it to the previously selected DF path.
|
|
|
|
* Scripts with ``package`` prefix will build and create a .zip package of DFHack.
|
|
|
|
|
2015-12-14 23:08:25 -07:00
|
|
|
Compiling from the command line is generally the quickest and easiest option.
|
2015-12-15 13:21:22 -07:00
|
|
|
However be aware that due to the limitations of ``cmd.exe`` - especially in
|
|
|
|
versions of Windows prior to Windows 10 - it can be very hard to see what happens
|
|
|
|
during a build. If you get a failure, you may miss important errors or warnings
|
|
|
|
due to the tiny window size and extremely limited scrollback. For that reason you
|
|
|
|
may prefer to compile in the IDE which will always show all build output.
|
2015-12-14 23:08:25 -07:00
|
|
|
|
|
|
|
Alternatively (or additionally), consider installing an improved Windows terminal
|
|
|
|
such as `Cmder <http://cmder.net/>`_. Easily installed through Chocolatey with:
|
2015-12-19 07:17:39 -07:00
|
|
|
``choco install cmder -y``.
|
2015-12-14 23:08:25 -07:00
|
|
|
|
2015-12-21 18:57:39 -07:00
|
|
|
**Note for Cygwin/msysgit users**: It is also possible to compile DFHack from a
|
2015-12-21 19:02:12 -07:00
|
|
|
Bash command line. This has three potential benefits:
|
2015-12-21 18:57:39 -07:00
|
|
|
|
|
|
|
* When you've installed Git and are using its Bash, but haven't added Git to your path:
|
|
|
|
|
|
|
|
* You can load Git's Bash and as long as it can access Perl and CMake, you can
|
|
|
|
use it for compile without adding Git to your system path.
|
|
|
|
|
|
|
|
* When you've installed Cygwin and its SSH server:
|
|
|
|
|
|
|
|
* You can now SSH in to your Windows install and compile from a remote terminal;
|
|
|
|
very useful if your Windows installation is a local VM on a \*nix host OS.
|
|
|
|
|
|
|
|
* In general: you can use Bash as your compilation terminal, meaning you have a decent
|
|
|
|
sized window, scrollback, etc.
|
|
|
|
|
|
|
|
* Whether you're accessing it locally as with Git's Bash, or remotely through
|
|
|
|
Cygwin's SSH server, this is far superior to using ``cmd.exe``.
|
|
|
|
|
|
|
|
You don't need to do anything special to compile from Bash. As long as your PATHs
|
|
|
|
are set up correctly, you can run the same generate- and build/install/package- bat
|
|
|
|
files as detailed above.
|
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
Building/installing from the Visual Studio IDE:
|
|
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
2017-03-01 18:35:27 -07:00
|
|
|
After running the CMake generate script you will have a new folder called VC2015
|
|
|
|
or VC2015_32, depending on the architecture you specified. Open the file
|
|
|
|
``dfhack.sln`` inside that folder. If you have multiple versions of Visual
|
|
|
|
Studio installed, make sure you open with Visual Studio 2015.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
The first thing you must then do is change the build type. It defaults to Debug,
|
|
|
|
but this cannot be used on Windows. Debug is not binary-compatible with DF.
|
2015-12-14 23:08:25 -07:00
|
|
|
If you try to use a debug build with DF, you'll only get crashes and for this
|
|
|
|
reason the Windows "debug" scripts actually do RelWithDebInfo builds.
|
|
|
|
After loading the Solution, change the Build Type to either ``Release``
|
|
|
|
or ``RelWithDebInfo``.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
Then build the ``INSTALL`` target listed under ``CMakePredefinedTargets``.
|
|
|
|
|
|
|
|
|
|
|
|
Building the documentation
|
2016-03-18 06:30:04 -06:00
|
|
|
==========================
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
DFHack documentation, like the file you are reading now, is created as .rst files,
|
|
|
|
which are in `reStructuredText (reST) <http://sphinx-doc.org/rest.html>`_ format.
|
|
|
|
This is a documenation format that has come from the Python community. It is very
|
2015-12-15 15:04:10 -07:00
|
|
|
similar in concept - and in syntax - to Markdown, as found on GitHub and many other
|
|
|
|
places. However it is more advanced than Markdown, with more features available when
|
|
|
|
compiled to HTML, such as automatic tables of contents, cross-linking, special
|
|
|
|
external links (forum, wiki, etc) and more. The documentation is compiled by a
|
|
|
|
Python tool, `Sphinx <http://sphinx-doc.org>`_.
|
|
|
|
|
|
|
|
The DFHack build process will compile the documentation but this has been disabled
|
|
|
|
by default. You only need to build the docs if you're changing them, or perhaps
|
|
|
|
if you want a local HTML copy; otherwise, read them easily online at
|
2015-12-14 20:30:08 -07:00
|
|
|
`ReadTheDoc's DFHack hosted documentation <https://dfhack.readthedocs.org>`_.
|
|
|
|
|
2015-12-15 15:04:10 -07:00
|
|
|
(Note that even if you do want a local copy, it is certainly not necesesary to
|
|
|
|
compile the documentation in order to read it. Like Markdown, reST documents are
|
|
|
|
designed to be just as readable in a plain-text editor as they are in HTML format.
|
|
|
|
The main thing you lose in plain text format is hyperlinking.)
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
|
|
|
|
Enabling documentation building
|
2016-03-18 06:30:04 -06:00
|
|
|
-------------------------------
|
2015-12-15 15:04:10 -07:00
|
|
|
First, make sure you have followed all the necessary steps for your platform as
|
|
|
|
outlined in the rest of this document.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
To compile documentation with DFHack, add the following flag to your ``cmake`` command::
|
|
|
|
|
|
|
|
-DBUILD_DOCS:bool=ON
|
|
|
|
|
2015-12-14 21:10:00 -07:00
|
|
|
For example::
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-14 21:10:00 -07:00
|
|
|
cmake .. -DCMAKE_BUILD_TYPE:string=Release -DBUILD_DOCS:bool=ON -DCMAKE_INSTALL_PREFIX=<path to DF>
|
2015-12-14 20:30:08 -07:00
|
|
|
|
2015-12-15 15:04:10 -07:00
|
|
|
Alternatively you can use the CMake GUI which allows options to be changed easily.
|
2015-12-15 13:30:11 -07:00
|
|
|
|
2015-12-15 15:04:10 -07:00
|
|
|
On Windows you should either use ``generate-msvc-gui.bat`` and set the option
|
|
|
|
through the GUI, or else if you want to use an alternate file, such as
|
|
|
|
``generate-msvc-all.bat``, you will need to edit it to add the flag.
|
|
|
|
Or you could just run ``cmake`` on the command line like in other platforms.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
Required dependencies
|
2016-03-18 06:30:04 -06:00
|
|
|
---------------------
|
2015-12-14 20:30:08 -07:00
|
|
|
In order to build the documentation, you must have Python with Sphinx
|
|
|
|
version 1.3.1 or later. Both Python 2.x and 3.x are supported.
|
|
|
|
|
|
|
|
When installing Sphinx from OS package managers, be aware that there is
|
|
|
|
another program called Sphinx, completely unrelated to documentation management.
|
2015-12-14 21:11:39 -07:00
|
|
|
Be sure you are installing the right Sphinx; it may be called ``python-sphinx``,
|
2015-12-15 13:21:22 -07:00
|
|
|
for example. To avoid doubt, ``pip`` can be used instead as detailed below.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
|
|
|
|
Linux
|
2015-12-14 21:11:39 -07:00
|
|
|
-----
|
2015-12-21 18:39:39 -07:00
|
|
|
Most Linux distributions will include Python as standard.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
Check your package manager to see if Sphinx 1.3.1 or later is available,
|
|
|
|
but at the time of writing Ubuntu for example only has 1.2.x.
|
|
|
|
|
2015-12-21 18:39:39 -07:00
|
|
|
You can instead install Sphinx with the pip package manager. This may need
|
|
|
|
to be installed from your OS package manager; this is the case on Ubuntu.
|
|
|
|
On Ubuntu/Debian, use the following to first install pip::
|
|
|
|
|
|
|
|
sudo apt-get install python-pip
|
|
|
|
|
|
|
|
Once pip is available, you can then install the Python Sphinx module with::
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
pip install sphinx
|
|
|
|
|
|
|
|
If you run this as a normal user it will install a local copy for your user only.
|
2015-12-21 18:39:39 -07:00
|
|
|
Run it with sudo if you want a system-wide install. Either is fine for DFHack,
|
|
|
|
however if installing locally do check that ``sphinx-build`` is in your path.
|
|
|
|
It may be installed in a directory such as ``~/.local/bin/``, so after pip
|
|
|
|
install, find ``sphinx-build`` and ensure its directory is in your local ``$PATH``.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
|
|
|
|
Mac OS X
|
|
|
|
--------
|
|
|
|
OS X has Python 2.7 installed by default, but it does not have the pip package manager.
|
|
|
|
|
|
|
|
You can install Homebrew's Python 3, which includes pip, and then install the
|
|
|
|
latest Sphinx using pip::
|
|
|
|
|
|
|
|
brew install python3
|
|
|
|
pip3 install sphinx
|
|
|
|
|
|
|
|
Alternatively, you can simply install Sphinx 1.3.x directly from Homebrew::
|
|
|
|
|
|
|
|
brew install sphinx-doc
|
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
This will install Sphinx for OS X's system Python 2.7, without needing pip.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
Either method works; if you plan to use Python for other purposes, it might best
|
|
|
|
to install Homebrew's Python 3 so that you have the latest Python as well as pip.
|
2015-12-15 13:21:22 -07:00
|
|
|
If not, just installing sphinx-doc for OS X's system Python 2.7 is fine.
|
2015-12-14 20:30:08 -07:00
|
|
|
|
|
|
|
|
|
|
|
Windows
|
|
|
|
-------
|
|
|
|
Use the Chocolatey package manager to install Python and pip,
|
|
|
|
then use pip to install Sphinx.
|
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
Run the following commands from an elevated (Admin) ``cmd.exe``, after installing
|
2015-12-14 20:30:08 -07:00
|
|
|
Chocolatey as outlined in the `Windows section <compile-windows>`::
|
|
|
|
|
|
|
|
choco install python pip -y
|
|
|
|
|
2015-12-15 13:21:22 -07:00
|
|
|
Then close that Admin ``cmd.exe``, re-open another Admin ``cmd.exe``, and run::
|
2015-11-05 03:40:09 -07:00
|
|
|
|
2015-12-14 20:30:08 -07:00
|
|
|
pip install sphinx
|
2017-03-01 18:44:47 -07:00
|
|
|
|
2018-04-02 20:22:20 -06:00
|
|
|
.. _build-changelog:
|
|
|
|
|
|
|
|
Building the changelogs
|
|
|
|
-----------------------
|
|
|
|
If you have Python installed, but do not want to build all of the documentation,
|
|
|
|
you can build the changelogs with the ``docs/gen_changelog.py`` script.
|
|
|
|
|
|
|
|
All changes should be listed in ``changelog.txt``. A description of this file's
|
|
|
|
format follows:
|
|
|
|
|
|
|
|
.. include:: /docs/changelog.txt
|
|
|
|
:start-after: ===help
|
|
|
|
:end-before: ===end
|
|
|
|
|
2017-03-01 18:44:47 -07:00
|
|
|
Misc. Notes
|
|
|
|
===========
|
|
|
|
|
2017-03-01 19:29:17 -07:00
|
|
|
.. _note-offline-builds:
|
|
|
|
|
|
|
|
Note on building DFHack offline
|
|
|
|
-------------------------------
|
|
|
|
|
|
|
|
As of 0.43.05, DFHack downloads several files during the build process, depending
|
|
|
|
on your target OS and architecture. If your build machine's internet connection
|
|
|
|
is unreliable, or nonexistent, you can download these files in advance.
|
|
|
|
|
|
|
|
First, you must locate the files you will need. These can be found in the
|
|
|
|
`dfhack-bin repo <https://github.com/DFHack/dfhack-bin/releases>`_. Look for the
|
|
|
|
most recent version number *before or equal to* the DF version which you are
|
|
|
|
building for. For example, suppose "0.43.05" and "0.43.07" are listed. You should
|
|
|
|
choose "0.43.05" if you are building for 0.43.05 or 0.43.06, and "0.43.07" if
|
|
|
|
you are building for 0.43.07 or 0.43.08.
|
|
|
|
|
|
|
|
Then, download all of the files you need, and save them to ``<path to DFHack
|
|
|
|
clone>/CMake/downloads/<any filename>``. The destination filename you choose
|
|
|
|
does not matter, as long as the files end up in the ``CMake/downloads`` folder.
|
|
|
|
You need to download all of the files for the architecture(s) you are building
|
|
|
|
for. For example, if you are building for 32-bit Linux and 64-bit Windows,
|
|
|
|
download all files starting with ``linux32`` and ``win64``. GitHub should sort
|
|
|
|
files alphabetically, so all the files you need should be next to each other.
|
|
|
|
|
2018-02-16 00:16:06 -07:00
|
|
|
.. note::
|
|
|
|
|
|
|
|
* Any files containing "allegro" in their filename are only necessary for
|
|
|
|
building `stonesense`. If you are not building Stonesense, you don't have to
|
|
|
|
download these, as they are larger than any other listed files.
|
|
|
|
|
2017-03-01 19:29:17 -07:00
|
|
|
It is recommended that you create a build folder and run CMake to verify that
|
|
|
|
you have downloaded everything at this point, assuming your download machine has
|
|
|
|
CMake installed. This involves running a "generate" batch script on Windows, or
|
2018-07-13 08:33:01 -06:00
|
|
|
a command starting with ``cmake .. -G Ninja`` on Linux and OS X, following the
|
2018-02-16 00:16:06 -07:00
|
|
|
instructions in the sections above. CMake should automatically locate files that
|
|
|
|
you placed in ``CMake/downloads``, and use them instead of attempting to
|
|
|
|
download them.
|
2017-03-01 19:29:17 -07:00
|
|
|
|
2017-03-01 18:44:47 -07:00
|
|
|
.. _note-old-git-and-dfhack:
|
|
|
|
|
|
|
|
Note on using very old git versions with pre-0.43.03 DFHack versions
|
|
|
|
--------------------------------------------------------------------
|
|
|
|
|
|
|
|
If you are using git 1.8.0 or older, and cloned DFHack before commit 85a920d
|
|
|
|
(around DFHack v0.43.03-alpha1), you may run into fatal git errors when updating
|
|
|
|
submodules after switching branches. This is due to those versions of git being
|
|
|
|
unable to handle our change from "scripts/3rdparty/name" submodules to a single
|
|
|
|
"scripts" submodule. This may be fixable by renaming .git/modules/scripts to
|
|
|
|
something else and re-running ``git submodule update --init`` on the branch with
|
|
|
|
the single scripts submodule (and running it again when switching back to the
|
|
|
|
one with multiple submodules, if necessary), but it is usually much simpler to
|
|
|
|
upgrade your git version.
|