From c0fe5776fb760d3cdfc3b8966ffde2e5416455dd Mon Sep 17 00:00:00 2001 From: Myk Taylor Date: Mon, 10 Apr 2023 18:29:41 -0700 Subject: [PATCH] update Installing docs for Steam --- docs/Installing.rst | 163 ++++++++++++++++---------------------------- docs/changelog.txt | 1 + 2 files changed, 58 insertions(+), 106 deletions(-) diff --git a/docs/Installing.rst b/docs/Installing.rst index bc58a39b7..a80133e88 100644 --- a/docs/Installing.rst +++ b/docs/Installing.rst @@ -7,78 +7,50 @@ Installing DFHack .. contents:: :local: - Requirements ============ -DFHack supports Windows, Linux, and macOS, and both 64-bit and 32-bit builds -of Dwarf Fortress. +DFHack supports all operating systems and platforms that Dwarf Fortress itself +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: 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. - +are named after. For example, DFHack 50.05 only supported DF 50.05. DFHack +releases *never* support newer versions of DF -- 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. .. _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: +Stable builds of DFHack are available on +`Steam `__ +or from our `GitHub `__. Either +location will give you exactly the same package. + +On Steam, note that DFHack is a separate app, not a DF Steam Workshop mod. You +can run DF with DFHack by launching either the DFHack app or the original Dwarf +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 ` 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) +* ``dfhack-50.07-r1-Windows-64bit.zip`` supports 64-bit DF on Windows -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). +In between stable releases, we may create beta releases to test new features. +These are available via the beta release channel on Steam or from our regular +Github page as a pre-release tagged with a "beta" suffix. .. warning:: @@ -91,19 +63,22 @@ restrictions apply (e.g. a file named ``Windows64`` is for 64-bit Windows DF). 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 `, 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 folders, including a ``hack`` folder where -DFHack binary and system data is stored, a ``dfhack-config`` folder where user -data and configuration is stored, and a ``blueprints`` folder where `quickfort` -blueprints are stored. 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. +The release archives contain a ``hack`` folder where DFHack binary and system +data is stored, a ``stonesense`` folder that contains data specific to the +`stonesense` 3d renderer, and various libraries and executable files. 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 ``mods`` folder, +among other things. Some redistributions of Dwarf Fortress may place DF in +another folder, so ensure that the ``hack`` folder ends up next to the ``data`` +folder, and you'll be fine. .. 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 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 +Manually uninstalling DFHack essentially involves reversing what you did to +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 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. +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 ================ -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 ` 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: +Again, if you have installed from Steam, your copy of DFHack will automatically be kept up to date. This section is for manual installers. -* `AUR `__, for Arch and related - distributions -* `RPM Fusion `__, - for Fedora and related distributions +First, remove the ``hack`` and ``stonesense`` folders in their entirety. This +ensures that files that don't exist in the latest version are properly removed +and don't affect your new installation. -Note that these may lag behind DFHack releases. If you want to use a newer -version of DFHack, we generally recommended installing it in a clean copy of DF -in your home folder. Attempting to upgrade an installation of DFHack from a -package manager may break it. +Then, extract the DFHack release archive into your Dwarf Fortress folder, +overwriting any remaining top-level files (including SDL.dll). diff --git a/docs/changelog.txt b/docs/changelog.txt index e63b80bd7..8beb3dc6e 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -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 ## Documentation +- `installing`: updated to include Steam installation instructions ## API