From c0d582c406c89ef2106a508be3953325bec54cc8 Mon Sep 17 00:00:00 2001 From: Josh Cooper Date: Wed, 21 Dec 2022 20:35:40 -0400 Subject: [PATCH] more small screen changes --- docs/dev/Contributing.rst | 31 +- docs/dev/building/Compile.rst | 593 +++++++++-------------------- docs/dev/building/Dependencies.rst | 259 ++++++------- 3 files changed, 332 insertions(+), 551 deletions(-) diff --git a/docs/dev/Contributing.rst b/docs/dev/Contributing.rst index f503d9126..66be801f4 100644 --- a/docs/dev/Contributing.rst +++ b/docs/dev/Contributing.rst @@ -36,11 +36,24 @@ The sections below cover some guidelines that contributions should follow: .. contents:: :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 ` + will take priority over ideas or suggestions. + Code format ----------- * Four space indents for C++. Never use tabs for indentation in any language. * LF (Unix style) line terminators -* Avoid trailing whitespace +* No trailing whitespace * UTF-8 encoding * For C++: @@ -86,27 +99,13 @@ Pull request guidelines or add "WIP" to the title. Otherwise, your pull request may be reviewed and/or 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 ` - will take priority over ideas or suggestions. - - Other ways to help ================== 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: * reporting bugs and incomplete documentation -* improving the documentation +* improving the documentation (C++ api is rife) * finding third-party scripts to add * writing tutorials for newbies diff --git a/docs/dev/building/Compile.rst b/docs/dev/building/Compile.rst index f3f1cb0ed..a0a9b070c 100644 --- a/docs/dev/building/Compile.rst +++ b/docs/dev/building/Compile.rst @@ -2,13 +2,13 @@ .. _compile: -################ -Compiling DFHack -################ +########### +Compilation +########### 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 +writing scripts [lua] (not plugins), it is generally recommended (and easier) to use these `builds` instead of compiling DFHack from source. 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` +Instructions +============ .. _compile-linux: Linux -===== +----- On Linux, DFHack acts as a library that shadows parts of the SDL API using LD_PRELOAD. Dependencies ------------- - - +~~~~~~~~~~~~ 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 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 +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 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 ---------------------- +~~~~~~~~~~~~~~~~~~~~~ If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the multilib development tools and libraries: @@ -230,7 +314,7 @@ to use ``lxc`` to :forums:`create a virtual 32-bit environment <139553.msg5435310#msg5435310>`. Build ------ +~~~~~ Building is fairly straightforward. Enter the ``build`` folder (or create an empty folder in the DFHack directory to use instead) and start the build like this:: @@ -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 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 /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 `__ 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 `_ (recommended):: - - brew tap homebrew/versions - brew install git - brew install cmake - brew install ninja - brew install gcc@7 - - Using `MacPorts `_:: - - 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 `_. - - 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= - ninja install # or ninja -jX install to specify the number of cores (X) to use - - should be a path to a copy of Dwarf Fortress, of the appropriate - version for the DFHack you are building. - - .. _compile-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 `_; -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 ------ +~~~~~ 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 @@ -622,10 +395,26 @@ solution file(s): release builds of DFHack. Note that this includes documentation, which requires 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: * 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 files as detailed above. -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. +.. _compile-macos: -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``. +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. -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 -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. + Homebrew (if installed elsewhere, replace /usr/local with ``$(brew --prefix)``):: -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 - 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 + export CC=/opt/local/bin/gcc-mp-7 + export CXX=/opt/local/bin/g++-mp-7 -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. + Change the version numbers appropriately if you installed a different version of GCC. -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 -container. Inside the container, run the following commands:: + export CC=gcc-7 + export CXX=g++-7 - git clone https://github.com/DFHack/dfhack.git - cd dfhack - git submodule update --init - cd build - dfhack-configure windows 64 Release - dfhack-make + (adjust as needed for different GCC installations) -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. +* Build DFHack:: -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= + 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 -assets:: + should be a path to a copy of Dwarf Fortress, of the appropriate + 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. -Otherwise, you can do something like this in your host Linux environment to copy an -installed version to the container:: +Notes for GCC 8+ or OS X 10.10+ users +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - cd ~/.steam/steam/steamapps/common/Dwarf\ Fortress/ - docker cp . dfhack-win:df/ +If none of these situations apply to you, skip to `osx-setup`. -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 - cmake .. -DCMAKE_INSTALL_PREFIX=/home/buildmaster/df - ninja install - cd ~/df - wine64 "Dwarf Fortress.exe" +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:: -Other notes ------------ + cd /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 -host when you want to reattach:: +For example, with GCC 6.3.0, ``PATH_TO_LIBSTDC++`` would be:: - 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``. -That will handle all the wineserver management for you. +**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. -Building the documentation -========================== +.. _osx-m1-notes: -The steps above will not build DFHack's documentation by default. If you are -changing documentation, see `documentation` for details on how to build it. +Notes for M1 users +~~~~~~~~~~~~~~~~~~ -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 `__ 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 on your target OS and architecture. If your build machine's internet connection is unreliable, or nonexistent, you can download these files in advance. diff --git a/docs/dev/building/Dependencies.rst b/docs/dev/building/Dependencies.rst index ad065caa4..c6f69cc1b 100644 --- a/docs/dev/building/Dependencies.rst +++ b/docs/dev/building/Dependencies.rst @@ -26,10 +26,11 @@ System packages: * SDL (libsdl 1.2, not sdl2). * cmake +* git (required for `contributions`) * ccache (**optional**, but recommended to improve build times) * OpenGL headers (**optional**: to build `stonesense`) -* zlib (compression library used for `xlsxioreader`) -* build system +* zlib (compression library used for `xlsxioreader` -> `quickfort`) +* build system (e.g. gcc & ninja, or Visual Studio) .. 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 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 ------ +===== Here are some package install commands for various distributions: @@ -89,7 +99,7 @@ either by downloading it from `cmake.org `_ or through your package manager, if possible. Building 32-bit Binaries -======================== +~~~~~~~~~~~~~~~~~~~~~~~~ If you want to compile 32-bit DFHack on 64-bit distributions, you'll need the multilib development tools and libraries: @@ -113,7 +123,7 @@ to use ``lxc`` to .. _linux-incompatible-libstdcxx: Incompatible libstdc++ -====================== +~~~~~~~~~~~~~~~~~~~~~~ When compiling DFHack yourself, it builds against your system libstdc++. When Dwarf Fortress runs, it uses a libstdc++ shipped in the ``libs`` folder, which comes from GCC 4.8 and is incompatible with code compiled with newer GCC @@ -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 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 `_ (recommended):: - - brew tap homebrew/versions - brew install git - brew install cmake - brew install ninja - brew install gcc@7 - - Using `MacPorts `_:: - - 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 `_. - - 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 -------- +======= 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`` @@ -223,9 +160,7 @@ toolchain to build for windows. What you'll need is as follows: * Microsoft Visual C++ 2022, 2019, 2017, or 2015 (optional) -* ``v140`` or ``v140_xp`` toolchain - - * i.e. Microsoft Visual C++ 2015 Build Tools +* ``v140`` or ``v140_xp`` toolchain (Microsoft Visual C++ 2015 Build Tools) * Git (optional) * CMake * 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 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. All of the required tools are available from Microsoft as part of Visual Studio's Community 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 -Installing Dependencies -======================= - -It is recommended to use the package manager ``choco`` on windows for satisfying dependencies. -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 +With Choco +~~~~~~~~~~ +Many of the dependencies are simple enough to download and install via the +`chocolatey` package manager on the command line. -Common Dependencies -~~~~~~~~~~~~~~~~~~~ - -Installing with Choco -+++++++++++++++++++++ -To install the common dependencies:: +Here are some package install commands:: choco install cmake + choco install ccache choco install strawberryperl choco install python choco install sphinx + choco install visualstudio2022community + +.. _chocolatey-link: https://chocolatey.org/install -Installing Manually -+++++++++++++++++++ +Visual Studio +~~~~~~~~~~~~~ +You could install visual studio `manually`, 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 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 ^^^^^ @@ -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 -Visual Studio -~~~~~~~~~~~~~ +.. _install-visual-studio: +Visual Studio +^^^^^^^^^^^^^ 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. -**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 .. _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. 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, @@ -399,3 +330,73 @@ 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. + +.. _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 `_ (recommended):: + + brew tap homebrew/versions + brew install git + brew install cmake + brew install ninja + brew install gcc@7 + + Using `MacPorts `_:: + + 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 `_. + + 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.