summaryrefslogtreecommitdiff
path: root/Compile.html
diff options
context:
space:
mode:
Diffstat (limited to 'Compile.html')
-rw-r--r--Compile.html506
1 files changed, 506 insertions, 0 deletions
diff --git a/Compile.html b/Compile.html
new file mode 100644
index 00000000..1e418054
--- /dev/null
+++ b/Compile.html
@@ -0,0 +1,506 @@
+<?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>Compiling DFHACK</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" 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="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>
+</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>
+</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="#building-the-shared-memory-hook-library-shm" id="id10">Building the shared memory hook library (SHM)</a></li>
+<li><a class="reference internal" href="#checking-strings-support" id="id11">Checking strings support</a></li>
+</ul>
+</div>
+<div class="section" id="dependencies">
+<h1><a class="toc-backref" href="#id1">Dependencies</a></h1>
+<ul class="simple">
+<li><tt class="docutils literal">cmake</tt></li>
+<li>A compiler for building the main lib and the various tools.</li>
+<li>(Linux only) Veinlook requires the wide-character ncurses library (libncursesw)</li>
+<li>(Linux only) You'll need X11 dev libraries.</li>
+</ul>
+</div>
+<div class="section" id="building-on-linux">
+<h1><a class="toc-backref" href="#id2">Building on Linux</a></h1>
+<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">
+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
+program.</p>
+<p>To be installed into the system or packaged:</p>
+<pre class="literal-block">
+cd build
+cmake -DCMAKE_BUILD_TYPE:string=Release \
+ -DCMAKE_INSTALL_PREFIX=/usr \
+ -DMEMXML_DATA_PATH:path=/usr/share/dfhack ..
+make
+make install
+</pre>
+<p>With this dfhack installs:</p>
+<ul class="simple">
+<li>library to <tt class="docutils literal">$CMAKE_INSTALL_PREFIX/lib</tt></li>
+<li>executables to <tt class="docutils literal">$CMAKE_INSTALL_PREFIX/bin</tt></li>
+<li>The <tt class="docutils literal">Memory.xml</tt> file to <tt class="docutils literal">/usr/share/dfhack</tt></li>
+</ul>
+<p>See the section on the shared memory hook library (SHM).</p>
+</div>
+<div class="section" id="building-on-windows">
+<h1><a class="toc-backref" href="#id3">Building on Windows</a></h1>
+<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>
+<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>
+<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">
+cd build
+cmake .. -G&quot;MinGW Makefiles&quot; -DCMAKE_BUILD_TYPE:string=Release
+mingw32-make
+</pre>
+</div>
+</div>
+<div class="section" id="using-msvc">
+<h2><a class="toc-backref" href="#id6">Using MSVC</a></h2>
+<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">
+cd build
+cmake ..
+</pre>
+<p>This will generate MSVC solution and project files.</p>
+<div class="note">
+<p class="first admonition-title">Note</p>
+<p class="last">You are working in the <tt class="docutils literal">/build</tt> folder. Files added to
+projects will end up there! (and that's wrong). Any changes to the
+build system should be done by changing cmake configs and running
+<tt class="docutils literal">cmake</tt> on them!</p>
+</div>
+<p>Also, you'll have to copy the <tt class="docutils literal">Memory.xml</tt> file to the build output
+folders MSVC generates. For example from <tt class="docutils literal">output/</tt> to
+<tt class="docutils literal">output/Release/</tt></p>
+</div>
+<div class="section" id="using-some-other-compiler">
+<h2><a class="toc-backref" href="#id7">Using some other compiler</a></h2>
+<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>
+<p>dfhack has a few build targets:</p>
+<ul class="simple">
+<li>If you're only after the library run <tt class="docutils literal">make dfhack</tt>.</li>
+<li><tt class="docutils literal">make</tt> will build everything.</li>
+<li><tt class="docutils literal">make expbench</tt> will build the expbench testing program and the
+library.</li>
+</ul>
+</div>
+<div class="section" id="build-types">
+<h1><a class="toc-backref" href="#id9">Build types</a></h1>
+<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">
+cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
+</pre>
+<p>Without specifying a build type or 'None', cmake uses the
+<tt class="docutils literal">CMAKE_CXX_FLAGS</tt> variable for building.</p>
+<p>Valid an useful build types include 'Release', 'Debug' and
+'RelWithDebInfo'. There are others, but they aren't really that useful.</p>
+<p>Have fun.</p>
+</div>
+<div class="section" id="building-the-shared-memory-hook-library-shm">
+<h1><a class="toc-backref" href="#id10">Building the shared memory hook library (SHM)</a></h1>
+<p>Unlike the rest of DFHack, The SHM needs special treatment when it
+comes to compilation. Because it shares the memory space with DF
+itself, it has to be built with the same tools as DF and use the same C
+and C++/STL libraries.</p>
+<p>For DF 31.01 - 31.10 on Windows, use MSVC 2008. You can get the Express
+edition for free from Microsoft.</p>
+<p>Windows dependencies can be determined by a tool like <tt class="docutils literal">depends.exe</tt>
+(<a class="reference external" href="http://www.google.com/search?q=depends.exe">google it</a>). Both the fake <tt class="docutils literal">SDL.dll</tt> and DF have to use the same
+version of the C runtime (MSVCRT). The SHM can only be debugged using a
+RelWithDebInfo build!</p>
+<p>Linux dependencies can be determined by setting the LD_DEBUG variable
+and running ./df:</p>
+<pre class="literal-block">
+export LD_DEBUG=versions
+./df
+</pre>
+<p>Example of (a part of a) relevant output from a working SHM
+installation:</p>
+<pre class="literal-block">
+24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libpthread.so.0 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GCC_3.0' in file ./libs/libgcc_s.so.1 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBC_2.0' in file ./libs/libgcc_s.so.1 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBC_2.1' in file /opt/lib32/lib/libm.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libm.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBC_2.1.3' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBC_2.3.4' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBC_2.4' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libc.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBCXX_3.4.9' in file ./libs/libstdc++.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `CXXABI_1.3' in file ./libs/libstdc++.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `GLIBCXX_3.4' in file ./libs/libstdc++.so.6 [0] required by file ./dwarfort.exe [0]
+24472: checking for version `CXXABI_1.3' in file ./libs/libstdc++.so.6 [0] required by file ./libs/libdfconnect.so [0]
+24472: checking for version `GLIBCXX_3.4' in file ./libs/libstdc++.so.6 [0] required by file ./libs/libdfconnect.so [0]
+24472: checking for version `GLIBC_2.1.3' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
+24472: checking for version `GLIBC_2.2' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
+24472: checking for version `GLIBC_2.3.4' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
+24472: checking for version `GLIBC_2.0' in file /opt/lib32/lib/libc.so.6 [0] required by file ./libs/libdfconnect.so [0]
+</pre>
+<p>libdfconnect is the SHM. Both are compiled against the same C++ library
+and share the same CXXABI version.</p>
+<p>Precompiled SHM libraries are provided in binary releases.</p>
+</div>
+<div class="section" id="checking-strings-support">
+<h1><a class="toc-backref" href="#id11">Checking strings support</a></h1>
+<p>Strings are one of the important C++ types and a great indicator that
+the SHM works. Tools like Dwarf Therapist depend on string support.
+Reading of strings can be checked by running any of the tools that deal
+with materials.</p>
+<p>String writing is best tested with a fresh throw-away fort and
+<tt class="docutils literal">dfrenamer</tt>.</p>
+<p>Embark, give one dwarf a very long name using dfrenamer and save/exit.
+If DF crashes during the save sequence, your SHM is not compatible with
+DF and the throw-away fort is most probably lost.</p>
+</div>
+</div>
+</body>
+</html>