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

stuff

develop
Josh Cooper 2022-12-23 17:33:43 -04:00
parent 994cb30f4d
commit 1993291a87
1 changed files with 103 additions and 127 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -86,44 +86,23 @@ assistance.
are also able to help with any submodule-related (or Git-related) issues
you may encounter.
Dependencies
------------
If you haven't already checked, this would be a good point to ensure you have
all the `dependencies <build-dependencies>`.
Contributing to DFHack
----------------------
For details on contributing to DFHack, including pull requests, code
format, and more, please see `contributing-code`.
All Platforms
=============
Before you can compile the code you'll need to configure your build with cmake. Some IDEs can do this,
but from command line is the usual way to do this; thought the windows section below points out some
windows batch files that can be used to avoid opening a terminal/command-prompt.
Build settings
==============
This section describes build configuration options that apply to all platforms.
If you don't have a working build environment set up yet, follow the instructions
in the platform-specific sections below first, then come back here.
Be sure to check out common `build options <build-options>`.
Instructions
============
.. contents::
:local:
:depth: 1
You should seek cmake's documentation online or via ``cmake --help`` to see how the command works. See
the `build-options` page for help finding the DFHack build options relevant to you.
.. _compile-linux:
Linux
-----
=====
On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD.
Build
~~~~~
-----
Building is fairly straightforward. Enter the ``build`` folder (or create an
empty folder in the DFHack directory to use instead) and start the build like this::
@ -145,97 +124,10 @@ This will show a curses-based interface that lets you set all of the
extra options. You can also use a cmake-friendly IDE like KDevelop 4
or the cmake-gui program.
Windows cross compiling from Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. 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 the `buildmaster` user) 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 download 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 install``.
That will handle all the wineserver management for you.
.. _compile-windows:
Windows
-------
Build
~~~~~
=======
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
@ -263,8 +155,8 @@ solution file(s):
Then you can either open the solution with MSVC or use one of the msbuild scripts.
Building/installing from the Visual Studio IDE
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
@ -279,8 +171,8 @@ or ``RelWithDebInfo``.
Then build the ``INSTALL`` target listed under ``CMakePredefinedTargets``.
Building/installing from the command line
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Command Line
------------
In the build directory you will find several ``.bat`` files:
* Scripts with ``build`` prefix will only build DFHack.
@ -324,7 +216,7 @@ files as detailed above.
.. _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.
@ -334,7 +226,7 @@ will require you to perform extra steps to get DFHack to run (see `osx-new-gcc-n
and your build will likely not be redistributable.
Building
~~~~~~~~
--------
* Get the DFHack source as per section `compile-how-to-get-the-code`, above.
* Set environment variables
@ -371,7 +263,7 @@ Building
.. _osx-new-gcc-notes:
Notes for GCC 8+ or OS X 10.10+ users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-------------------------------------
If you have issues building on OS X 10.10 (Yosemite) or above, try defining
the following environment variable::
@ -400,7 +292,7 @@ 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.
@ -418,10 +310,94 @@ addition to the normal ``CC`` and ``CXX`` flags above::
export PATH=/usr/local/bin:$PATH
Docker
======
.. highlight:: bash
You can use docker to build DFHack for windows. These instructions were developed
on a linux host system.
.. 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 the `buildmaster` user) 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 download 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.
.. _note-offline-builds:
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.