more small screen changes

develop
Josh Cooper 2022-12-21 20:35:40 -04:00
parent e60030e85e
commit c0d582c406
3 changed files with 332 additions and 551 deletions

@ -36,11 +36,24 @@ The sections below cover some guidelines that contributions should follow:
.. contents:: .. contents::
:local: :local:
General contribution guidelines
-------------------------------
* If convenient, compile on multiple platforms when changing anything that
compiles. Our CI should catch anything that fails to build, but checking in
advance can sometimes let you know of any issues sooner.
* Update documentation when applicable - see `docs-standards` for details.
* Update ``docs/changelog.txt`` and ``docs/about/Authors.rst`` when applicable. See
`build-changelog` for more information on the changelog format.
* Submit ideas and bug reports as :issue:`issues on GitHub <>`.
Posts in the forum thread can easily get missed or forgotten.
* Work on :issue:`reported problems <?q=is:open+-label:idea>`
will take priority over ideas or suggestions.
Code format Code format
----------- -----------
* Four space indents for C++. Never use tabs for indentation in any language. * Four space indents for C++. Never use tabs for indentation in any language.
* LF (Unix style) line terminators * LF (Unix style) line terminators
* Avoid trailing whitespace * No trailing whitespace
* UTF-8 encoding * UTF-8 encoding
* For C++: * For C++:
@ -86,27 +99,13 @@ Pull request guidelines
or add "WIP" to the title. Otherwise, your pull request may be reviewed and/or or add "WIP" to the title. Otherwise, your pull request may be reviewed and/or
merged prematurely. merged prematurely.
General contribution guidelines
-------------------------------
* If convenient, compile on multiple platforms when changing anything that
compiles. Our CI should catch anything that fails to build, but checking in
advance can sometimes let you know of any issues sooner.
* Update documentation when applicable - see `docs-standards` for details.
* Update ``docs/changelog.txt`` and ``docs/about/Authors.rst`` when applicable. See
`build-changelog` for more information on the changelog format.
* Submit ideas and bug reports as :issue:`issues on GitHub <>`.
Posts in the forum thread can easily get missed or forgotten.
* Work on :issue:`reported problems <?q=is:open+-label:idea>`
will take priority over ideas or suggestions.
Other ways to help Other ways to help
================== ==================
DFHack is a software project, but there's a lot more to it than programming. DFHack is a software project, but there's a lot more to it than programming.
If you're not comfortable programming, you can help by: If you're not comfortable programming, you can help by:
* reporting bugs and incomplete documentation * reporting bugs and incomplete documentation
* improving the documentation * improving the documentation (C++ api is rife)
* finding third-party scripts to add * finding third-party scripts to add
* writing tutorials for newbies * writing tutorials for newbies

@ -2,13 +2,13 @@
.. _compile: .. _compile:
################ ###########
Compiling DFHack 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 (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<build-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
@ -173,17 +173,17 @@ Other settings
See our page on `build options<build-options>` See our page on `build options<build-options>`
Instructions
============
.. _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 Dependencies
------------ ~~~~~~~~~~~~
You also need zlib, libsdl (1.2, not sdl2, like DF), perl, and the XML::LibXML 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 and XML::LibXSLT perl packages (for the code generation parts). You should be
able to find them in your distribution's repositories. able to find them in your distribution's repositories.
@ -206,9 +206,93 @@ 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 yum install gcc-c++ cmake ninja-build git zlib-devel SDL-devel perl-core perl-XML-LibXML perl-XML-LibXSLT ruby
Windows cross compiling from Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. highlight:: bash
If you are on Linux but need to produce a Windows build (for example, because the
DF version you're working on isn't out for Linux yet), here is how you can build
and run a Windows binary on Linux.
.. contents::
:local:
:depth: 1
Step 1: prepare a docker image
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
On your Linux host, install and run the docker daemon and then run these commands::
xhost +local:root
git clone https://github.com/BenLubar/build-env.git
cd build-env/msvc
docker build .
docker image ls
IMAGE_ID=<your image id>
docker run -it --env="DISPLAY" --env="QT_X11_NO_MITSHM=1" --volume=/tmp/.X11-unix:/tmp/.X11-unix --user buildmaster --name dfhack-win $IMAGE_ID
The ``xhost`` command and ``--env`` parameters are there so you can eventually
run Dwarf Fortress from the container and have it display on your host.
Step 2: build DFHack
^^^^^^^^^^^^^^^^^^^^
The ``docker run`` command above will give you a shell prompt (as root) in the
container. Inside the container, run the following commands::
git clone https://github.com/DFHack/dfhack.git
cd dfhack
git submodule update --init
cd build
dfhack-configure windows 64 Release
dfhack-make
Inside the ``dfhack-*`` scripts there are several commands that set up the wine
server. Each invocation of a windows tool will cause wine to run in the container.
Preloading the wineserver and telling it not to exit will speed configuration and
compilation up considerably (approx. 10x). You can configure and build DFHack
with regular ``cmake`` and ``ninja`` commands, but your build will go much slower.
Step 3: copy Dwarf Fortress to the container
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
First, create a directory in the container to house the Dwarf Fortress binary and
assets::
mkdir ~/df
If you can just downlaod Dwarf Fortress directly into the container, then that's fine.
Otherwise, you can do something like this in your host Linux environment to copy an
installed version to the container::
cd ~/.steam/steam/steamapps/common/Dwarf\ Fortress/
docker cp . dfhack-win:df/
Step 4: install DFHack and run DF
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Back in the container, run the following commands::
cd dfhack/build
cmake .. -DCMAKE_INSTALL_PREFIX=/home/buildmaster/df
ninja install
cd ~/df
wine64 "Dwarf Fortress.exe"
Other notes
^^^^^^^^^^^
Closing your shell will kick you out of the container. Run this command on your Linux
host when you want to reattach::
docker start -ai dfhack-win
If you edit code and need to rebuild, run ``dfhack-make`` and then ``ninja install``.
That will handle all the wineserver management for you.
Multilib dependencies Multilib dependencies
--------------------- ~~~~~~~~~~~~~~~~~~~~~
If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the
multilib development tools and libraries: multilib development tools and libraries:
@ -230,7 +314,7 @@ to use ``lxc`` to
:forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. :forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`.
Build Build
----- ~~~~~
Building is fairly straightforward. Enter the ``build`` folder (or create an 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:: empty folder in the DFHack directory to use instead) and start the build like this::
@ -280,323 +364,12 @@ 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 you are planning on distributing binaries to other users, we recommend using an
older GCC (but still at least 4.8) version if possible. older GCC (but still at least 4.8) version if possible.
.. _compile-macos:
macOS
=====
DFHack functions similarly on macOS and Linux, and the majority of the
information above regarding the build process (CMake and Ninja) applies here
as well.
DFHack can officially be built on macOS only with GCC 4.8 or 7. Anything newer than 7
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.
.. _osx-new-gcc-notes:
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
the following environment variable::
export MACOSX_DEPLOYMENT_TARGET=10.9
If you build with a GCC version newer than 7, DFHack will probably crash
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::
cd <path to df>/hack && mv libstdc++.6.dylib libstdc++.6.dylib.orig &&
ln -s [PATH_TO_LIBSTDC++] .
For example, with GCC 6.3.0, ``PATH_TO_LIBSTDC++`` would be::
/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
**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
recommended to use GCC 4.8 or 7.
.. _osx-m1-notes:
Notes for M1 users
------------------
Alongside the above, you will need to follow these additional steps to get it
running on Apple silicon.
Install an x86 copy of ``homebrew`` alongside your existing one. `This
stackoverflow answer <https://stackoverflow.com/a/64951025>`__ describes the
process.
Follow the normal macOS steps to install ``cmake`` and ``gcc`` via your x86 copy of
``homebrew``. Note that this will install a GCC version newer than 7, so see
`osx-new-gcc-notes`.
In your terminal, ensure you have your path set to the correct homebrew in
addition to the normal ``CC`` and ``CXX`` flags above::
export PATH=/usr/local/bin:$PATH
.. _osx-setup:
Dependencies and system set-up
------------------------------
#. Download and unpack a copy of the latest DF
#. Install Xcode from the Mac App Store
#. Install the XCode Command Line Tools by running the following command::
xcode-select --install
#. Install dependencies
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``.
Using `Homebrew <https://brew.sh/>`_ (recommended)::
brew tap homebrew/versions
brew install git
brew install cmake
brew install ninja
brew install gcc@7
Using `MacPorts <https://www.macports.org>`_::
sudo port install gcc7 +universal cmake +universal git-core +universal ninja +universal
Macports will take some time - maybe hours. At some point it may ask
you to install a Java environment; let it do so.
#. Install Perl dependencies
* 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
* ``install XML::LibXML``
* ``install XML::LibXSLT``
* In a separate, local Perl install
Rather than using system Perl, you might also want to consider
the Perl manager, `Perlbrew <https://perlbrew.pl>`_.
This manages Perl 5 locally under ``~/perl5/``, providing an easy
way to install Perl and run CPAN against it without ``sudo``.
It can maintain multiple Perl installs and being local has the
benefit of easy migration and insulation from OS issues and upgrades.
See https://perlbrew.pl/ for more details.
Building
--------
* 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)``)::
export CC=/usr/local/bin/gcc-7
export CXX=/usr/local/bin/g++-7
Macports::
export CC=/opt/local/bin/gcc-mp-7
export CXX=/opt/local/bin/g++-mp-7
Change the version numbers appropriately if you installed a different version of GCC.
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
(adjust as needed for different GCC installations)
* Build DFHack::
mkdir build-osx
cd build-osx
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.
.. _compile-windows: .. _compile-windows:
Windows Windows
======= -------
On Windows, DFHack replaces the SDL library distributed with DF.
Dependencies
------------
You will need the following:
* Microsoft Visual C++ 2022, 2019, 2017, or 2015 (optional)
* Microsoft Visual C++ 2015 Build Tools
* Git
* CMake
* Perl with XML::LibXML and XML::LibXSLT
* It is recommended to install StrawberryPerl, which includes both.
* Python (for documentation; optional, except for release builds)
Microsoft Visual Studio
~~~~~~~~~~~~~~~~~~~~~~~
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.
You can also download just the Visual C++ 2015 `build tools`_ if you aren't going to use
Visual Studio to edit code.
Option 1: Build Tools Only
^^^^^^^^^^^^^^^^^^^^^^^^^^
Click `build tools`_ and you will be prompted to login to your Microsoft account.
Then you should be redirected to a page with various download options with 2015
in their name. If this redirect doesn't occur, just copy, paste, and enter the
download link again and you should see the options. You need to get:
Visual C++ Build Tools for Visual Studio 2015 with Update 3.
Click the download button next to it and a dropdown of download formats will appear.
Select the DVD format to download an ISO file. When the download is complete,
click on the ISO file and a folder will popup with the following contents:
* packages (folder)
* VCPlusPlusBuildTools2015Update3_x64_Files.cat
* VisualCppBuildTools_Full.exe
The packages folder contains the dependencies that are required by the build tools.
These include:
* Microsoft .NET Framework 4.6.1 Developer Pack
* Microsoft Visual C++ 2015 Redistributable (x64) - 14.0.24210
* Windows 10 Universal SDK - 10.0.10240
* Windows 8.1 SDK
Click VisualCppBuildTools_Full.exe and use the default options provided by the installer
wizard that appears. After the installation is completed, add the path where MSBuild.exe
was installed to your PATH environment variable. The path should be:
* ``C:\Program Files (x86)\MSBuild\14.0\Bin``
Note that this process may install only the ``v140`` toolchain, not the ``v140_xp`` toolchain that
is normally used to compile build releases of DFHack. Due to a bug in the Microsoft-provided libraries used with
the ``v140_xp`` toolchain that Microsoft has never fixed, DFHack (and probably also Dwarf Fortress itself)
doesn't run reliably on 64-bit XP. Investigations have so far suggested that ``v140`` and
``v140_xp`` are ABI-compatible. As such, there should be no harm in using ``v140`` instead of
``v140_xp`` as the build toolchain, at least on 64-bit platforms. However, it is our policy to use
``v140_xp`` for release builds for both 32-bit and 64-bit Windows,
since 32-bit releases of Dwarf Fortress work on XP and ``v140_xp`` is required for compatibility with
XP.
The ``v141`` toolchain, in Visual Studio 2017, has been empirically documented to be incompatible with
released versions of Dwarf Fortress and cannot be used to make usable builds of DFHack.
Option 2: IDE + Build Tools
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Click Visual Studio 2022_ or 2019_ to download an installer wizard that will prompt you
to select the optional tools you want to download alongside the IDE. You may need to log into
(or create) a Microsoft account in order to download Visual Studio.
In addition to selecting the workload for "Desktop Development with C++",
you will also need to go to the "Individual Components" tab in the Installer and
select the following additional components to get the "``v140_xp``" toolchain that DFHack
requires for ABI compatibility with recent releases of Dwarf Fortress:
* MSVC v140 - VS 2015 C++ build tools (v14.00)
* C++ Windows XP Support for VS 2017 (v141) tools [Deprecated]
Yes, this is unintuitive. Installing XP Support for VS 2017 installs XP Support for VS 2015
if the 2015 toolchain is installed.
.. _2022: https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&cid=2030&passive=false
.. _2019: https://my.visualstudio.com/Downloads?q=visual%20studio%202019&wt.mc_id=o~msft~vscom~older-downloads
.. _build tools: https://my.visualstudio.com/Downloads?q=visual%20studio%202015&wt.mc_id=o~msft~vscom~older-downloads
Additional dependencies: installing with the Chocolatey Package Manager
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The remainder of dependencies - Git, CMake, StrawberryPerl, and Python - can be
most easily installed using the Chocolatey Package Manager. Chocolatey is a
\*nix-style package manager for Windows. It's fast, small (8-20MB on disk)
and very capable. Think "``apt-get`` for Windows."
Chocolatey is a recommended way of installing the required dependencies
as it's quicker, requires less effort, and will install known-good utilities
guaranteed to have the correct setup (especially PATH).
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
* Copy the first one, which starts ``@powershell ...``
* It won't be repeated here in case it changes in future Chocolatey releases.
* Open an elevated (Admin) ``cmd.exe`` window
* 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)"
* On earlier Windows: find ``cmd.exe`` in Start Menu, right click
and choose Open As Administrator.
* Paste in the Chocolatey install command and hit enter
* Close this ``cmd.exe`` window and open another Admin ``cmd.exe`` in the same way
* Run the following command::
choco install git cmake.portable strawberryperl -y
* Close the Admin ``cmd.exe`` window; you're done!
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;
for all other purposes, including compiling DFHack, you should use
a normal ``cmd.exe`` (or, better, an improved terminal like `Cmder <https://cmder.net/>`_;
details below, under Build.)
**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.
Build Build
----- ~~~~~
There are several different batch files in the ``win32`` and ``win64`` 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 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 the DF path. Use the subfolder corresponding to the architecture that you want
@ -622,10 +395,26 @@ solution file(s):
release builds of DFHack. Note that this includes documentation, which requires release builds of DFHack. Note that this includes documentation, which requires
Python. Python.
Then you can either open the solution with MSVC or use one of the msbuild scripts: Then you can either open the solution with MSVC or use one of the msbuild scripts.
Building/installing from the Visual Studio IDE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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.
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.
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``.
Building/installing from the command line: Then build the ``INSTALL`` target listed under ``CMakePredefinedTargets``.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Building/installing from the command line
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In the build directory you will find several ``.bat`` files: In the build directory you will find several ``.bat`` files:
* Scripts with ``build`` prefix will only build DFHack. * Scripts with ``build`` prefix will only build DFHack.
@ -666,117 +455,109 @@ You don't need to do anything special to compile from Bash. As long as your PATH
are set up correctly, you can run the same generate- and build/install/package- bat are set up correctly, you can run the same generate- and build/install/package- bat
files as detailed above. files as detailed above.
Building/installing from the Visual Studio IDE: .. _compile-macos:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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.
The first thing you must then do is change the build type. It defaults to Debug, macOS
but this cannot be used on Windows. Debug is not binary-compatible with DF. -----
If you try to use a debug build with DF, you'll only get crashes and for this DFHack functions similarly on macOS and Linux, and the majority of the
reason the Windows "debug" scripts actually do RelWithDebInfo builds. information above regarding the build process (CMake and Ninja) applies here
After loading the Solution, change the Build Type to either ``Release`` as well.
or ``RelWithDebInfo``.
Then build the ``INSTALL`` target listed under ``CMakePredefinedTargets``. DFHack can officially be built on macOS only with GCC 4.8 or 7. Anything newer than 7
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.
Windows cross compiling from Linux Building
================================== ~~~~~~~~
.. highlight:: bash * Get the DFHack source as per section `compile-how-to-get-the-code`, above.
* Set environment variables
If you are on Linux but need to produce a Windows build (for example, because the Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``)::
DF version you're working on isn't out for Linux yet), here is how you can build
and run a Windows binary on Linux.
Step 1: prepare a docker image export CC=/usr/local/bin/gcc-7
------------------------------ export CXX=/usr/local/bin/g++-7
On your Linux host, install and run the docker daemon and then run these commands:: Macports::
xhost +local:root export CC=/opt/local/bin/gcc-mp-7
git clone https://github.com/BenLubar/build-env.git export CXX=/opt/local/bin/g++-mp-7
cd build-env/msvc
docker build .
docker image ls
IMAGE_ID=<your image id>
docker run -it --env="DISPLAY" --env="QT_X11_NO_MITSHM=1" --volume=/tmp/.X11-unix:/tmp/.X11-unix --user buildmaster --name dfhack-win $IMAGE_ID
The ``xhost`` command and ``--env`` parameters are there so you can eventually Change the version numbers appropriately if you installed a different version of GCC.
run Dwarf Fortress from the container and have it display on your host.
Step 2: build DFHack If you are confident that you have GCC in your path, you can omit the absolute paths::
--------------------
The ``docker run`` command above will give you a shell prompt (as root) in the export CC=gcc-7
container. Inside the container, run the following commands:: export CXX=g++-7
git clone https://github.com/DFHack/dfhack.git (adjust as needed for different GCC installations)
cd dfhack
git submodule update --init
cd build
dfhack-configure windows 64 Release
dfhack-make
Inside the ``dfhack-*`` scripts there are several commands that set up the wine * Build DFHack::
server. Each invocation of a windows tool will cause wine to run in the container.
Preloading the wineserver and telling it not to exit will speed configuration and
compilation up considerably (approx. 10x). You can configure and build DFHack
with regular ``cmake`` and ``ninja`` commands, but your build will go much slower.
Step 3: copy Dwarf Fortress to the container mkdir build-osx
-------------------------------------------- cd build-osx
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
First, create a directory in the container to house the Dwarf Fortress binary and <path to DF> should be a path to a copy of Dwarf Fortress, of the appropriate
assets:: version for the DFHack you are building.
mkdir ~/df .. _osx-new-gcc-notes:
If you can just downlaod Dwarf Fortress directly into the container, then that's fine. Notes for GCC 8+ or OS X 10.10+ users
Otherwise, you can do something like this in your host Linux environment to copy an ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
installed version to the container::
cd ~/.steam/steam/steamapps/common/Dwarf\ Fortress/ If none of these situations apply to you, skip to `osx-setup`.
docker cp . dfhack-win:df/
Step 4: install DFHack and run DF If you have issues building on OS X 10.10 (Yosemite) or above, try defining
--------------------------------- the following environment variable::
Back in the container, run the following commands:: export MACOSX_DEPLOYMENT_TARGET=10.9
cd dfhack/build If you build with a GCC version newer than 7, DFHack will probably crash
cmake .. -DCMAKE_INSTALL_PREFIX=/home/buildmaster/df immediately on startup, or soon after. To fix this, you will need to replace
ninja install ``hack/libstdc++.6.dylib`` with a symlink to the ``libstdc++.6.dylib`` included
cd ~/df in your version of GCC::
wine64 "Dwarf Fortress.exe"
Other notes cd <path to df>/hack && mv libstdc++.6.dylib libstdc++.6.dylib.orig &&
----------- ln -s [PATH_TO_LIBSTDC++] .
Closing your shell will kick you out of the container. Run this command on your Linux For example, with GCC 6.3.0, ``PATH_TO_LIBSTDC++`` would be::
host when you want to reattach::
docker start -ai dfhack-win /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
If you edit code and need to rebuild, run ``dfhack-make`` and then ``ninja install``. **Note:** If you build with a version of GCC that requires this, your DFHack
That will handle all the wineserver management for you. 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
recommended to use GCC 4.8 or 7.
Building the documentation .. _osx-m1-notes:
==========================
The steps above will not build DFHack's documentation by default. If you are Notes for M1 users
changing documentation, see `documentation` for details on how to build it. ~~~~~~~~~~~~~~~~~~
Misc. Notes Alongside the above, you will need to follow these additional steps to get it
=========== running on Apple silicon.
.. _note-offline-builds: Install an x86 copy of ``homebrew`` alongside your existing one. `This
stackoverflow answer <https://stackoverflow.com/a/64951025>`__ describes the
process.
Follow the normal macOS steps to install ``cmake`` and ``gcc`` via your x86 copy of
``homebrew``. Note that this will install a GCC version newer than 7, so see
`osx-new-gcc-notes`.
Note on building DFHack offline In your terminal, ensure you have your path set to the correct homebrew in
------------------------------- addition to the normal ``CC`` and ``CXX`` flags above::
export PATH=/usr/local/bin:$PATH
.. _note-offline-builds:
Building DFHack Offline
-----------------------
As of 0.43.05, DFHack downloads several files during the build process, depending 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 on your target OS and architecture. If your build machine's internet connection
is unreliable, or nonexistent, you can download these files in advance. is unreliable, or nonexistent, you can download these files in advance.

@ -26,10 +26,11 @@ System packages:
* SDL (libsdl 1.2, not sdl2). * SDL (libsdl 1.2, not sdl2).
* cmake * cmake
* git (required for `contributions<pr-link>`)
* 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`) * zlib (compression library used for `xlsxioreader` -> `quickfort`)
* build system * 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
@ -45,10 +46,19 @@ 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
----------
.. contents:: Install Instructions
:local:
:depth: 2
.. _linux-dependency-instructions: .. _linux-dependency-instructions:
Linux Linux
----- =====
Here are some package install commands for various distributions: Here are some package install commands for various distributions:
@ -89,7 +99,7 @@ either by downloading it from `cmake.org <https://cmake.org/download/>`_ or
through your package manager, if possible. through your package manager, if possible.
Building 32-bit Binaries Building 32-bit Binaries
======================== ~~~~~~~~~~~~~~~~~~~~~~~~
If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the
multilib development tools and libraries: multilib development tools and libraries:
@ -113,7 +123,7 @@ to use ``lxc`` to
.. _linux-incompatible-libstdcxx: .. _linux-incompatible-libstdcxx:
Incompatible libstdc++ Incompatible libstdc++
====================== ~~~~~~~~~~~~~~~~~~~~~~
When compiling DFHack yourself, it builds against your system libstdc++. When When compiling DFHack yourself, it builds against your system libstdc++. When
Dwarf Fortress runs, it uses a libstdc++ shipped in the ``libs`` folder, which 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 comes from GCC 4.8 and is incompatible with code compiled with newer GCC
@ -138,83 +148,10 @@ 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 you are planning on distributing binaries to other users, we recommend using an
older GCC (but still at least 4.8) version if possible. older GCC (but still at least 4.8) version if possible.
.. _mac-dependency-instructions:
macOS
-----
DFHack can officially be built on macOS only with GCC 4.8 or 7. Anything newer than 7
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.
.. _osx-setup:
Dependencies and system set-up
==============================
#. Download and unpack a copy of the latest DF
#. Install Xcode from the Mac App Store
#. Install the XCode Command Line Tools by running the following command::
xcode-select --install
#. Install dependencies
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``.
Using `Homebrew <https://brew.sh/>`_ (recommended)::
brew tap homebrew/versions
brew install git
brew install cmake
brew install ninja
brew install gcc@7
Using `MacPorts <https://www.macports.org>`_::
sudo port install gcc7 +universal cmake +universal git-core +universal ninja +universal
Macports will take some time - maybe hours. At some point it may ask
you to install a Java environment; let it do so.
#. Install Perl dependencies
* 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
* ``install XML::LibXML``
* ``install XML::LibXSLT``
* In a separate, local Perl install
Rather than using system Perl, you might also want to consider
the Perl manager, `Perlbrew <https://perlbrew.pl>`_.
This manages Perl 5 locally under ``~/perl5/``, providing an easy
way to install Perl and run CPAN against it without ``sudo``.
It can maintain multiple Perl installs and being local has the
benefit of easy migration and insulation from OS issues and upgrades.
See https://perlbrew.pl/ for more details.
.. _windows-dependency-instructions: .. _windows-dependency-instructions:
Windows Windows
------- =======
On Windows, DFHack replaces the SDL library distributed with DF. On Windows, DFHack replaces the SDL library distributed with DF.
For ABI compatibility with recent releases of Dwarf Fortress, DFHack requires the ``v140`` or ``v140_xp`` For ABI compatibility with recent releases of Dwarf Fortress, DFHack requires the ``v140`` or ``v140_xp``
@ -223,9 +160,7 @@ toolchain to build for windows.
What you'll need is as follows: What you'll need is as follows:
* Microsoft Visual C++ 2022, 2019, 2017, or 2015 (optional) * Microsoft Visual C++ 2022, 2019, 2017, or 2015 (optional)
* ``v140`` or ``v140_xp`` toolchain * ``v140`` or ``v140_xp`` toolchain (Microsoft Visual C++ 2015 Build Tools)
* i.e. Microsoft Visual C++ 2015 Build Tools
* Git (optional) * Git (optional)
* CMake * CMake
* StrawberryPerl, OR CPAN (optional, see nested) * StrawberryPerl, OR CPAN (optional, see nested)
@ -243,7 +178,7 @@ 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 Visual Studio 2015 is no longer supported by Microsoft and it can be difficult to obtain
working installers for this product today. The recommended approach is to use a modern community 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 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. 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 All of the required tools are available from Microsoft as part of Visual Studio's Community
Edition at no charge. Edition at no charge.
@ -253,37 +188,51 @@ Visual Studio to edit code.
.. _build tools: https://my.visualstudio.com/Downloads?q=visual%20studio%202015&wt.mc_id=o~msft~vscom~older-downloads .. _build tools: https://my.visualstudio.com/Downloads?q=visual%20studio%202015&wt.mc_id=o~msft~vscom~older-downloads
Installing Dependencies With Choco
======================= ~~~~~~~~~~
Many of the dependencies are simple enough to download and install via the
It is recommended to use the package manager ``choco`` on windows for satisfying dependencies. `chocolatey<chocolatey-link>` package manager on the command line.
Install instructions for this command line tool can be found at https://chocolatey.org/install
..
Perhaps when the windows package manager
is more mature we can switch to it.
.. contents:: Windows
:local:
:depth: 2
Common Dependencies Here are some package install commands::
~~~~~~~~~~~~~~~~~~~
Installing with Choco
+++++++++++++++++++++
To install the common dependencies::
choco install cmake choco install cmake
choco install ccache
choco install strawberryperl choco install strawberryperl
choco install python choco install python
choco install sphinx choco install sphinx
choco install visualstudio2022community
.. _chocolatey-link: https://chocolatey.org/install
Installing Manually Visual Studio
+++++++++++++++++++ ~~~~~~~~~~~~~
You could install visual studio `manually<install-visual-studio>`, perhaps even the build tools as well.
You could also just run a ``choco`` command. For example::
choco install visualstudio2022community
If Visual Studio is installed follow these next steps for the build tools:
1. Open **Visual Studio Installer**.
2. Select modify, for whichever version you've chosen to utilize.
3. Check the boxes for the following components:
* "Desktop Development with C++"
* "C++ Windows XP Support for VS 2017 (v141) tools [Deprecated]"
* "MSVC v140 - VS 2015 C++ build tools (v14.00)"
Yes, this is unintuitive. Installing XP Support for VS 2017 installs XP Support for VS 2015
if the 2015 toolchain is installed.
Manually
~~~~~~~~
If you prefer to install manually rather than using Chocolatey, details and 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
:local:
:depth: 1
CMake CMake
^^^^^ ^^^^^
@ -328,42 +277,24 @@ See `sphinx-install` at https://www.sphinx-doc.org/
.. _sphinx-install: https://www.sphinx-doc.org/en/master/usage/installation.html .. _sphinx-install: https://www.sphinx-doc.org/en/master/usage/installation.html
Visual Studio .. _install-visual-studio:
~~~~~~~~~~~~~
Visual Studio
^^^^^^^^^^^^^
Click Visual Studio 2022_ or 2019_ to download an installer wizard that will prompt you Click Visual Studio 2022_ or 2019_ to download an installer wizard that will prompt you
to select the optional tools you want to download alongside the IDE. You may need to log into to select the optional tools you want to download alongside the IDE. You may need to log into
(or create) a Microsoft account in order to download Visual Studio. (or create) a Microsoft account in order to download Visual Studio.
**OR**
To install this toolchain in your visual studio, you'll need to have first installed visual studio.
For example::
choco install visualstudio2022community
If Visual Studio is installed follow these next steps:
1. Open **Visual Studio Installer**.
2. Select modify, for whichever version you've chosen to utilize.
3. Check the boxes for the following components:
* "Desktop Development with C++"
* "C++ Windows XP Support for VS 2017 (v141) tools [Deprecated]"
* "MSVC v140 - VS 2015 C++ build tools (v14.00)"
Yes, this is unintuitive. Installing XP Support for VS 2017 installs XP Support for VS 2015
if the 2015 toolchain is installed.
.. _2022: https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&cid=2030&passive=false .. _2022: https://visualstudio.microsoft.com/thank-you-downloading-visual-studio/?sku=Community&channel=Release&version=VS2022&source=VSLandingPage&cid=2030&passive=false
.. _2019: https://my.visualstudio.com/Downloads?q=visual%20studio%202019&wt.mc_id=o~msft~vscom~older-downloads .. _2019: https://my.visualstudio.com/Downloads?q=visual%20studio%202019&wt.mc_id=o~msft~vscom~older-downloads
Build Tools Only Build Tools [Without Visual Studio]
~~~~~~~~~~~~~~~~ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Click `build tools`_ and you will be prompted to login to your Microsoft account. Click `build tools`_ and you will be prompted to login to your Microsoft account.
Then you should be redirected to a page with various download options with 2015 Then you should be redirected to a page with various download options with 2015
in their name. If this redirect doesn't occur, just copy, paste, and enter the in their name. If this redirect doesn't occur, just copy, paste, and enter the
download link again and you should see the options. You need to get: download link again and you should see the options. You need to get:
Visual C++ Build Tools for Visual Studio 2015 with Update 3. Visual C++ Build Tools for Visual Studio 2015 with Update 3.
Click the download button next to it and a dropdown of download formats will appear. Click the download button next to it and a dropdown of download formats will appear.
Select the DVD format to download an ISO file. When the download is complete, Select the DVD format to download an ISO file. When the download is complete,
@ -399,3 +330,73 @@ XP.
The ``v141`` toolchain, in Visual Studio 2017, has been empirically documented to be incompatible with The ``v141`` toolchain, in Visual Studio 2017, has been empirically documented to be incompatible with
released versions of Dwarf Fortress and cannot be used to make usable builds of DFHack. released versions of Dwarf Fortress and cannot be used to make usable builds of DFHack.
.. _mac-dependency-instructions:
macOS
=====
DFHack can officially be built on macOS only with GCC 4.8 or 7. Anything newer than 7
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.
.. _osx-setup:
#. Download and unpack a copy of the latest DF
#. Install Xcode from the Mac App Store
#. Install the XCode Command Line Tools by running the following command::
xcode-select --install
#. Install dependencies
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``.
Using `Homebrew <https://brew.sh/>`_ (recommended)::
brew tap homebrew/versions
brew install git
brew install cmake
brew install ninja
brew install gcc@7
Using `MacPorts <https://www.macports.org>`_::
sudo port install gcc7 +universal cmake +universal git-core +universal ninja +universal
Macports will take some time - maybe hours. At some point it may ask
you to install a Java environment; let it do so.
#. Install Perl dependencies
* 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
* ``install XML::LibXML``
* ``install XML::LibXSLT``
* In a separate, local Perl install
Rather than using system Perl, you might also want to consider
the Perl manager, `Perlbrew <https://perlbrew.pl>`_.
This manages Perl 5 locally under ``~/perl5/``, providing an easy
way to install Perl and run CPAN against it without ``sudo``.
It can maintain multiple Perl installs and being local has the
benefit of easy migration and insulation from OS issues and upgrades.
See https://perlbrew.pl/ for more details.