From 2302698b2251d5b47b9b3400e47376229b0f6426 Mon Sep 17 00:00:00 2001 From: PeridexisErrant Date: Fri, 25 Sep 2015 23:33:28 +1000 Subject: [PATCH] Consolidate binpatch docs. Closes #546 Binpatches aren't used much at the moment, so this has two purposes: collate information so it's easier to write them again, and remove it from other sections where it's useless. Note that if the standalone binpatch.exe is removed, the 'patching on disk' section can be cleanly removed from 'Using a patch' by deleting lines 44-47 & 61-90. --- README.rst | 1 + docs/Binpatches.rst | 179 ++++++++++++++++++++++++++++++++++++++++++ docs/Contributing.rst | 2 + docs/Core.rst | 28 ------- docs/Plugins.rst | 52 +----------- docs/Scripts.rst | 37 ++------- 6 files changed, 189 insertions(+), 110 deletions(-) create mode 100644 docs/Binpatches.rst diff --git a/README.rst b/README.rst index b75320a98..97ac6b36e 100644 --- a/README.rst +++ b/README.rst @@ -56,3 +56,4 @@ For Developers: docs/Compile docs/Lua API library/xml/SYNTAX + docs/Binpatches diff --git a/docs/Binpatches.rst b/docs/Binpatches.rst new file mode 100644 index 000000000..994957b1b --- /dev/null +++ b/docs/Binpatches.rst @@ -0,0 +1,179 @@ +.. _binpatches: + +###################### +Patching the DF binary +###################### + +Writing scripts and plugins for DFHack is not the only way to modify Dwarf +Fortress. Before DFHack, it was common for tools to manually patch the +binary to change behaviour, and DFHack still contains tools to do this via +the `scripts/binpatch` command. + +.. warning:: + + We recommend using a script or plugin instead of a raw patch if + at all possible - that way your work will work for many versions + across multiple operating systems. There's a reason nobody has + written patches since ``0.34.11``! + +.. contents:: + + +Getting a patch +=============== +There are no binary patches available for Dwarf Fortress versions after 0.34.11 + +This system is kept for the chance that someone will find it useful, so some +hints on how to write your own follow. This will require disassembly and +decent skill in `memory research `. + +* The patches are expected to be encoded in text format used by IDA. + +* See `this commit `_, + when the 0.34.11 patches were discarded, for example patches. + +* `Issue #546 `_ is about the + future of the binpatches, and may be useful reading. + +If you want to write a patch, the armory patches discussed here and documented +below would probably be the best place to start. + + +Using a patch +============= +There are two methods to apply a patch. + +Patching at runtime +------------------- +The `scripts/binpatch` script checks, applies or removes binary patches +directly in memory at runtime:: + + binpatch [check|apply|remove] + +If the name of the patch has no extension or directory separators, the +script uses ``hack/patches//.dif``, thus auto-selecting +the version appropriate for the currently loaded executable. + +This is the preferred method; it's easier to debug, does not cause persistent +problems, and leaves file checksums alone. + + +Patching on disk +---------------- + +.. warning:: + + This method of patching is deprecated, and may be removed without notice. + You should use the runtime patching option above. + +DFHack includes a small stand-alone utility for applying and removing +binary patches from the game executable. Use it from the regular operating +system console: + +``binpatch check "Dwarf Fortress.exe" patch.dif`` + Checks and prints if the patch is currently applied. + +``binpatch apply "Dwarf Fortress.exe" patch.dif`` + Applies the patch, unless it is already applied or in conflict. + +``binpatch remove "Dwarf Fortress.exe" patch.dif`` + Removes the patch, unless it is already removed. + +If you use a permanent patch under OSX or Linux, you must update +``symbols.xml`` with the new checksum of the executable. Find the relevant +section, and add a new line:: + + + +In order to find the correct value of the hash, look into stderr.log; +DFHack prints an error there if it does not recognize the hash. + +.. _binpatches/needs-patch: + +Tools reliant on binpatches +=========================== +Some DFHack tools require the game to be patched to work. As no patches +are currently available, the full description of each is included here. + +fix-armory +---------- +Enables a fix for storage of squad equipment in barracks. + +Specifically, it prevents your haulers from moving squad equipment +to stockpiles, and instead queues jobs to store it on weapon racks, +armor stands, and in containers. + +.. note:: + + In order to actually be used, weapon racks have to be patched and + manually assigned to a squad. See `scripts/gui/assign-rack`. + +Note that the buildings in the armory are used as follows: + +* Weapon racks (when patched) are used to store any assigned weapons. + Each rack belongs to a specific squad, and can store up to 5 weapons. + +* Armor stands belong to specific squad members and are used for + armor and shields. + +* Cabinets are used to store assigned clothing for a specific squad member. + They are **never** used to store owned clothing. + +* Chests (boxes, etc) are used for a flask, backpack or quiver assigned + to the squad member. Due to a probable bug, food is dropped out of the + backpack when it is stored. + +.. warning:: + + Although armor stands, cabinets and chests properly belong only to one + squad member, the owner of the building used to create the barracks will + randomly use any containers inside the room. Thus, it is recommended to + always create the armory from a weapon rack. + +Contrary to the common misconception, all these uses are controlled by the +*Individual Equipment* usage flag. The *Squad Equipment* flag is actually +intended for ammo, but the game does even less in that area than for armor +and weapons. This plugin implements the following rules almost from scratch: + +* Combat ammo is stored in chests inside rooms with Squad Equipment enabled. + +* If a chest is assigned to a squad member due to Individual Equipment also + being set, it is only used for that squad's ammo; otherwise, any squads + with Squad Equipment on the room will use all of the chests at random. + +* Training ammo is stored in chests inside archery ranges designated from + archery targets, and controlled by the same Train flag as archery training + itself. This is inspired by some defunct code for weapon racks. + +There are some minor traces in the game code to suggest that the first of +these rules is intended by Toady; the rest are invented by this plugin. + + +gui/assign-rack +--------------- +Bind to a key (the example config uses P), and activate when viewing a weapon +rack in the ``q`` mode. + +.. image:: images/assign-rack.png + +This script is part of a group of related fixes to make the armory storage +work again. The existing issues are: + +* Weapon racks have to each be assigned to a specific squad, like with + beds/boxes/armor stands and individual squad members, but nothing in + the game does this. This issue is what this script addresses. + +* Even if assigned by the script, **the game will unassign the racks again + without a binary patch**. This patch is called ``weaponrack-unassign``, + and has not been updated since 0.34.11. See `the bug report`_ for more info. + +.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 + +* Haulers still take equipment stored in the armory away to the stockpiles, + unless `plugins/fix-armory` is used. + +The script interface simply lets you designate one of the squads that +are assigned to the barracks/armory containing the selected stand as +the intended user. In order to aid in the choice, it shows the number +of currently assigned racks for every valid squad. + diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 3c7f99ec1..6599f680c 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -101,6 +101,8 @@ How to get new code into DFHack * Work done against Github issues tagged "bug report" get priority * Submit ideas and bug reports as issues on Github. Posts in the forum thread can easily get missed or forgotten. +.. _contributing-memory-research: + Memory research --------------- If you want to do memory research, you'll need some tools and some knowledge. diff --git a/docs/Core.rst b/docs/Core.rst index 91d2fdb96..4e2080311 100644 --- a/docs/Core.rst +++ b/docs/Core.rst @@ -304,31 +304,3 @@ nopause Disables pausing (both manual and automatic) with the exception of pause forced by 'reveal hell'. This is nice for digging under rivers. -Patched binaries -================ -As an alternative to permanently modifying the binary, you can use the -``binpatch`` dfhack command to apply patches live in memory during a DF session. - -In this case, updating symbols.xml is not necessary - otherwise Linux and OSX -users of patched binaries may have to find the relevant section in ``symbols.xml``, -and add a new line with the checksum of their executable:: - - - -In order to find the correct value of the hash, look into stderr.log; -DFHack prints an error there if it does not recognize the hash. - -DFHack includes a small stand-alone utility for applying and removing -binary patches from the game executable. Use it from the regular operating -system console: - -``binpatch check "Dwarf Fortress.exe" patch.dif`` - Checks and prints if the patch is currently applied. - -``binpatch apply "Dwarf Fortress.exe" patch.dif`` - Applies the patch, unless it is already applied or in conflict. - -``binpatch remove "Dwarf Fortress.exe" patch.dif`` - Removes the patch, unless it is already removed. - -The patches are expected to be encoded in text format used by IDA. diff --git a/docs/Plugins.rst b/docs/Plugins.rst index 5cb16dfd3..656df680d 100644 --- a/docs/Plugins.rst +++ b/docs/Plugins.rst @@ -332,56 +332,8 @@ Subcommands that persist until disabled or DF quits: fix-armory ========== -Enables a fix for storage of squad equipment in barracks. - -Specifically, it prevents your haulers from moving squad equipment -to stockpiles, and instead queues jobs to store it on weapon racks, -armor stands, and in containers. - -.. note:: - - In order to actually be used, weapon racks have to be patched and - manually assigned to a squad. See `scripts/gui/assign-rack`. - -Note that the buildings in the armory are used as follows: - -* Weapon racks (when patched) are used to store any assigned weapons. - Each rack belongs to a specific squad, and can store up to 5 weapons. - -* Armor stands belong to specific squad members and are used for - armor and shields. - -* Cabinets are used to store assigned clothing for a specific squad member. - They are **never** used to store owned clothing. - -* Chests (boxes, etc) are used for a flask, backpack or quiver assigned - to the squad member. Due to a probable bug, food is dropped out of the - backpack when it is stored. - -.. warning:: - - Although armor stands, cabinets and chests properly belong only to one - squad member, the owner of the building used to create the barracks will - randomly use any containers inside the room. Thus, it is recommended to - always create the armory from a weapon rack. - -Contrary to the common misconception, all these uses are controlled by the -*Individual Equipment* usage flag. The *Squad Equipment* flag is actually -intended for ammo, but the game does even less in that area than for armor -and weapons. This plugin implements the following rules almost from scratch: - -* Combat ammo is stored in chests inside rooms with Squad Equipment enabled. - -* If a chest is assigned to a squad member due to Individual Equipment also - being set, it is only used for that squad's ammo; otherwise, any squads - with Squad Equipment on the room will use all of the chests at random. - -* Training ammo is stored in chests inside archery ranges designated from - archery targets, and controlled by the same Train flag as archery training - itself. This is inspired by some defunct code for weapon racks. - -There are some minor traces in the game code to suggest that the first of -these rules is intended by Toady; the rest are invented by this plugin. +`This plugin requires a binpatch `, which has not +been available since DF 0.34.11 =========== diff --git a/docs/Scripts.rst b/docs/Scripts.rst index e7203694c..d28914c47 100644 --- a/docs/Scripts.rst +++ b/docs/Scripts.rst @@ -143,31 +143,8 @@ Does something with items in adventure mode jobs. gui/assign-rack =============== -Bind to a key (the example config uses P), and activate when viewing a weapon -rack in the 'q' mode. - -.. image:: images/assign-rack.png - -This script is part of a group of related fixes to make the armory storage -work again. The existing issues are: - -* Weapon racks have to each be assigned to a specific squad, like with - beds/boxes/armor stands and individual squad members, but nothing in - the game does this. This issue is what this script addresses. - -* Even if assigned by the script, **the game will unassign the racks again without a binary patch**. - This patch is called ``weaponrack-unassign``, and can be applied via - the binpatch program, or the matching script. See `the bug report`_ for more info. - -.. _`the bug report`: http://www.bay12games.com/dwarves/mantisbt/view.php?id=1445 - -* Haulers still take equipment stored in the armory away to the stockpiles, - unless `plugins/fix-armory` is used. - -The script interface simply lets you designate one of the squads that -are assigned to the barracks/armory containing the selected stand as -the intended user. In order to aid in the choice, it shows the number -of currently assigned racks for every valid squad. +`This script requires a binpatch `, which has not +been available since DF 0.34.11 gui/autobutcher =============== @@ -681,15 +658,11 @@ A more convenient way to ban cooking various categories of foods than the kitchen interface. Usage: ``ban-cooking ``. Valid types are ``booze``, ``honey``, ``tallow``, ``oil``, and ``seeds`` (non-tree plants with seeds). +.. _scripts/binpatch: + binpatch ======== -Checks, applies or removes binary patches directly in memory at runtime:: - - binpatch check/apply/remove - -If the name of the patch has no extension or directory separators, the -script uses ``hack/patches//.dif``, thus auto-selecting -the version appropriate for the currently loaded executable. +Implements functions for in-memory binpatches. See `binpatches`. .. _scripts/brainwash: