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

minor liquids bugfix, added typedef for planecoord so that stonesense builds. Build system bits. Doxygen bits.

develop
Petr Mrázek 2011-03-13 19:38:32 +01:00
parent b6d02768b4
commit cb86f52993
15 changed files with 438 additions and 301 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
CMakeLists.txt
Unescape Escape View File

@ -25,6 +25,7 @@ ENDIF(NOT DEFINED CMAKE_BUILD_TYPE)
SET( LIBRARY_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack library" ) SET( LIBRARY_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack library" )
SET( EXECUTABLE_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack tools" ) SET( EXECUTABLE_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack tools" )
SET( DATA_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack data (offset files)" ) SET( DATA_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack data (offset files)" )
SET( DOXYGEN_OUTPUT_DIR ${CMAKE_SOURCE_DIR}/output/doxygen CACHE PATH "Output directory for doxygen")
OPTION(BUILD_DFHACK_DOCUMENTATION "Create doxygen documentation for developers" OFF) OPTION(BUILD_DFHACK_DOCUMENTATION "Create doxygen documentation for developers" OFF)
OPTION(BUILD_DFHACK_EXAMPLES "Build example tools" OFF) OPTION(BUILD_DFHACK_EXAMPLES "Build example tools" OFF)

131
COMPILE.rst
Unescape Escape View File

@ -26,6 +26,16 @@ is simple. Enter the build folder, run the tools. Like this::
make make
This will build the library and its tools and place them in ``/output``. This will build the library and its tools and place them in ``/output``.
Alternatively, you can use ccmake instead of cmake:
cd build
ccmake ..
make
This will show a curses-based interface that lets you set all of the
extra options.
You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI
program. program.
@ -133,3 +143,124 @@ Valid an useful build types include 'Release', 'Debug' and
'RelWithDebInfo'. There are others, but they aren't really that useful. 'RelWithDebInfo'. There are others, but they aren't really that useful.
Have fun. Have fun.
================================
Using the library as a developer
================================
DFHack is using the zlib/libpng license. This makes it easy to link to
it, use it in-source or add your own extensions. Contributing back to
the dfhack repository is welcome and the right thing to do :)
Rudimentary API documentation can be built using doxygen.
Contributing to DFHack
======================
Several things should be kept in mind when contributing to DFHack.
------------
Coding style
------------
DFhack uses ANSI formatting and four spaces as indentation. Line
endings are UNIX. The files use UTF-8 encoding. Code not following this
won't make me happy, because I'll have to fix it. There's a good chance
I'll make *you* fix it ;)
-------------------------------
How to get new code into DFHack
-------------------------------
You can send patches or make a clone of the github repo and ask me on
the IRC channel to pull your code in. I'll review it and see if there
are any problems. I'll fix them if they are minor.
Fixes are higher in priority. If you want to work on something, but
don't know what, check out http://github.com/peterix/dfhack/issues --
this is also a good place to dump new ideas and/or bugs that need
fixing.
----------------
Layout for tools
----------------
Tools live in the tools/ folder. There, they are split into three
categories.
distributed
these tools get distributed with binary releases and are installed
by doing 'make install' on linux. They are supposed to be stable
and supported. Experimental, useless, buggy or untested stuff
doesn't belong here.
examples
examples are tools that aren't very useful, but show how DF and
DFHack work. They should use only DFHack API functions. No actual
hacking or 'magic offsets' are allowed.
playground
This is a catch-all folder for tools that aren't ready to be
examples or be distributed in binary releases. All new tools should
start here. They can contain actual hacking, magic values and other
nasty business.
------------------------
Modules - what are they?
------------------------
DFHack uses modules to partition sets of features into manageable
chunks. A module can have both client and server side.
Client side is the part that goes into the main library and is
generally written in C++. It is exposed to the users of DFHack.
Server side is used inside DF and serves to accelerate the client
modules. This is written mostly in C style.
There's a Core module that shouldn't be changed, because it defines the
basic commands like reading and writing raw data. The client parts for
the Core module are the various implementations of the Process
interface.
A good example of a module is Maps. Named the same in both client and
server, it allows accelerating the reading of map blocks.
Communication between modules happens by using shared memory. This is
pretty fast, but needs quite a bit of care to not break.
------------
Dependencies
------------
Internal
either part of the codebase or statically linked.
External
linked as dynamic loaded libraries (.dll, .so, etc.)
If you want to add dependencies, think twice about it. All internal
dependencies for core dfhack should be either public domain or require
attribution at most. External dependencies for tools can be either
that, or any Free Software licenses.
Current internal dependencies
-----------------------------
tinyxml
used by core dfhack to read offset definitions from Memory.xml
md5
an implementation of the MD5 hash algorithm. Used for identifying
DF binaries on Linux.
argstream
Allows reading terminal application arguments. GPL!
Current external dependencies
-----------------------------
wide-character ncurses
used for the veinlook tool on Linux.
x11 libraries
used for sending key events on linux
Build-time dependencies
-----------------------
cmake
you need cmake to generate the build system and some configuration
headers
=========================
Memory offset definitions
=========================
The files with memory offset definitions used by dfhack can be found in the
data folder.

184
Compile.html
Unescape Escape View File

@ -312,28 +312,49 @@ ul.auto-toc {
<body> <body>
<div class="document" id="compiling-dfhack"> <div class="document" id="compiling-dfhack">
<h1 class="title">Compiling DFHACK</h1> <h1 class="title">Compiling DFHACK</h1>
<h2 class="subtitle" id="here-s-how-you-build-dfhack">Here's how you build dfhack!</h2>
<div class="section" id="here-s-how-you-build-dfhack">
<h1><a class="toc-backref" href="#id2">Here's how you build dfhack!</a></h1>
<div class="contents topic" id="contents"> <div class="contents topic" id="contents">
<p class="topic-title first">Contents</p> <p class="topic-title first">Contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#dependencies" id="id1">Dependencies</a></li> <li><a class="reference internal" href="#here-s-how-you-build-dfhack" id="id2">Here's how you build dfhack!</a><ul>
<li><a class="reference internal" href="#building-on-linux" id="id2">Building on Linux</a></li> <li><a class="reference internal" href="#dependencies" id="id3">Dependencies</a></li>
<li><a class="reference internal" href="#building-on-windows" id="id3">Building on Windows</a><ul> <li><a class="reference internal" href="#building-on-linux" id="id4">Building on Linux</a></li>
<li><a class="reference internal" href="#using-mingw" id="id4">Using mingw</a><ul> <li><a class="reference internal" href="#building-on-windows" id="id5">Building on Windows</a><ul>
<li><a class="reference internal" href="#building" id="id5">Building</a></li> <li><a class="reference internal" href="#using-mingw" id="id6">Using mingw</a><ul>
<li><a class="reference internal" href="#building" id="id7">Building</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#using-msvc" id="id6">Using MSVC</a></li> <li><a class="reference internal" href="#using-msvc" id="id8">Using MSVC</a></li>
<li><a class="reference internal" href="#using-some-other-compiler" id="id7">Using some other compiler</a></li> <li><a class="reference internal" href="#using-some-other-compiler" id="id9">Using some other compiler</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#build-targets" id="id8">Build targets</a></li> <li><a class="reference internal" href="#build-targets" id="id10">Build targets</a></li>
<li><a class="reference internal" href="#build-types" id="id9">Build types</a></li> <li><a class="reference internal" href="#build-types" id="id11">Build types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#using-the-library-as-a-developer" id="id12">Using the library as a developer</a><ul>
<li><a class="reference internal" href="#contributing-to-dfhack" id="id13">Contributing to DFHack</a><ul>
<li><a class="reference internal" href="#coding-style" id="id14">Coding style</a></li>
<li><a class="reference internal" href="#how-to-get-new-code-into-dfhack" id="id15">How to get new code into DFHack</a></li>
<li><a class="reference internal" href="#layout-for-tools" id="id16">Layout for tools</a></li>
<li><a class="reference internal" href="#modules-what-are-they" id="id17">Modules - what are they?</a></li>
<li><a class="reference internal" href="#id1" id="id18">Dependencies</a><ul>
<li><a class="reference internal" href="#current-internal-dependencies" id="id19">Current internal dependencies</a></li>
<li><a class="reference internal" href="#current-external-dependencies" id="id20">Current external dependencies</a></li>
<li><a class="reference internal" href="#build-time-dependencies" id="id21">Build-time dependencies</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#memory-offset-definitions" id="id22">Memory offset definitions</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="dependencies"> <div class="section" id="dependencies">
<h1><a class="toc-backref" href="#id1">Dependencies</a></h1> <h2><a class="toc-backref" href="#id3">Dependencies</a></h2>
<ul class="simple"> <ul class="simple">
<li><tt class="docutils literal">cmake</tt></li> <li><tt class="docutils literal">cmake</tt></li>
<li>A compiler for building the main lib and the various tools.</li> <li>A compiler for building the main lib and the various tools.</li>
@ -342,7 +363,7 @@ ul.auto-toc {
</ul> </ul>
</div> </div>
<div class="section" id="building-on-linux"> <div class="section" id="building-on-linux">
<h1><a class="toc-backref" href="#id2">Building on Linux</a></h1> <h2><a class="toc-backref" href="#id4">Building on Linux</a></h2>
<p>To run in the output folder (without installing) building the library <p>To run in the output folder (without installing) building the library
is simple. Enter the build folder, run the tools. Like this:</p> is simple. Enter the build folder, run the tools. Like this:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -350,8 +371,15 @@ cd build
cmake .. -DCMAKE_BUILD_TYPE:string=Release cmake .. -DCMAKE_BUILD_TYPE:string=Release
make make
</pre> </pre>
<p>This will build the library and its tools and place them in <tt class="docutils literal">/output</tt>. <p>This will build the library and its tools and place them in <tt class="docutils literal">/output</tt>.</p>
You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI <p>Alternatively, you can use ccmake instead of cmake:</p>
<blockquote>
cd build
ccmake ..
make</blockquote>
<p>This will show a curses-based interface that lets you set all of the
extra options.</p>
<p>You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI
program.</p> program.</p>
<p>To be installed into the system or packaged:</p> <p>To be installed into the system or packaged:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -370,19 +398,19 @@ make install
</ul> </ul>
</div> </div>
<div class="section" id="building-on-windows"> <div class="section" id="building-on-windows">
<h1><a class="toc-backref" href="#id3">Building on Windows</a></h1> <h2><a class="toc-backref" href="#id5">Building on Windows</a></h2>
<p>You need <tt class="docutils literal">cmake</tt>. Get the win32 installer version from the official <p>You need <tt class="docutils literal">cmake</tt>. Get the win32 installer version from the official
site: <a class="reference external" href="http://www.cmake.org/cmake/resources/software.html">http://www.cmake.org/cmake/resources/software.html</a></p> site: <a class="reference external" href="http://www.cmake.org/cmake/resources/software.html">http://www.cmake.org/cmake/resources/software.html</a></p>
<p>It has the usual installer wizard thing.</p> <p>It has the usual installer wizard thing.</p>
<div class="section" id="using-mingw"> <div class="section" id="using-mingw">
<h2><a class="toc-backref" href="#id4">Using mingw</a></h2> <h3><a class="toc-backref" href="#id6">Using mingw</a></h3>
<p>You also need a compiler. I build dfhack using mingw. You can get it <p>You also need a compiler. I build dfhack using mingw. You can get it
from the mingw site: <a class="reference external" href="http://www.mingw.org/">http://www.mingw.org/</a></p> from the mingw site: <a class="reference external" href="http://www.mingw.org/">http://www.mingw.org/</a></p>
<p>Get the automated installer, it will download newest version of mingw <p>Get the automated installer, it will download newest version of mingw
and set things up nicely.</p> and set things up nicely.</p>
<p>You'll have to add <tt class="docutils literal"><span class="pre">C:\MinGW\</span></tt> to your PATH variable.</p> <p>You'll have to add <tt class="docutils literal"><span class="pre">C:\MinGW\</span></tt> to your PATH variable.</p>
<div class="section" id="building"> <div class="section" id="building">
<h3><a class="toc-backref" href="#id5">Building</a></h3> <h4><a class="toc-backref" href="#id7">Building</a></h4>
<p>open up cmd and navigate to the <tt class="docutils literal">dfhack\build</tt> folder, run <tt class="docutils literal">cmake</tt> <p>open up cmd and navigate to the <tt class="docutils literal">dfhack\build</tt> folder, run <tt class="docutils literal">cmake</tt>
and the mingw version of make:</p> and the mingw version of make:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -393,7 +421,7 @@ mingw32-make
</div> </div>
</div> </div>
<div class="section" id="using-msvc"> <div class="section" id="using-msvc">
<h2><a class="toc-backref" href="#id6">Using MSVC</a></h2> <h3><a class="toc-backref" href="#id8">Using MSVC</a></h3>
<p>open up <tt class="docutils literal">cmd</tt> and navigate to the <tt class="docutils literal">dfhack\build</tt> folder, run <p>open up <tt class="docutils literal">cmd</tt> and navigate to the <tt class="docutils literal">dfhack\build</tt> folder, run
<tt class="docutils literal">cmake</tt>:</p> <tt class="docutils literal">cmake</tt>:</p>
<pre class="literal-block"> <pre class="literal-block">
@ -410,14 +438,14 @@ by changing cmake configs and running <tt class="docutils literal">cmake</tt> on
</div> </div>
</div> </div>
<div class="section" id="using-some-other-compiler"> <div class="section" id="using-some-other-compiler">
<h2><a class="toc-backref" href="#id7">Using some other compiler</a></h2> <h3><a class="toc-backref" href="#id9">Using some other compiler</a></h3>
<p>I'm afraid you are on your own. dfhack wasn't tested with any other <p>I'm afraid you are on your own. dfhack wasn't tested with any other
compiler.</p> compiler.</p>
<p>Try using a different cmake generator that's intended for your tools.</p> <p>Try using a different cmake generator that's intended for your tools.</p>
</div> </div>
</div> </div>
<div class="section" id="build-targets"> <div class="section" id="build-targets">
<h1><a class="toc-backref" href="#id8">Build targets</a></h1> <h2><a class="toc-backref" href="#id10">Build targets</a></h2>
<p>dfhack has a few build targets:</p> <p>dfhack has a few build targets:</p>
<ul> <ul>
<li><p class="first">If you're only after the library run <tt class="docutils literal">make dfhack</tt>.</p> <li><p class="first">If you're only after the library run <tt class="docutils literal">make dfhack</tt>.</p>
@ -443,7 +471,7 @@ cmake .. -DBUILD_DFHACK_EXAMPLES=ON
</ul> </ul>
</div> </div>
<div class="section" id="build-types"> <div class="section" id="build-types">
<h1><a class="toc-backref" href="#id9">Build types</a></h1> <h2><a class="toc-backref" href="#id11">Build types</a></h2>
<p><tt class="docutils literal">cmake</tt> allows you to pick a build type by changing this <p><tt class="docutils literal">cmake</tt> allows you to pick a build type by changing this
variable: <tt class="docutils literal">CMAKE_BUILD_TYPE</tt></p> variable: <tt class="docutils literal">CMAKE_BUILD_TYPE</tt></p>
<pre class="literal-block"> <pre class="literal-block">
@ -456,5 +484,119 @@ cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
<p>Have fun.</p> <p>Have fun.</p>
</div> </div>
</div> </div>
<div class="section" id="using-the-library-as-a-developer">
<h1><a class="toc-backref" href="#id12">Using the library as a developer</a></h1>
<p>DFHack is using the zlib/libpng license. This makes it easy to link to
it, use it in-source or add your own extensions. Contributing back to
the dfhack repository is welcome and the right thing to do :)</p>
<p>Rudimentary API documentation can be built using doxygen.</p>
<div class="section" id="contributing-to-dfhack">
<h2><a class="toc-backref" href="#id13">Contributing to DFHack</a></h2>
<p>Several things should be kept in mind when contributing to DFHack.</p>
<div class="section" id="coding-style">
<h3><a class="toc-backref" href="#id14">Coding style</a></h3>
<p>DFhack uses ANSI formatting and four spaces as indentation. Line
endings are UNIX. The files use UTF-8 encoding. Code not following this
won't make me happy, because I'll have to fix it. There's a good chance
I'll make <em>you</em> fix it ;)</p>
</div>
<div class="section" id="how-to-get-new-code-into-dfhack">
<h3><a class="toc-backref" href="#id15">How to get new code into DFHack</a></h3>
<p>You can send patches or make a clone of the github repo and ask me on
the IRC channel to pull your code in. I'll review it and see if there
are any problems. I'll fix them if they are minor.</p>
<p>Fixes are higher in priority. If you want to work on something, but
don't know what, check out <a class="reference external" href="http://github.com/peterix/dfhack/issues">http://github.com/peterix/dfhack/issues</a> --
this is also a good place to dump new ideas and/or bugs that need
fixing.</p>
</div>
<div class="section" id="layout-for-tools">
<h3><a class="toc-backref" href="#id16">Layout for tools</a></h3>
<p>Tools live in the tools/ folder. There, they are split into three
categories.</p>
<dl class="docutils">
<dt>distributed</dt>
<dd>these tools get distributed with binary releases and are installed
by doing 'make install' on linux. They are supposed to be stable
and supported. Experimental, useless, buggy or untested stuff
doesn't belong here.</dd>
<dt>examples</dt>
<dd>examples are tools that aren't very useful, but show how DF and
DFHack work. They should use only DFHack API functions. No actual
hacking or 'magic offsets' are allowed.</dd>
<dt>playground</dt>
<dd>This is a catch-all folder for tools that aren't ready to be
examples or be distributed in binary releases. All new tools should
start here. They can contain actual hacking, magic values and other
nasty business.</dd>
</dl>
</div>
<div class="section" id="modules-what-are-they">
<h3><a class="toc-backref" href="#id17">Modules - what are they?</a></h3>
<p>DFHack uses modules to partition sets of features into manageable
chunks. A module can have both client and server side.</p>
<p>Client side is the part that goes into the main library and is
generally written in C++. It is exposed to the users of DFHack.</p>
<p>Server side is used inside DF and serves to accelerate the client
modules. This is written mostly in C style.</p>
<p>There's a Core module that shouldn't be changed, because it defines the
basic commands like reading and writing raw data. The client parts for
the Core module are the various implementations of the Process
interface.</p>
<p>A good example of a module is Maps. Named the same in both client and
server, it allows accelerating the reading of map blocks.</p>
<p>Communication between modules happens by using shared memory. This is
pretty fast, but needs quite a bit of care to not break.</p>
</div>
<div class="section" id="id1">
<h3><a class="toc-backref" href="#id18">Dependencies</a></h3>
<dl class="docutils">
<dt>Internal</dt>
<dd>either part of the codebase or statically linked.</dd>
<dt>External</dt>
<dd>linked as dynamic loaded libraries (.dll, .so, etc.)</dd>
</dl>
<p>If you want to add dependencies, think twice about it. All internal
dependencies for core dfhack should be either public domain or require
attribution at most. External dependencies for tools can be either
that, or any Free Software licenses.</p>
<div class="section" id="current-internal-dependencies">
<h4><a class="toc-backref" href="#id19">Current internal dependencies</a></h4>
<dl class="docutils">
<dt>tinyxml</dt>
<dd>used by core dfhack to read offset definitions from Memory.xml</dd>
<dt>md5</dt>
<dd>an implementation of the MD5 hash algorithm. Used for identifying
DF binaries on Linux.</dd>
<dt>argstream</dt>
<dd>Allows reading terminal application arguments. GPL!</dd>
</dl>
</div>
<div class="section" id="current-external-dependencies">
<h4><a class="toc-backref" href="#id20">Current external dependencies</a></h4>
<dl class="docutils">
<dt>wide-character ncurses</dt>
<dd>used for the veinlook tool on Linux.</dd>
<dt>x11 libraries</dt>
<dd>used for sending key events on linux</dd>
</dl>
</div>
<div class="section" id="build-time-dependencies">
<h4><a class="toc-backref" href="#id21">Build-time dependencies</a></h4>
<dl class="docutils">
<dt>cmake</dt>
<dd>you need cmake to generate the build system and some configuration
headers</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="section" id="memory-offset-definitions">
<h1><a class="toc-backref" href="#id22">Memory offset definitions</a></h1>
<p>The files with memory offset definitions used by dfhack can be found in the
data folder.</p>
</div>
</div>
</body> </body>
</html> </html>

134
README.rst
Unescape Escape View File

@ -45,12 +45,17 @@ Windows
fix it :) fix it :)
0.31.01 - 0.31.03 legacy 0.31.01 - 0.31.03 legacy
0.31.04 - 0.31.21 SDL 0.31.04 - 0.31.21 SDL
There are missing offsets but Map tools should be OK. Wait for updates...
You need have the MSVC 2010 redistributable_ package installed! The tools will fail to run otherwise.
.. _redistributable: http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a7b7a05e-6de6-4d3a-a423-37bf0912db84
Linux Linux
===== =====
0.31.05 - 0.31.19 native. 0.31.05 - 0.31.19 native.
There are missing offsets but Map tools should be OK. Linux support is There are missing offsets but Map tools should be OK. Linux support is
a bit lacking, I'm working on it. Slowly. All supported Windows versions a bit lacking, I'm working on it. Slowly. All supported Windows versions
running in wine can be used with native DFHack binaries. running in wine can be used with native DFHack binaries.
@ -150,130 +155,3 @@ I take no responsibility of anything that happens as a result of using this tool
Your tool here Your tool here
============== ==============
Write one ;) Write one ;)
================================
Using the library as a developer
================================
The library is compilable under Linux with GCC and under Windows with
MinGW32 and MSVC compilers. It is using the cmake build system. See
COMPILE for details.
DFHack is using the zlib/libpng license. This makes it easy to link to
it, use it in-source or add your own extensions. Contributing back to
the dfhack repository is welcome and the right thing to do :)
At the time of writing there's no API reference or documentation. The
code does have a lot of comments though (and getting better all the
time).
Contributing to DFHack
======================
Several things should be kept in mind when contributing to DFHack.
------------
Coding style
------------
DFhack uses ANSI formatting and four spaces as indentation. Line
endings are UNIX. The files use UTF-8 encoding. Code not following this
won't make me happy, because I'll have to fix it. There's a good chance
I'll make *you* fix it ;)
-------------------------------
How to get new code into DFHack
-------------------------------
You can send patches or make a clone of the github repo and ask me on
the IRC channel to pull your code in. I'll review it and see if there
are any problems. I'll fix them if they are minor.
Fixes are higher in priority. If you want to work on something, but
don't know what, check out http://github.com/peterix/dfhack/issues --
this is also a good place to dump new ideas and/or bugs that need
fixing.
----------------
Layout for tools
----------------
Tools live in the tools/ folder. There, they are split into three
categories.
distributed
these tools get distributed with binary releases and are installed
by doing 'make install' on linux. They are supposed to be stable
and supported. Experimental, useless, buggy or untested stuff
doesn't belong here.
examples
examples are tools that aren't very useful, but show how DF and
DFHack work. They should use only DFHack API functions. No actual
hacking or 'magic offsets' are allowed.
playground
This is a catch-all folder for tools that aren't ready to be
examples or be distributed in binary releases. All new tools should
start here. They can contain actual hacking, magic values and other
nasty business.
------------------------
Modules - what are they?
------------------------
DFHack uses modules to partition sets of features into manageable
chunks. A module can have both client and server side.
Client side is the part that goes into the main library and is
generally written in C++. It is exposed to the users of DFHack.
Server side is used inside DF and serves to accelerate the client
modules. This is written mostly in C style.
There's a Core module that shouldn't be changed, because it defines the
basic commands like reading and writing raw data. The client parts for
the Core module are the various implementations of the Process
interface.
A good example of a module is Maps. Named the same in both client and
server, it allows accelerating the reading of map blocks.
Communication between modules happens by using shared memory. This is
pretty fast, but needs quite a bit of care to not break.
------------
Dependencies
------------
Internal
either part of the codebase or statically linked.
External
linked as dynamic loaded libraries (.dll, .so, etc.)
If you want to add dependencies, think twice about it. All internal
dependencies for core dfhack should be either public domain or require
attribution at most. External dependencies for tools can be either
that, or any Free Software licenses.
Current internal dependencies
-----------------------------
tinyxml
used by core dfhack to read offset definitions from Memory.xml
md5
an implementation of the MD5 hash algorithm. Used for identifying
DF binaries on Linux.
argstream
Allows reading terminal application arguments. GPL!
Current external dependencies
-----------------------------
wide-character ncurses
used for the veinlook tool on Linux.
x11 libraries
used for sending key events on linux
Build-time dependencies
-----------------------
cmake
you need cmake to generate the build system and some configuration
headers
=========================
Memory offset definitions
=========================
The files with memory offset definitions used by dfhack can be found in the
data folder.

145
Readme.html
Unescape Escape View File

@ -353,23 +353,6 @@ allow for easier development of new tools.</p>
<li><a class="reference internal" href="#your-tool-here" id="id24">Your tool here</a></li> <li><a class="reference internal" href="#your-tool-here" id="id24">Your tool here</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#using-the-library-as-a-developer" id="id25">Using the library as a developer</a><ul>
<li><a class="reference internal" href="#contributing-to-dfhack" id="id26">Contributing to DFHack</a><ul>
<li><a class="reference internal" href="#coding-style" id="id27">Coding style</a></li>
<li><a class="reference internal" href="#how-to-get-new-code-into-dfhack" id="id28">How to get new code into DFHack</a></li>
<li><a class="reference internal" href="#layout-for-tools" id="id29">Layout for tools</a></li>
<li><a class="reference internal" href="#modules-what-are-they" id="id30">Modules - what are they?</a></li>
<li><a class="reference internal" href="#dependencies" id="id31">Dependencies</a><ul>
<li><a class="reference internal" href="#current-internal-dependencies" id="id32">Current internal dependencies</a></li>
<li><a class="reference internal" href="#current-external-dependencies" id="id33">Current external dependencies</a></li>
<li><a class="reference internal" href="#build-time-dependencies" id="id34">Build-time dependencies</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#memory-offset-definitions" id="id35">Memory offset definitions</a></li>
</ul> </ul>
</div> </div>
</div> </div>
@ -397,14 +380,14 @@ in AUR and the arch-games repository.</p>
functionality. If you know how to easily suspend processes, you can functionality. If you know how to easily suspend processes, you can
fix it :)</p> fix it :)</p>
</div> </div>
<p>0.31.01 - 0.31.03 legacy <p>0.31.01 - 0.31.03 legacy</p>
0.31.04 - 0.31.21 SDL <p>0.31.04 - 0.31.21 SDL</p>
There are missing offsets but Map tools should be OK. Wait for updates...</p> <p>You need have the MSVC 2010 <a class="reference external" href="http://www.microsoft.com/downloads/en/details.aspx?FamilyID=a7b7a05e-6de6-4d3a-a423-37bf0912db84">redistributable</a> package installed! The tools will fail to run otherwise.</p>
</div> </div>
<div class="section" id="linux"> <div class="section" id="linux">
<h2><a class="toc-backref" href="#id6">Linux</a></h2> <h2><a class="toc-backref" href="#id6">Linux</a></h2>
<p>0.31.05 - 0.31.19 native. <p>0.31.05 - 0.31.19 native.</p>
There are missing offsets but Map tools should be OK. Linux support is <p>There are missing offsets but Map tools should be OK. Linux support is
a bit lacking, I'm working on it. Slowly. All supported Windows versions a bit lacking, I'm working on it. Slowly. All supported Windows versions
running in wine can be used with native DFHack binaries.</p> running in wine can be used with native DFHack binaries.</p>
</div> </div>
@ -503,124 +486,6 @@ You just lost a fortress and gained an adventurer.</p>
<p>Write one ;)</p> <p>Write one ;)</p>
</div> </div>
</div> </div>
<div class="section" id="using-the-library-as-a-developer">
<h1><a class="toc-backref" href="#id25">Using the library as a developer</a></h1>
<p>The library is compilable under Linux with GCC and under Windows with
MinGW32 and MSVC compilers. It is using the cmake build system. See
COMPILE for details.</p>
<p>DFHack is using the zlib/libpng license. This makes it easy to link to
it, use it in-source or add your own extensions. Contributing back to
the dfhack repository is welcome and the right thing to do :)</p>
<p>At the time of writing there's no API reference or documentation. The
code does have a lot of comments though (and getting better all the
time).</p>
<div class="section" id="contributing-to-dfhack">
<h2><a class="toc-backref" href="#id26">Contributing to DFHack</a></h2>
<p>Several things should be kept in mind when contributing to DFHack.</p>
<div class="section" id="coding-style">
<h3><a class="toc-backref" href="#id27">Coding style</a></h3>
<p>DFhack uses ANSI formatting and four spaces as indentation. Line
endings are UNIX. The files use UTF-8 encoding. Code not following this
won't make me happy, because I'll have to fix it. There's a good chance
I'll make <em>you</em> fix it ;)</p>
</div>
<div class="section" id="how-to-get-new-code-into-dfhack">
<h3><a class="toc-backref" href="#id28">How to get new code into DFHack</a></h3>
<p>You can send patches or make a clone of the github repo and ask me on
the IRC channel to pull your code in. I'll review it and see if there
are any problems. I'll fix them if they are minor.</p>
<p>Fixes are higher in priority. If you want to work on something, but
don't know what, check out <a class="reference external" href="http://github.com/peterix/dfhack/issues">http://github.com/peterix/dfhack/issues</a> --
this is also a good place to dump new ideas and/or bugs that need
fixing.</p>
</div>
<div class="section" id="layout-for-tools">
<h3><a class="toc-backref" href="#id29">Layout for tools</a></h3>
<p>Tools live in the tools/ folder. There, they are split into three
categories.</p>
<dl class="docutils">
<dt>distributed</dt>
<dd>these tools get distributed with binary releases and are installed
by doing 'make install' on linux. They are supposed to be stable
and supported. Experimental, useless, buggy or untested stuff
doesn't belong here.</dd>
<dt>examples</dt>
<dd>examples are tools that aren't very useful, but show how DF and
DFHack work. They should use only DFHack API functions. No actual
hacking or 'magic offsets' are allowed.</dd>
<dt>playground</dt>
<dd>This is a catch-all folder for tools that aren't ready to be
examples or be distributed in binary releases. All new tools should
start here. They can contain actual hacking, magic values and other
nasty business.</dd>
</dl>
</div>
<div class="section" id="modules-what-are-they">
<h3><a class="toc-backref" href="#id30">Modules - what are they?</a></h3>
<p>DFHack uses modules to partition sets of features into manageable
chunks. A module can have both client and server side.</p>
<p>Client side is the part that goes into the main library and is
generally written in C++. It is exposed to the users of DFHack.</p>
<p>Server side is used inside DF and serves to accelerate the client
modules. This is written mostly in C style.</p>
<p>There's a Core module that shouldn't be changed, because it defines the
basic commands like reading and writing raw data. The client parts for
the Core module are the various implementations of the Process
interface.</p>
<p>A good example of a module is Maps. Named the same in both client and
server, it allows accelerating the reading of map blocks.</p>
<p>Communication between modules happens by using shared memory. This is
pretty fast, but needs quite a bit of care to not break.</p>
</div>
<div class="section" id="dependencies">
<h3><a class="toc-backref" href="#id31">Dependencies</a></h3>
<dl class="docutils">
<dt>Internal</dt>
<dd>either part of the codebase or statically linked.</dd>
<dt>External</dt>
<dd>linked as dynamic loaded libraries (.dll, .so, etc.)</dd>
</dl>
<p>If you want to add dependencies, think twice about it. All internal
dependencies for core dfhack should be either public domain or require
attribution at most. External dependencies for tools can be either
that, or any Free Software licenses.</p>
<div class="section" id="current-internal-dependencies">
<h4><a class="toc-backref" href="#id32">Current internal dependencies</a></h4>
<dl class="docutils">
<dt>tinyxml</dt>
<dd>used by core dfhack to read offset definitions from Memory.xml</dd>
<dt>md5</dt>
<dd>an implementation of the MD5 hash algorithm. Used for identifying
DF binaries on Linux.</dd>
<dt>argstream</dt>
<dd>Allows reading terminal application arguments. GPL!</dd>
</dl>
</div>
<div class="section" id="current-external-dependencies">
<h4><a class="toc-backref" href="#id33">Current external dependencies</a></h4>
<dl class="docutils">
<dt>wide-character ncurses</dt>
<dd>used for the veinlook tool on Linux.</dd>
<dt>x11 libraries</dt>
<dd>used for sending key events on linux</dd>
</dl>
</div>
<div class="section" id="build-time-dependencies">
<h4><a class="toc-backref" href="#id34">Build-time dependencies</a></h4>
<dl class="docutils">
<dt>cmake</dt>
<dd>you need cmake to generate the build system and some configuration
headers</dd>
</dl>
</div>
</div>
</div>
</div>
<div class="section" id="memory-offset-definitions">
<h1><a class="toc-backref" href="#id35">Memory offset definitions</a></h1>
<p>The files with memory offset definitions used by dfhack can be found in the
data folder.</p>
</div>
</div> </div>
</body> </body>
</html> </html>

5
build/auto.bat
Unescape Escape View File

@ -0,0 +1,5 @@
mkdir build-real
cd build-real
cmake ..\.. -G"Visual Studio 10"
msbuild ALL_BUILD.vcxproj /p:Configuration=Release
echo FINISHED_BUILD

39
build/buildremote.expect
Unescape Escape View File

@ -0,0 +1,39 @@
#!/usr/bin/expect
# procedure to attempt connecting; result 0 if OK, 1 otherwise
proc connect {} {
expect "login:"
send "kitteh\r"
expect "password:"
send "a\r"
expect {
kitteh {return 0}
failed return 1
"invalid password" return 1
timeout return 1
connected
}
# timed out
return 1
}
spawn telnet win7
set rez [connect]
if { $rez == 0 } {
send "net use X: \\\\vboxsvr\\projects\r\n"
expect "The command completed successfully."
send "X:\r\n"
expect "X:"
send "cd X:\\dfhack\\build\r\n"
expect "build"
send "\"C:\\Program Files (x86)\\MSVC10\\VC\\vcvarsall.bat\" x86\r\n"
expect "build"
set timeout -1
send "auto.bat\r\n"
expect "FINISHED_BUILD"
send "exit\r"
expect eof
exit 0
}
puts "\nError connecting to server!\n"
exit 1

49
build/linux-MSVC-2008.sh
Unescape Escape View File

@ -0,0 +1,49 @@
#/bin/sh
# VARS
export WINEARCH=win32
export WINEPREFIX=$HOME/.wine-mscv/
export WINEDEBUG=-all
export DFHACK_VER=0.5.6
export PKG=dfhack-bin-$DFHACK_VER
export VCBUILD="/home/peterix/.wine-mscv/drive_c/Program Files/Microsoft Visual Studio 9.0/VC/vcpackages/vcbuild.exe"
export TARGET=Release
export PROJECTS="library\\dfhack.vcproj
tools\\supported\\dfattachtest.vcproj
tools\\supported\\dfautosearch.vcproj
tools\\supported\\dfcleanmap.vcproj
tools\\supported\\dfcleartask.vcproj
tools\\supported\\dfdoffsets.vcproj
tools\\supported\\dfexpbench.vcproj
tools\\supported\\dfflows.vcproj
tools\\supported\\dfincremental.vcproj
tools\\supported\\dfliquids.vcproj
tools\\supported\\dfmode.vcproj
tools\\supported\\dfpause.vcproj
tools\\supported\\dfposition.vcproj
tools\\supported\\dfprobe.vcproj
tools\\supported\\dfprospector.vcproj
tools\\supported\\dfreveal.vcproj
tools\\supported\\dfsuspend.vcproj
tools\\supported\\dfunstuck.vcproj
tools\\supported\\dfvdig.vcproj
tools\\supported\\dfweather.vcproj"
# let's build it all
rm -r build-real
mkdir build-real
cd build-real
wine cmake ..\\.. -G"Visual Studio 9 2008"
for proj in $PROJECTS
do
wine "$VCBUILD" $proj $TARGET
done
echo "Creating package..."
cd ../../output/$TARGET
rm -r $PKG
rm $PKG.zip
mkdir $PKG
mv *.exe *.dll *.html *.txt *.xml $PKG
zip -r $PKG.zip $PKG
echo "DONE"

20
build/linux-remote-MSVC-2008.sh
Unescape Escape View File

@ -0,0 +1,20 @@
#/bin/sh
# VARS
export DFHACK_VER=0.5.6
export PKG=dfhack-bin-$DFHACK_VER
export TARGET=Release
# let's build it all
VBoxManage startvm "7 Prof"
sleep 5
expect buildremote.expect $TARGET
echo "Creating package..."
cd ../output/$TARGET
rm -r $PKG
rm $PKG.zip
mkdir $PKG
mv *.exe *.dll *.html *.txt *.xml $PKG
zip -r $PKG.zip $PKG
echo "DONE"

3
doc/CMakeLists.txt
Unescape Escape View File

@ -47,7 +47,6 @@ IF(DOXYGEN_FOUND)
# "${CMAKE_SOURCE_DIR}/library/private" # "${CMAKE_SOURCE_DIR}/library/private"
) )
SET(DOXYGEN_OUTPUT_DIR html)
STRING(REGEX REPLACE ";" " " CMAKE_DOXYGEN_INPUT_LIST "${DOXYGEN_SOURCE_DIR}") STRING(REGEX REPLACE ";" " " CMAKE_DOXYGEN_INPUT_LIST "${DOXYGEN_SOURCE_DIR}")
CONFIGURE_FILE(Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) CONFIGURE_FILE(Doxyfile.in ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
@ -57,7 +56,7 @@ IF(DOXYGEN_FOUND)
/usr/bin/doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile /usr/bin/doxygen ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile
DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
INSTALL( DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/" DESTINATION "/usr/share/doc/dfhack-${DFHACK_VERSION}" ) # INSTALL( DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/html/" DESTINATION "/usr/share/doc/dfhack-${DFHACK_VERSION}" )
ELSE(DOXYGEN_FOUND) ELSE(DOXYGEN_FOUND)
MESSAGE (FATAL_ERROR "doxygen binary couldn't be found") MESSAGE (FATAL_ERROR "doxygen binary couldn't be found")

10
doc/Doxyfile.in
Unescape Escape View File

@ -38,7 +38,7 @@ PROJECT_NUMBER = @DFHACK_VERSION@
# If a relative path is entered, it will be relative to the location # If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used. # where doxygen was started. If left blank the current directory will be used.
OUTPUT_DIRECTORY = . OUTPUT_DIRECTORY = @DOXYGEN_OUTPUT_DIR@
# If the CREATE_SUBDIRS tag is set to YES, then doxygen will create # If the CREATE_SUBDIRS tag is set to YES, then doxygen will create
# 4096 sub-directories (in 2 levels) under the output directory of each output # 4096 sub-directories (in 2 levels) under the output directory of each output
@ -60,7 +60,7 @@ CREATE_SUBDIRS = NO
# Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak, # Polish, Portuguese, Romanian, Russian, Serbian, Serbian-Cyrilic, Slovak,
# Slovene, Spanish, Swedish, Ukrainian, and Vietnamese. # Slovene, Spanish, Swedish, Ukrainian, and Vietnamese.
OUTPUT_LANGUAGE = English OUTPUT_LANGUAGE = @DOXYGEN_LANGUAGE@
# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will # If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
# include brief member descriptions after the members that are listed in # include brief member descriptions after the members that are listed in
@ -225,7 +225,7 @@ EXTENSION_MAPPING =
# func(std::string) {}). This also make the inheritance and collaboration # func(std::string) {}). This also make the inheritance and collaboration
# diagrams that involve STL classes more complete and accurate. # diagrams that involve STL classes more complete and accurate.
BUILTIN_STL_SUPPORT = NO BUILTIN_STL_SUPPORT = YES
# If you use Microsoft's C++/CLI language, you should set this option to YES to # If you use Microsoft's C++/CLI language, you should set this option to YES to
# enable parsing support. # enable parsing support.
@ -521,7 +521,7 @@ LAYOUT_FILE =
# The QUIET tag can be used to turn on/off the messages that are generated # The QUIET tag can be used to turn on/off the messages that are generated
# by doxygen. Possible values are YES and NO. If left blank NO is used. # by doxygen. Possible values are YES and NO. If left blank NO is used.
QUIET = NO QUIET = YES
# The WARNINGS tag can be used to turn on/off the warning messages that are # The WARNINGS tag can be used to turn on/off the warning messages that are
# generated by doxygen. Possible values are YES and NO. If left blank # generated by doxygen. Possible values are YES and NO. If left blank
@ -775,7 +775,7 @@ GENERATE_HTML = YES
# If a relative path is entered the value of OUTPUT_DIRECTORY will be # If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank `html' will be used as the default path. # put in front of it. If left blank `html' will be used as the default path.
HTML_OUTPUT = html HTML_OUTPUT = .
# The HTML_FILE_EXTENSION tag can be used to specify the file extension for # The HTML_FILE_EXTENSION tag can be used to specify the file extension for
# each generated HTML page (for example: .htm,.php,.asp). If it is left blank # each generated HTML page (for example: .htm,.php,.asp). If it is left blank

2
doc/index.dxgen
Unescape Escape View File

@ -51,7 +51,7 @@ PLACEHOLDER TERRITORY!
Second part has some details on DFHack development: Second part has some details on DFHack development:
<ul> <ul>
<li>Section \ref starting tells you how to cromulate at a distance! <li>Section \ref starting tells you how to cromulate at a distance, with a difference!
</ul> </ul>
The third part describes how to use the supported DFHack utilities The third part describes how to use the supported DFHack utilities

10
library/include/dfhack/modules/Maps.h
Unescape Escape View File

@ -65,16 +65,26 @@ namespace DFHack
// x,y,z share the same space with comparate. comparate can be used for fast comparisons // x,y,z share the same space with comparate. comparate can be used for fast comparisons
union union
{ {
// new shiny DFCoord struct. notice the ludicrous space for Z-levels
struct struct
{ {
uint16_t x; uint16_t x;
uint16_t y; uint16_t y;
uint32_t z; uint32_t z;
}; };
// old planeccord struct for compatibility
struct
{
uint16_t x;
uint16_t y;
} dim;
// comparing thing
uint64_t comparate; uint64_t comparate;
}; };
}; };
typedef DFCoord planecoord;
struct t_feature struct t_feature
{ {
e_feature type; e_feature type;

0
output/doxygen/.keep
Unescape Escape View File

6
tools/supported/liquids.cpp
Unescape Escape View File

@ -1,5 +1,3 @@
// TO BE DEPRECATED SOON.
#include <iostream> #include <iostream>
#include <vector> #include <vector>
#include <map> #include <map>
@ -20,7 +18,7 @@ public:
virtual coord_vec points(MapCache & mc,DFHack::DFCoord start) = 0; virtual coord_vec points(MapCache & mc,DFHack::DFCoord start) = 0;
}; };
/** /**
* generic 2D rectangle brush. you can specify the dimensions of * generic 3D rectangle brush. you can specify the dimensions of
* the rectangle and optionally which tile is its 'center' * the rectangle and optionally which tile is its 'center'
*/ */
class RectangleBrush : public Brush class RectangleBrush : public Brush
@ -37,7 +35,7 @@ public:
else else
cy_ = centery; cy_ = centery;
if(centerz == -1) if(centerz == -1)
cz_ = y/2; cz_ = z/2;
else else
cz_ = centerz; cz_ = centerz;
x_ = x; x_ = x;