diff --git a/docs/Installing.rst b/docs/Installing.rst new file mode 100644 index 000000000..92e5cfa0a --- /dev/null +++ b/docs/Installing.rst @@ -0,0 +1,132 @@ +.. _installing: + +================= +Installing DFHack +================= + +.. contents:: + :local: + + +Requirements +============ + +DFHack supports Windows, Linux, and macOS, and both 64-bit and 32-bit builds +of Dwarf Fortress. + +.. _installing-df-version: + +DFHack releases generally only support the version of Dwarf Fortress that they +are named after. For example, DFHack 0.40.24-r5 only supported DF 0.40.24. +DFHack releases *never* support newer versions of DF, because DFHack requires +data about DF that is only possible to obtain after DF has been released. +Occasionally, DFHack releases will be able to maintain support for older +versions of DF - for example, DFHack 0.34.11-r5 supported both DF 0.34.11 and +0.34.10. For maximum stability, you should usually use the latest versions of +both DF and DFHack. + +Windows +------- + +* DFHack only supports the SDL version of Dwarf Fortress. The "legacy" version + will *not* work with DFHack (the "small" SDL version is acceptable, however). +* Windows XP and older are *not* supported, due in part to a + `Visual C++ 2015 bug `_ + +The Windows build of DFHack should work under Wine on other operating systems, +although this is not tested very often. It is recommended to use the native +build for your operating system instead. + +.. _installing-reqs-linux: + +Linux +----- + +Generally, DFHack should work on any modern Linux distribution. There are +multiple release binaries provided - as of DFHack 0.47.04-r1, there are built +with GCC 7 and GCC 4.8 (as indicated by the ``gcc`` component of their +filenames). Using the newest build that works on your system is recommended. +The GCC 4.8 build is built on Ubuntu 14.04 and targets an older glibc, so it +should work on older distributions. + +In the event that none of the provided binaries work on your distribution, +you may need to `compile DFHack from source `. + +macOS +----- + +OS X 10.6.8 or later is required. + + +.. _downloading: + +Downloading DFHack +================== + +Stable builds of DFHack are available on `GitHub `_. +GitHub has been known to change their layout periodically, but as of July 2020, +downloads are available at the bottom of the release notes for each release, under a section +named "Assets" (which you may have to expand). The name of the file indicates +which DF version, platform, and architecture the build supports - the platform +and architecture (64-bit or 32-bit) **must** match your build of DF. The DF +version should also match your DF version - see `above ` +for details. For example: + +* ``dfhack-0.47.04-r1-Windows-64bit.zip`` supports 64-bit DF on Windows +* ``dfhack-0.47.04-r1-Linux-32bit-gcc-7.tar.bz2`` supports 32-bit DF on Linux + (see `installing-reqs-linux` for details on the GCC version indicator) + +The `DFHack website `_ also provides links to +unstable builds. These files have a different naming scheme, but the same +restrictions apply (e.g. a file named ``Windows64`` is for 64-bit Windows DF). + +.. warning:: + + Do *not* download the source code from GitHub, either from the releases page + or by clicking "Download ZIP" on the repo homepage. This will give you an + incomplete copy of the DFHack source code, which will not work as-is. (If + you want to compile DFHack instead of using a pre-built release, see + `compile` for instructions.) + +Installing DFHack +================= + +When you `download DFHack `, you will end up with a release archive +(a ``.zip`` file on Windows, or a ``.tar.bz2`` file on other platforms). Your +operating system should have built-in utilities capable of extracting files from +these archives. + +The release archives contain several files and folders, including a ``hack`` +folder, a ``dfhack-config`` folder, and a ``dfhack.init-example`` file. All +files from the DFHack archive need to be copied into the root DF folder, which +should already include a ``data`` folder and a ``raw`` folder, among other +things. Some packs and other redistributions of Dwarf Fortress may place DF in +another folder, so ensure that the ``hack`` folder ends up next to the ``data`` +folder. + +.. note:: + + On Windows, installing DFHack will overwrite ``SDL.dll``. This is + intentional and necessary for DFHack to work, so be sure to choose to + overwrite ``SDL.dll`` if prompted. (If you are not prompted, you may be + installing DFHack in the wrong place.) + + +Uninstalling DFHack +=================== + +Uninstalling DFHack essentially involves reversing what you did to install +DFHack. On Windows, replace ``SDL.dll`` with ``SDLreal.dll`` first. Then, you +can remove any files that were part of the DFHack archive. DFHack does not +currently maintain a list of these files, so if you want to completely remove +them, you should consult the DFHack archive that you installed for a full list. +Generally, any files left behind should not negatively affect DF. + +Pre-packaged DFHack installations +================================= + +There are :wiki:`several packs available ` that include +DF, DFHack, and other utilities. If you are new to Dwarf Fortress and DFHack, +these may be easier to set up. Note that these packs are not maintained by the +DFHack team and vary in their release schedules and contents. Some may make +significant configuration changes, and some may not include DFHack at all. diff --git a/docs/Introduction.rst b/docs/Introduction.rst index 4490086f3..7d510422f 100644 --- a/docs/Introduction.rst +++ b/docs/Introduction.rst @@ -35,47 +35,19 @@ allows easier development of new tools. As an open-source project under :local: -.. _installing: - -Installing DFHack -================= -DFHack is available for the SDL version of Dwarf Fortress on Windows, -any modern Linux distribution, and Mac OS X (10.6.8 and later). -It is possible to use Windows DF+DFHack under Wine on Linux or OS X. - -Most releases only support the version of DF mentioned in their title - for -example, DFHack 0.40.24-r2 only supports DF 0.40.24 - but some releases -support earlier DF versions as well. Wherever possible, use the latest version -of DFHack built for the target version of DF. - -Installing DFhack involves copying files from a release archive -into your DF folder, so that: - -* On Windows, ``SDL.dll`` is replaced -* On Linux or OS X, the ``dfhack`` script is placed in the same folder as the ``df`` script - -Uninstalling is basically the same, in reverse: - -* On Windows, replace ``SDL.dll`` with ``SDLreal.dll``, then remove the DFHack files. -* On Linux or OS X, remove the DFHack files. - -New players may wish to :wiki:`get a pack ` -with DFHack preinstalled. - - Getting started =============== -DFHack basically extends DF with something similar to the -console found in many PC games. +See `installing` for details on installing DFHack. -If DFHack is installed correctly, it will automatically pop up a console -window once DF is started as usual on Windows. Linux and Mac OS X require -running the dfhack script from the terminal, and will use that terminal for -the console. +Once DFHack is installed, it extends DF with a console that can be used to run +commands. On Windows, this console will open automatically when DF is started. +On Linux and macOS, you will need to run the ``dfhack`` script from a terminal +(instead of the ``df`` script included with DF), and that terminal will be +used by the DFHack console. -* Basic interaction with dfhack involves entering commands into the console. - To learn what commands are available, you can keep reading this documentation - or skip ahead and use the `ls` and `help` commands. +* Basic interaction with DFHack involves entering commands into the console. To + learn what commands are available, you can keep reading this documentation or + skip ahead and use the `ls` and `help` commands. * Another way to interact with DFHack is to set in-game `keybindings ` for certain commands. Many of the newer and user-friendly tools are designed diff --git a/index.rst b/index.rst index 91c883b51..d0e90b741 100644 --- a/index.rst +++ b/index.rst @@ -27,6 +27,7 @@ User Manual :maxdepth: 2 /docs/Introduction + /docs/Installing /docs/Core /docs/Plugins /docs/Scripts