diff options
| author | Petr Mrázek | 2010-07-25 10:03:47 +0200 |
|---|---|---|
| committer | Petr Mrázek | 2010-07-25 10:03:47 +0200 |
| commit | 0454dc6ab7cdf9370a06a95419a4412b9c212ea8 (patch) | |
| tree | 108eac42f6b98eaa5067a0f13736fc100e87944f /Readme.html | |
| parent | 148f3b3c6b618d3a877c0d7ad9e61d96161d6012 (diff) | |
| download | dfhack-0454dc6ab7cdf9370a06a95419a4412b9c212ea8.tar.gz dfhack-0454dc6ab7cdf9370a06a95419a4412b9c212ea8.tar.bz2 dfhack-0454dc6ab7cdf9370a06a95419a4412b9c212ea8.tar.xz | |
Removed old README and COMPILE files, added rst->html bash script that uses docutils
Diffstat (limited to 'Readme.html')
| -rw-r--r-- | Readme.html | 586 |
1 files changed, 586 insertions, 0 deletions
diff --git a/Readme.html b/Readme.html new file mode 100644 index 00000000..f1366154 --- /dev/null +++ b/Readme.html @@ -0,0 +1,586 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.7: http://docutils.sourceforge.net/" /> +<title></title> +<style type="text/css"> + +/* +:Author: David Goodger (goodger@python.org) +:Id: $Id: html4css1.css 6253 2010-03-02 00:24:53Z milde $ +:Copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. + +See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to +customize this style sheet. +*/ + +/* used to remove borders from tables and images */ +.borderless, table.borderless td, table.borderless th { + border: 0 } + +table.borderless td, table.borderless th { + /* Override padding for "table.docutils td" with "! important". + The right padding separates the table cells. */ + padding: 0 0.5em 0 0 ! important } + +.first { + /* Override more specific margin styles with "! important". */ + margin-top: 0 ! important } + +.last, .with-subtitle { + margin-bottom: 0 ! important } + +.hidden { + display: none } + +a.toc-backref { + text-decoration: none ; + color: black } + +blockquote.epigraph { + margin: 2em 5em ; } + +dl.docutils dd { + margin-bottom: 0.5em } + +/* Uncomment (and remove this text!) to get bold-faced definition list terms +dl.docutils dt { + font-weight: bold } +*/ + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.admonition, div.attention, div.caution, div.danger, div.error, +div.hint, div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.admonition p.admonition-title, div.hint p.admonition-title, +div.important p.admonition-title, div.note p.admonition-title, +div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +/* Uncomment (and remove this text!) to get reduced vertical space in + compound paragraphs. +div.compound .compound-first, div.compound .compound-middle { + margin-bottom: 0.5em } + +div.compound .compound-last, div.compound .compound-middle { + margin-top: 0.5em } +*/ + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em ; + margin-right: 2em } + +div.footer, div.header { + clear: both; + font-size: smaller } + +div.line-block { + display: block ; + margin-top: 1em ; + margin-bottom: 1em } + +div.line-block div.line-block { + margin-top: 0 ; + margin-bottom: 0 ; + margin-left: 1.5em } + +div.sidebar { + margin: 0 0 0.5em 1em ; + border: medium outset ; + padding: 1em ; + background-color: #ffffee ; + width: 40% ; + float: right ; + clear: right } + +div.sidebar p.rubric { + font-family: sans-serif ; + font-size: medium } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.section-subtitle, h2.section-subtitle, h3.section-subtitle, +h4.section-subtitle, h5.section-subtitle, h6.section-subtitle { + margin-top: 0.4em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr.docutils { + width: 75% } + +img.align-left, .figure.align-left, object.align-left { + clear: left ; + float: left ; + margin-right: 1em } + +img.align-right, .figure.align-right, object.align-right { + clear: right ; + float: right ; + margin-left: 1em } + +img.align-center, .figure.align-center, object.align-center { + display: block; + margin-left: auto; + margin-right: auto; +} + +.align-left { + text-align: left } + +.align-center { + clear: both ; + text-align: center } + +.align-right { + text-align: right } + +/* reset inner alignment in figures */ +div.align-right { + text-align: left } + +/* div.align-center * { */ +/* text-align: left } */ + +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + +p.attribution { + text-align: right ; + margin-left: 50% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.rubric { + font-weight: bold ; + font-size: larger ; + color: maroon ; + text-align: center } + +p.sidebar-title { + font-family: sans-serif ; + font-weight: bold ; + font-size: larger } + +p.sidebar-subtitle { + font-family: sans-serif ; + font-weight: bold } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font: inherit } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +span.section-subtitle { + /* font-size relative to parent (h1..h6 element) */ + font-size: 80% } + +table.citation { + border-left: solid 1px gray; + margin-left: 1px } + +table.docinfo { + margin: 2em 4em } + +table.docutils { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.footnote { + border-left: solid 1px black; + margin-left: 1px } + +table.docutils td, table.docutils th, +table.docinfo td, table.docinfo th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +table.docutils th.field-name, table.docinfo th.docinfo-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap ; + padding-left: 0 } + +h1 tt.docutils, h2 tt.docutils, h3 tt.docutils, +h4 tt.docutils, h5 tt.docutils, h6 tt.docutils { + font-size: 100% } + +ul.auto-toc { + list-style-type: none } + +</style> +</head> +<body> +<div class="document"> + + +<div class="section" id="introduction"> +<h1><a class="toc-backref" href="#id1">Introduction</a></h1> +<p>DFHack is a Dwarf Fortress memory access library and a set of basic +tools using this library. The library is a work in progress, so things +might change as more tools are written for it.</p> +<p>It is an attempt to unite the various ways tools access DF memory and +allow for easier development of new tools.</p> +<div class="contents topic" id="contents"> +<p class="topic-title first">Contents</p> +<ul class="simple"> +<li><a class="reference internal" href="#introduction" id="id1">Introduction</a></li> +<li><a class="reference internal" href="#getting-dfhack" id="id2">Getting DFHack</a><ul> +<li><a class="reference internal" href="#packages" id="id3">Packages</a></li> +</ul> +</li> +<li><a class="reference internal" href="#compatibility" id="id4">Compatibility</a><ul> +<li><a class="reference internal" href="#windows" id="id5">Windows</a></li> +<li><a class="reference internal" href="#linux" id="id6">Linux</a></li> +</ul> +</li> +<li><a class="reference internal" href="#tools" id="id7">Tools</a><ul> +<li><a class="reference internal" href="#dfcleanmap" id="id8">dfcleanmap</a></li> +<li><a class="reference internal" href="#dfexpbench" id="id9">dfexpbench</a></li> +<li><a class="reference internal" href="#dfliquids" id="id10">dfliquids</a></li> +<li><a class="reference internal" href="#dfposition" id="id11">dfposition</a></li> +<li><a class="reference internal" href="#dfprospector" id="id12">dfprospector</a></li> +<li><a class="reference internal" href="#dfreveal" id="id13">dfreveal</a></li> +<li><a class="reference internal" href="#dfsuspend" id="id14">dfsuspend</a></li> +<li><a class="reference internal" href="#dfunstuck" id="id15">dfunstuck</a></li> +<li><a class="reference internal" href="#dfvdig" id="id16">dfvdig</a></li> +<li><a class="reference internal" href="#dfflows" id="id17">dfflows</a></li> +<li><a class="reference internal" href="#your-tool-here" id="id18">Your tool here</a></li> +</ul> +</li> +<li><a class="reference internal" href="#using-the-library-as-a-developer" id="id19">Using the library as a developer</a><ul> +<li><a class="reference internal" href="#contributing-to-dfhack" id="id20">Contributing to DFHack</a><ul> +<li><a class="reference internal" href="#coding-style" id="id21">Coding style</a></li> +<li><a class="reference internal" href="#how-to-get-new-code-into-dfhack" id="id22">How to get new code into DFHack</a></li> +<li><a class="reference internal" href="#layout-for-tools" id="id23">Layout for tools</a></li> +<li><a class="reference internal" href="#modules-what-are-they" id="id24">Modules - what are they?</a></li> +<li><a class="reference internal" href="#dependencies" id="id25">Dependencies</a><ul> +<li><a class="reference internal" href="#current-internal-dependencies" id="id26">Current internal dependencies</a></li> +<li><a class="reference internal" href="#current-external-dependencies" id="id27">Current external dependencies</a></li> +<li><a class="reference internal" href="#build-time-dependencies" id="id28">Build-time dependencies</a></li> +</ul> +</li> +</ul> +</li> +</ul> +</li> +<li><a class="reference internal" href="#memory-offset-definitions" id="id29">Memory offset definitions</a></li> +</ul> +</div> +</div> +<div class="section" id="getting-dfhack"> +<h1><a class="toc-backref" href="#id2">Getting DFHack</a></h1> +<p>The project is currently hosted on <a class="reference external" href="http://www.github.com/">github</a>, for both source and +binaries at <a class="reference external" href="http://github.com/peterix/dfhack">http://github.com/peterix/dfhack</a></p> +<div class="section" id="packages"> +<h2><a class="toc-backref" href="#id3">Packages</a></h2> +<p>The library and tools are packaged for Archlinux and are available both +in AUR and the arch-games repository.</p> +<p>The package name is dfhack-git :)</p> +</div> +</div> +<div class="section" id="compatibility"> +<h1><a class="toc-backref" href="#id4">Compatibility</a></h1> +<p>DFHack works on Windows XP, Vista, 7 or any modern Linux distribution.</p> +<p>OSX is not supported due to lack of developers with a Mac.</p> +<p>Currently supported Dwarf Fortress versions are Windows and Linux.</p> +<div class="section" id="windows"> +<h2><a class="toc-backref" href="#id5">Windows</a></h2> +<div class="note"> +<p class="first admonition-title">Note</p> +<p class="last">Windows 2000 is currently <em>not supported</em> due to missing OS +functionality. If you know how to easily suspend processes, you can +fix it :)</p> +</div> +<p>0.31.01 - 0.31.03 legacy +0.31.04 - 0.31.11 SDL</p> +</div> +<div class="section" id="linux"> +<h2><a class="toc-backref" href="#id6">Linux</a></h2> +<p>0.31.04 - 0.31.11 native. +There are missing offsets but Map tools should be OK. Linux support is +a bit lacking, I'm working on it. All supported Windows versions +running in wine can be used with DFHack.</p> +</div> +</div> +<div class="section" id="tools"> +<h1><a class="toc-backref" href="#id7">Tools</a></h1> +<p>All the DFHack tools are terminal programs. This might seem strange to Windows +users, but these are meant mostly as examples for developers. Still, they can +be useful and are cross-platform just like the library itself.</p> +<div class="section" id="dfcleanmap"> +<h2><a class="toc-backref" href="#id8">dfcleanmap</a></h2> +<p>Cleans all the splatter that get scattered all over the map. +Only exception is mud. It leaves mud alone.</p> +</div> +<div class="section" id="dfexpbench"> +<h2><a class="toc-backref" href="#id9">dfexpbench</a></h2> +<p>Just a simple benchmark of the data export speed.</p> +</div> +<div class="section" id="dfliquids"> +<h2><a class="toc-backref" href="#id10">dfliquids</a></h2> +<p>A command prompt for liquid creation and manipulation (the Moses +effect included!) Also allows painting obsidian walls directly.</p> +<div class="note"> +<p class="first admonition-title">Note</p> +<p class="last">Spawning and deleting liquids can F up pathing data and +temperatures (creating heat traps). You've been warned.</p> +</div> +</div> +<div class="section" id="dfposition"> +<h2><a class="toc-backref" href="#id11">dfposition</a></h2> +<p>Prints the current DF window properties and cursor position.</p> +</div> +<div class="section" id="dfprospector"> +<h2><a class="toc-backref" href="#id12">dfprospector</a></h2> +<p>Lists all available minerals on the map and how much of them there is.</p> +</div> +<div class="section" id="dfreveal"> +<h2><a class="toc-backref" href="#id13">dfreveal</a></h2> +<p>Reveals the whole map, waits for input and hides it again. If you close +the tool while it waits, the map remains revealed.</p> +</div> +<div class="section" id="dfsuspend"> +<h2><a class="toc-backref" href="#id14">dfsuspend</a></h2> +<p>Test of the process suspend/resume mechanism.</p> +</div> +<div class="section" id="dfunstuck"> +<h2><a class="toc-backref" href="#id15">dfunstuck</a></h2> +<p>Use if you prematurely close any of the tools and DF appears to be +stuck.</p> +</div> +<div class="section" id="dfvdig"> +<h2><a class="toc-backref" href="#id16">dfvdig</a></h2> +<p>Designates a whole vein for digging. Point the cursor at a vein and run +this thing :)</p> +</div> +<div class="section" id="dfflows"> +<h2><a class="toc-backref" href="#id17">dfflows</a></h2> +<p>A tool for checking how many liquid tiles are actively checked for +flows.</p> +</div> +<div class="section" id="your-tool-here"> +<h2><a class="toc-backref" href="#id18">Your tool here</a></h2> +<p>Write one ;)</p> +</div> +</div> +<div class="section" id="using-the-library-as-a-developer"> +<h1><a class="toc-backref" href="#id19">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="#id20">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="#id21">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="#id22">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="#id23">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="#id24">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="#id25">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="#id26">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="#id27">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="#id28">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="#id29">Memory offset definitions</a></h1> +<p>The file with memory offset definitions used by dfhack can be found in the +output folder.</p> +</div> +</div> +</body> +</html> |
