dfhack/Compile.html

523 lines
17 KiB
HTML

<?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>
2010-08-09 17:21:47 -06:00
<ul>
<li><p class="first">If you're only after the library run <tt class="docutils literal">make dfhack</tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal">make</tt> will build everything.</p>
</li>
<li><p class="first"><tt class="docutils literal">make expbench</tt> will build the expbench testing program and the
library.</p>
</li>
<li><p class="first">Some of the utilities and the doxygen documentation won't be
normally built. You can enable them by specifying some extra
CMake variables:</p>
<pre class="literal-block">
BUILD_DFHACK_DOCUMENTATION - generate the documentation (really bad)
BUILD_DFHACK_EXAMPLES - build tools from tools/examples
BUILD_DFHACK_PLAYGROUND - build tools from tools/playground
</pre>
<p>Example:</p>
<pre class="literal-block">
cmake .. -DBUILD_DFHACK_EXAMPLES=ON
</pre>
</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>