diff options
| author | Petr Mrázek | 2011-03-13 19:38:32 +0100 |
|---|---|---|
| committer | Petr Mrázek | 2011-03-13 19:38:32 +0100 |
| commit | cb86f5299366afeb85cd12a8f4bce76f051d0699 (patch) | |
| tree | 19cc50255367e57761467cfa418c13e1e8099a9f /Compile.html | |
| parent | b6d02768b4bc12dec6bd036f075208d2b1f52a12 (diff) | |
| download | dfhack-cb86f5299366afeb85cd12a8f4bce76f051d0699.tar.gz dfhack-cb86f5299366afeb85cd12a8f4bce76f051d0699.tar.bz2 dfhack-cb86f5299366afeb85cd12a8f4bce76f051d0699.tar.xz | |
minor liquids bugfix, added typedef for planecoord so that stonesense builds. Build system bits. Doxygen bits.
Diffstat (limited to 'Compile.html')
| -rw-r--r-- | Compile.html | 184 |
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> |
