Updated docs.

develop
Petr Mrázek 2010-08-13 03:31:05 +02:00
parent 7188d87a5b
commit 343b14753b
4 changed files with 14 additions and 123 deletions

@ -87,13 +87,9 @@ This will generate MSVC solution and project files.
.. note:: .. note::
You are working in the ``/build`` folder. Files added to You are working in the ``/build`` folder. Files added to
projects will end up there! (and that's wrong). Any changes to the projects from within MSVC will end up there! (and that's
build system should be done by changing cmake configs and running wrong). Any changes to the build system should be done
``cmake`` on them! by changing cmake configs and running ``cmake`` on them!
Also, you'll have to copy the ``Memory.xml`` file to the build output
folders MSVC generates. For example from ``output/`` to
``output/Release/``
------------------------- -------------------------
Using some other compiler Using some other compiler
@ -147,59 +143,5 @@ 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 itself, it has to be built with the same tools as DF and use the same C
and C++/STL libraries. and C++/STL libraries.
For DF 31.01 - 31.10 on Windows, use MSVC 2008. You can get the Express For DF 31.01 - 31.12 on Windows, use MSVC 2008. You can get the Express
edition for free from Microsoft. edition for free from Microsoft.
Windows dependencies can be determined by a tool like ``depends.exe``
(`google it`_). Both the fake ``SDL.dll`` and DF have to use the same
version of the C runtime (MSVCRT). The SHM can only be debugged using a
RelWithDebInfo build!
Linux dependencies can be determined by setting the LD_DEBUG variable
and running ./df::
export LD_DEBUG=versions
./df
Example of (a part of a) relevant output from a working SHM
installation::
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]
libdfconnect is the SHM. Both are compiled against the same C++ library
and share the same CXXABI version.
Precompiled SHM libraries are provided in binary releases.
.. _google it: http://www.google.com/search?q=depends.exe
Checking strings support
========================
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.
String writing is best tested with a fresh throw-away fort and
``dfrenamer``.
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.

@ -331,7 +331,6 @@ ul.auto-toc {
<li><a class="reference internal" href="#build-targets" id="id8">Build targets</a></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-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="#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> </ul>
</div> </div>
<div class="section" id="dependencies"> <div class="section" id="dependencies">
@ -407,13 +406,10 @@ cmake ..
<div class="note"> <div class="note">
<p class="first admonition-title">Note</p> <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 <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 projects from within MSVC will end up there! (and that's
build system should be done by changing cmake configs and running wrong). Any changes to the build system should be done
<tt class="docutils literal">cmake</tt> on them!</p> by changing cmake configs and running <tt class="docutils literal">cmake</tt> on them!</p>
</div> </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>
<div class="section" id="using-some-other-compiler"> <div class="section" id="using-some-other-compiler">
<h2><a class="toc-backref" href="#id7">Using some other compiler</a></h2> <h2><a class="toc-backref" href="#id7">Using some other compiler</a></h2>
@ -467,55 +463,8 @@ cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
comes to compilation. Because it shares the memory space with DF 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 itself, it has to be built with the same tools as DF and use the same C
and C++/STL libraries.</p> and C++/STL libraries.</p>
<p>For DF 31.01 - 31.10 on Windows, use MSVC 2008. You can get the Express <p>For DF 31.01 - 31.12 on Windows, use MSVC 2008. You can get the Express
edition for free from Microsoft.</p> 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>
</div> </div>
</body> </body>

@ -49,7 +49,7 @@ Windows
Linux Linux
===== =====
0.31.04 - 0.31.12 native. 0.31.05 - 0.31.12 native.
There are missing offsets but Map tools should be OK. Linux support is 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 a bit lacking, I'm working on it. All supported Windows versions
running in wine can be used with native DFHack binaries. running in wine can be used with native DFHack binaries.
@ -247,6 +247,6 @@ cmake
========================= =========================
Memory offset definitions Memory offset definitions
========================= =========================
The file with memory offset definitions used by dfhack can be found in the The files with memory offset definitions used by dfhack can be found in the
output folder. data folder.

@ -398,7 +398,7 @@ fix it :)</p>
</div> </div>
<div class="section" id="linux"> <div class="section" id="linux">
<h2><a class="toc-backref" href="#id6">Linux</a></h2> <h2><a class="toc-backref" href="#id6">Linux</a></h2>
<p>0.31.04 - 0.31.12 native. <p>0.31.05 - 0.31.12 native.
There are missing offsets but Map tools should be OK. Linux support is 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 a bit lacking, I'm working on it. All supported Windows versions
running in wine can be used with native DFHack binaries.</p> running in wine can be used with native DFHack binaries.</p>
@ -588,8 +588,8 @@ headers</dd>
</div> </div>
<div class="section" id="memory-offset-definitions"> <div class="section" id="memory-offset-definitions">
<h1><a class="toc-backref" href="#id31">Memory offset definitions</a></h1> <h1><a class="toc-backref" href="#id31">Memory offset definitions</a></h1>
<p>The file with memory offset definitions used by dfhack can be found in the <p>The files with memory offset definitions used by dfhack can be found in the
output folder.</p> data folder.</p>
</div> </div>
</div> </div>
</body> </body>