Merge remote-tracking branch 'upstream/develop' into quickfort_skeleton
Myk Taylor
commit
ca1742243b
@ -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.
|
||||
@ -0,0 +1,233 @@
|
||||
.. _remote:
|
||||
|
||||
=======================
|
||||
DFHack Remote Interface
|
||||
=======================
|
||||
|
||||
DFHack provides a remote access interface that external tools can connect to and
|
||||
use to interact with DF. This is implemented with `Google protobuf`_ messages
|
||||
exchanged over a TCP socket. Both the core and plugins can define
|
||||
remotely-accessible methods, or **RPC methods**. The RPC methods currently
|
||||
available are not comprehensive, but can be extended with plugins.
|
||||
|
||||
.. _Google protobuf: https://developers.google.com/protocol-buffers
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
|
||||
.. _remote-server-config:
|
||||
|
||||
Server configuration
|
||||
====================
|
||||
|
||||
DFHack attempts to start a TCP server to listen for remote connections on
|
||||
startup. If this fails (due to the port being in use, for example), an error
|
||||
message will be logged to stderr.log.
|
||||
|
||||
The server can be configured by setting options in ``dfhack-config/remote-server.json``:
|
||||
|
||||
- ``allow_remote`` (default: ``false``): if true, allows connections from hosts
|
||||
other than the local machine. This is insecure and may allow arbitrary code
|
||||
execution on your machine, so it is disabled by default.
|
||||
- ``port`` (default: ``5000``): the port that the remote server listens on.
|
||||
Overriding this will allow the server to work if you have multiple instances
|
||||
of DF running, or if you have something else running on port 5000. Note that
|
||||
the ``DFHACK_PORT`` `environment variable <env-vars>` takes precedence over
|
||||
this setting and may be more useful for overriding the port temporarily.
|
||||
|
||||
|
||||
Developing with the remote API
|
||||
==============================
|
||||
|
||||
At a high level, the core and plugins define RPC methods, and external clients
|
||||
can call these methods. Each method is assigned an ID internally, which clients
|
||||
use to call it. These method IDs can be obtained using the special ``BindMethod``
|
||||
method, which has an ID of 0.
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
The `dfhack-run` command uses the RPC interface to invoke DFHack commands
|
||||
(or Lua functions) externally.
|
||||
|
||||
Plugins that implement RPC methods include:
|
||||
|
||||
- `rename`
|
||||
- `remotefortressreader`
|
||||
- `isoworldremote`
|
||||
|
||||
Plugins that use the RPC API include:
|
||||
|
||||
- `stonesense`
|
||||
|
||||
Third-party tools that use the RPC API include:
|
||||
|
||||
- `Armok Vision <https://github.com/RosaryMala/armok-vision>`_ (:forums:`Bay12 forums thread <146473>`)
|
||||
|
||||
Client libraries
|
||||
----------------
|
||||
|
||||
Some external libraries are available for interacting with the remote interface
|
||||
from other (non-C++) languages, including:
|
||||
|
||||
- `RemoteClientDF-Net <https://github.com/RosaryMala/RemoteClientDF-Net>`_ for C#
|
||||
- `dfhackrpc <https://github.com/BenLubar/dfhackrpc>`_ for Go
|
||||
- `dfhack-remote <https://github.com/alexchandel/dfhack-remote>`_ for JavaScript
|
||||
|
||||
|
||||
Protocol description
|
||||
====================
|
||||
|
||||
This is a low-level description of the RPC protocol, which may be useful when
|
||||
developing custom clients.
|
||||
|
||||
A WireShark dissector for this protocol is available in the
|
||||
`df_misc repo <https://github.com/DFHack/df_misc/blob/master/wireshark_dfhack_rpc.lua>`_.
|
||||
|
||||
|
||||
Built-in messages
|
||||
-----------------
|
||||
These messages have hardcoded IDs; all others must be obtained through ``BindMethod``.
|
||||
|
||||
=== ============ =============================== =======================
|
||||
ID Method Input Output
|
||||
=== ============ =============================== =======================
|
||||
0 BindMethod dfproto.CoreBindRequest dfproto.CoreBindReply
|
||||
1 RunCommand dfproto.CoreRunCommandRequest dfproto.EmptyMessage
|
||||
=== ============ =============================== =======================
|
||||
|
||||
|
||||
|
||||
Conversation flow
|
||||
-----------------
|
||||
|
||||
* Client → Server: `handshake request`_
|
||||
* Server → Client: `handshake reply`_
|
||||
* Repeated 0 or more times:
|
||||
* Client → Server: `request`_
|
||||
* Server → Client: `text`_ (0 or more times)
|
||||
* Server → Client: `result`_ or `failure`_
|
||||
* Client → Server: `quit`_
|
||||
|
||||
Raw message types
|
||||
-----------------
|
||||
|
||||
* All numbers are little-endian
|
||||
* All strings are ASCII
|
||||
* A payload size of greater than 64MiB is an error
|
||||
* See ``RemoteClient.h`` for definitions of constants starting with ``RPC``
|
||||
|
||||
handshake request
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. csv-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
|
||||
Type, Name, Value
|
||||
char[8], magic, ``DFHack?\n``
|
||||
int32_t, version, 1
|
||||
|
||||
handshake reply
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. csv-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
|
||||
Type, Name, Value
|
||||
char[8], magic, ``DFHack!\n``
|
||||
int32_t, version, 1
|
||||
|
||||
header
|
||||
~~~~~~
|
||||
|
||||
**Note:** the two fields of this message are sometimes repurposed. Uses of this
|
||||
message are represented as ``header(x, y)``, where ``x`` corresponds to the ``id``
|
||||
field and ``y`` corresponds to ``size``.
|
||||
|
||||
.. csv-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
|
||||
Type, Name
|
||||
int16_t, id
|
||||
int16_t, (padding - unused)
|
||||
int32_t, size
|
||||
|
||||
request
|
||||
~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
:widths: 25 75
|
||||
|
||||
* - Type
|
||||
- Description
|
||||
* - `header`_
|
||||
- ``header(id, size)``
|
||||
* - buffer
|
||||
- Protobuf-encoded payload of the input message type of the method specified by ``id``; length of ``size`` bytes
|
||||
|
||||
text
|
||||
~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
:widths: 25 75
|
||||
|
||||
* - Type
|
||||
- Description
|
||||
* - `header`_
|
||||
- ``header(RPC_REPLY_TEXT, size)``
|
||||
* - buffer
|
||||
- Protobuf-encoded payload of type ``dfproto.CoreTextNotification``; length of ``size`` bytes
|
||||
|
||||
result
|
||||
~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
:widths: 25 75
|
||||
|
||||
* - Type
|
||||
- Description
|
||||
* - `header`_
|
||||
- ``header(RPC_REPLY_RESULT, size)``
|
||||
* - buffer
|
||||
- Protobuf-encoded payload of the output message type of the oldest incomplete method call; when received,
|
||||
that method call is considered completed. Length of ``size`` bytes.
|
||||
|
||||
failure
|
||||
~~~~~~~
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
:widths: 25 75
|
||||
|
||||
* - Type
|
||||
- Description
|
||||
* - `header`_
|
||||
- ``header(RPC_REPLY_FAIL, command_result)``
|
||||
* - command_result
|
||||
- return code of the command (a constant starting with ``CR_``; see ``RemoteClient.h``)
|
||||
|
||||
quit
|
||||
~~~~
|
||||
|
||||
**Note:** the server closes the connection after receiving this message.
|
||||
|
||||
.. list-table::
|
||||
:align: left
|
||||
:header-rows: 1
|
||||
:widths: 25 75
|
||||
|
||||
* - Type
|
||||
- Description
|
||||
* - `header`_
|
||||
- ``header(RPC_REQUEST_QUIT, 0)``
|
||||
@ -1 +1 @@
|
||||
Subproject commit bdab71c99a0a7cc268ca517a0cd3f0a5fb41042a
|
||||
Subproject commit 87e6cf02b914daf6f7811d967db6fadc7ca115fe
|
||||
@ -1 +1 @@
|
||||
Subproject commit af749e7086739a058cd5095a6ee1a60d7e795a7c
|
||||
Subproject commit a5e385bb2a3c72f878be614cb0cc004aafa17f79
|
||||
Loading…
Reference in New Issue