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

update Installing docs for Steam

develop
Myk Taylor 2023-04-10 18:29:41 -07:00
parent 2344a30196
commit c0fe5776fb
No known key found for this signature in database
2 changed files with 58 additions and 106 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

163
docs/Installing.rst
Unescape Escape View File

@ -7,78 +7,50 @@ Installing DFHack
.. contents:: .. contents::
:local: :local:
Requirements Requirements
============ ============
DFHack supports Windows, Linux, and macOS, and both 64-bit and 32-bit builds DFHack supports all operating systems and platforms that Dwarf Fortress itself
of Dwarf Fortress. supports, which at the moment is just 64-bit Windows. However, the Windows
build of DFHack works well under ``wine`` (or ``Proton``, Steam's fork of
``wine``) on other operating systems.
.. _installing-df-version: .. _installing-df-version:
DFHack releases generally only support the version of Dwarf Fortress that they 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. are named after. For example, DFHack 50.05 only supported DF 50.05. DFHack
DFHack releases *never* support newer versions of DF, because DFHack requires releases *never* support newer versions of DF -- DFHack requires data about DF
data about DF that is only possible to obtain after DF has been released. that is only possible to obtain after DF has been released. Occasionally,
Occasionally, DFHack releases will be able to maintain support for older DFHack releases will be able to maintain support for older versions of DF - for
versions of DF - for example, DFHack 0.34.11-r5 supported both DF 0.34.11 and example, DFHack 0.34.11-r5 supported both DF 0.34.11 and 0.34.10. For maximum
0.34.10. For maximum stability, you should usually use the latest versions of stability, you should usually use the latest versions of both DF and DFHack.
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 <building-dfhack-index>`.
macOS
-----
OS X 10.6.8 or later is required.
.. _downloading: .. _downloading:
Downloading DFHack Downloading DFHack
================== ==================
Stable builds of DFHack are available on `GitHub <https://github.com/dfhack/dfhack/releases>`_. Stable builds of DFHack are available on
GitHub has been known to change their layout periodically, but as of July 2020, `Steam <https://store.steampowered.com/app/2346660/DFHack__Dwarf_Fortress_Modding_Engine/>`__
downloads are available at the bottom of the release notes for each release, under a section or from our `GitHub <https://github.com/dfhack/dfhack/releases>`__. Either
named "Assets" (which you may have to expand). The name of the file indicates location will give you exactly the same package.
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 On Steam, note that DFHack is a separate app, not a DF Steam Workshop mod. You
version should also match your DF version - see `above <installing-df-version>` can run DF with DFHack by launching either the DFHack app or the original Dwarf
for details. For example: Fortress app.
If you download from GitHub, 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-50.07-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 In between stable releases, we may create beta releases to test new features.
unstable builds. These files have a different naming scheme, but the same These are available via the beta release channel on Steam or from our regular
restrictions apply (e.g. a file named ``Windows64`` is for 64-bit Windows DF). Github page as a pre-release tagged with a "beta" suffix.
.. warning:: .. warning::
@ -91,19 +63,22 @@ restrictions apply (e.g. a file named ``Windows64`` is for 64-bit Windows DF).
Installing DFHack Installing DFHack
================= =================
If you are installing from Steam, this is handled for you automatically. The
instructions here are for manual installs.
When you `download DFHack <downloading>`, you will end up with a release archive 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 (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 operating system should have built-in utilities capable of extracting files from
these archives. these archives.
The release archives contain several folders, including a ``hack`` folder where The release archives contain a ``hack`` folder where DFHack binary and system
DFHack binary and system data is stored, a ``dfhack-config`` folder where user data is stored, a ``stonesense`` folder that contains data specific to the
data and configuration is stored, and a ``blueprints`` folder where `quickfort` `stonesense` 3d renderer, and various libraries and executable files. To
blueprints are stored. To install DFHack, copy all of the files from the DFHack install DFHack, copy all of the files from the DFHack archive into the root DF
archive into the root DF folder, which should already include a ``data`` folder folder, which should already include a ``data`` folder and a ``mods`` folder,
and a ``raw`` folder, among other things. Some packs and other redistributions among other things. Some redistributions of Dwarf Fortress may place DF in
of Dwarf Fortress may place DF in another folder, so ensure that the ``hack`` another folder, so ensure that the ``hack`` folder ends up next to the ``data``
folder ends up next to the ``data`` folder. folder, and you'll be fine.
.. note:: .. note::
@ -112,58 +87,34 @@ folder ends up next to the ``data`` folder.
overwrite ``SDL.dll`` if prompted. (If you are not prompted, you may be overwrite ``SDL.dll`` if prompted. (If you are not prompted, you may be
installing DFHack in the wrong place.) installing DFHack in the wrong place.)
Uninstalling DFHack Uninstalling DFHack
=================== ===================
Uninstalling DFHack essentially involves reversing what you did to install Manually uninstalling DFHack essentially involves reversing what you did to
DFHack. On Windows, replace ``SDL.dll`` with ``SDLreal.dll`` first. Then, you install. 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 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 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. them, you should consult the DFHack archive that you installed for a full list.
Generally, any files left behind should not negatively affect DF. Generally, any files left behind should not negatively affect DF.
On Steam, uninstalling DFHack will cleanly remove everything that was installed
with DFHack, **including** the ``SDL.dll`` file, which will render Dwarf
Fortress inoperative. In your Steam client, open the properties window for
Dwarf Fortress, select "Local Files", and click on "Verify integrity of game
files...". This will get Dwarf Fortress working properly again.
Note that Steam will leave behind the ``dfhack-config`` folder, which contains
all your personal DFHack-related settings and data. If you keep this folder,
all your settings will be restored when you reinstall DFHack later.
Upgrading DFHack Upgrading DFHack
================ ================
The recommended approach to upgrade DFHack is to uninstall DFHack first, then Again, if you have installed from Steam, your copy of DFHack will automatically be kept up to date. This section is for manual installers.
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.
Linux packages
==============
Third-party DFHack packages are available for some Linux distributions,
including in:
* `AUR <https://aur.archlinux.org/packages/dfhack/>`__, for Arch and related First, remove the ``hack`` and ``stonesense`` folders in their entirety. This
distributions ensures that files that don't exist in the latest version are properly removed
* `RPM Fusion <https://admin.rpmfusion.org/pkgdb/package/nonfree/dfhack/>`__, and don't affect your new installation.
for Fedora and related distributions
Note that these may lag behind DFHack releases. If you want to use a newer Then, extract the DFHack release archive into your Dwarf Fortress folder,
version of DFHack, we generally recommended installing it in a clean copy of DF overwriting any remaining top-level files (including SDL.dll).
in your home folder. Attempting to upgrade an installation of DFHack from a
package manager may break it.

1
docs/changelog.txt
Unescape Escape View File

@ -55,6 +55,7 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
- Core: hide DFHack terminal console by default when running on Steam Deck - Core: hide DFHack terminal console by default when running on Steam Deck
## Documentation ## Documentation
- `installing`: updated to include Steam installation instructions
## API ## API