summaryrefslogtreecommitdiff
path: root/Compile.html
diff options
context:
space:
mode:
Diffstat (limited to 'Compile.html')
-rw-r--r--Compile.html184
1 files changed, 163 insertions, 21 deletions
diff --git a/Compile.html b/Compile.html
index b4a252cc..8e91e15f 100644
--- a/Compile.html
+++ b/Compile.html
@@ -312,28 +312,49 @@ ul.auto-toc {
<body>
<div class="document" id="compiling-dfhack">
<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">
<p class="topic-title first">Contents</p>
<ul class="simple">
-<li><a class="reference internal" href="#dependencies" id="id1">Dependencies</a></li>
-<li><a class="reference internal" href="#building-on-linux" id="id2">Building on Linux</a></li>
-<li><a class="reference internal" href="#building-on-windows" id="id3">Building on Windows</a><ul>
-<li><a class="reference internal" href="#using-mingw" id="id4">Using mingw</a><ul>
-<li><a class="reference internal" href="#building" id="id5">Building</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="#dependencies" id="id3">Dependencies</a></li>
+<li><a class="reference internal" href="#building-on-linux" id="id4">Building on Linux</a></li>
+<li><a class="reference internal" href="#building-on-windows" id="id5">Building on Windows</a><ul>
+<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>
</li>
-<li><a class="reference internal" href="#using-msvc" id="id6">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-msvc" id="id8">Using MSVC</a></li>
+<li><a class="reference internal" href="#using-some-other-compiler" id="id9">Using some other compiler</a></li>
</ul>
</li>
-<li><a class="reference internal" href="#build-targets" id="id8">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-targets" id="id10">Build targets</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>
</div>
<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">
<li><tt class="docutils literal">cmake</tt></li>
<li>A compiler for building the main lib and the various tools.</li>
@@ -342,7 +363,7 @@ ul.auto-toc {
</ul>
</div>
<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
is simple. Enter the build folder, run the tools. Like this:</p>
<pre class="literal-block">
@@ -350,8 +371,15 @@ cd build
cmake .. -DCMAKE_BUILD_TYPE:string=Release
make
</pre>
-<p>This will build the library and its tools and place them in <tt class="docutils literal">/output</tt>.
-You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI
+<p>This will build the library and its tools and place them in <tt class="docutils literal">/output</tt>.</p>
+<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>
<p>To be installed into the system or packaged:</p>
<pre class="literal-block">
@@ -370,19 +398,19 @@ make install
</ul>
</div>
<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
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>
<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
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
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>
<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>
and the mingw version of make:</p>
<pre class="literal-block">
@@ -393,7 +421,7 @@ mingw32-make
</div>
</div>
<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
<tt class="docutils literal">cmake</tt>:</p>
<pre class="literal-block">
@@ -410,14 +438,14 @@ by changing cmake configs and running <tt class="docutils literal">cmake</tt> on
</div>
</div>
<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
compiler.</p>
<p>Try using a different cmake generator that's intended for your tools.</p>
</div>
</div>
<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>
<ul>
<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>
</div>
<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
variable: <tt class="docutils literal">CMAKE_BUILD_TYPE</tt></p>
<pre class="literal-block">
@@ -456,5 +484,119 @@ cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
<p>Have fun.</p>
</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>
</html>