Merge remote-tracking branch 'lethosor/docs-install' into develop

Closes #1568
develop
lethosor 2020-07-18 12:39:02 -04:00
commit 5fad916bd7
No known key found for this signature in database
GPG Key ID: 76A269552F4F58C1
3 changed files with 162 additions and 37 deletions

@ -0,0 +1,152 @@
.. _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 <https://stackoverflow.com/questions/32452777/visual-c-2015-express-stat-not-working-on-windows-xp>`_
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 <compile>`.
macOS
-----
OS X 10.6.8 or later is required.
.. _downloading:
Downloading DFHack
==================
Stable builds of DFHack are available on `GitHub <https://github.com/dfhack/dfhack/releases>`_.
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 <installing-df-version>`
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 <https://dfhack.org/builds>`_ 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 <downloading>`, 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. To
install DFHack, copy all of the files from the DFHack archive 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.
Upgrading DFHack
================
The recommended approach to upgrade DFHack is to uninstall DFHack first, then
install the new version. This will ensure that any files that are only part
of the older DFHack installation do not affect the new DFHack installation
(although this is unlikely to occur).
It is also possible to overwrite an existing DFHack installation in-place.
To do this, follow the installation instructions above, but overwrite all files
that exist in the new DFHack archive (on Windows, this includes ``SDL.dll`` again).
.. note::
You may wish to make a backup of your ``dfhack-config`` folder first if you
have made changes to it. Some archive managers (e.g. Archive Utility on macOS)
will overwrite the entire folder, removing any files that you have added.
Pre-packaged DFHack installations
=================================
There are :wiki:`several packs available <Utility:Lazy_Newb_Pack>` 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.

@ -35,47 +35,19 @@ allows easier development of new tools. As an open-source project under
:local: :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 <Utility:Lazy_Newb_Pack>`
with DFHack preinstalled.
Getting started Getting started
=============== ===============
DFHack basically extends DF with something similar to the See `installing` for details on installing DFHack.
console found in many PC games.
If DFHack is installed correctly, it will automatically pop up a console Once DFHack is installed, it extends DF with a console that can be used to run
window once DF is started as usual on Windows. Linux and Mac OS X require commands. On Windows, this console will open automatically when DF is started.
running the dfhack script from the terminal, and will use that terminal for On Linux and macOS, you will need to run the ``dfhack`` script from a terminal
the console. (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. * Basic interaction with DFHack involves entering commands into the console. To
To learn what commands are available, you can keep reading this documentation learn what commands are available, you can keep reading this documentation or
or skip ahead and use the `ls` and `help` commands. skip ahead and use the `ls` and `help` commands.
* Another way to interact with DFHack is to set in-game `keybindings <keybinding>` * Another way to interact with DFHack is to set in-game `keybindings <keybinding>`
for certain commands. Many of the newer and user-friendly tools are designed for certain commands. Many of the newer and user-friendly tools are designed

@ -27,6 +27,7 @@ User Manual
:maxdepth: 2 :maxdepth: 2
/docs/Introduction /docs/Introduction
/docs/Installing
/docs/Core /docs/Core
/docs/Plugins /docs/Plugins
/docs/Scripts /docs/Scripts