diff --git a/docs/dev/building/Compile.rst b/docs/dev/building/Compile.rst index 2de2735b2..cedf7e210 100644 --- a/docs/dev/building/Compile.rst +++ b/docs/dev/building/Compile.rst @@ -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 `. - - -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 `. - -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= - 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= + 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.