Updated README, added Readme and Compile with DOS line endings
Petr Mrázek
parent
ce151458e4
commit
b60ef9f70f
@ -0,0 +1,138 @@
|
|||||||
|
Here's how you build dfhack!
|
||||||
|
----------------------------
|
||||||
|
|
||||||
|
First, there is one dependency, regardless of the OS you use:
|
||||||
|
cmake - it's the build system
|
||||||
|
|
||||||
|
|
||||||
|
Building on Linux:
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
* To run in the output folder (without installing):
|
||||||
|
|
||||||
|
building the library is simple. Enter the build folder, run the tools. Like this:
|
||||||
|
|
||||||
|
cd build
|
||||||
|
cmake .. -DCMAKE_BUILD_TYPE:string=Release
|
||||||
|
make
|
||||||
|
|
||||||
|
This will build the library and its tools and place them in /output.
|
||||||
|
You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI program.
|
||||||
|
|
||||||
|
* To be installed into the system or packaged
|
||||||
|
|
||||||
|
cd build
|
||||||
|
cmake -DCMAKE_BUILD_TYPE:string=Release -DCMAKE_INSTALL_PREFIX=/usr -DMEMXML_DATA_PATH:path=/usr/share/dfhack ..
|
||||||
|
make
|
||||||
|
make install
|
||||||
|
|
||||||
|
With this dfhack installs:
|
||||||
|
library to $CMAKE_INSTALL_PREFIX/lib
|
||||||
|
executables to $CMAKE_INSTALL_PREFIX/bin
|
||||||
|
The Memory.xml file to /usr/share/dfhack
|
||||||
|
|
||||||
|
See the section on the shared memory hook library (SHM).
|
||||||
|
|
||||||
|
Building on Windows:
|
||||||
|
--------------------
|
||||||
|
|
||||||
|
You need cmake. Get the win32 installer version from the official site: http://www.cmake.org/cmake/resources/software.html
|
||||||
|
It has the usual installer wizard thing.
|
||||||
|
|
||||||
|
* Using mingw:
|
||||||
|
|
||||||
|
You also need a compiler. I build dfhack using mingw. You can get it from the mingw site:
|
||||||
|
Get the automated installer, it will download newest version of mingw and set things up nicely.
|
||||||
|
You'll have to add C:\MinGW\ to your PATH variable.
|
||||||
|
|
||||||
|
- Building:
|
||||||
|
open up cmd and navigate to the dfhack\build folder, run cmake and the mingw version of make:
|
||||||
|
cd build
|
||||||
|
cmake .. -G"MinGW Makefiles" -DCMAKE_BUILD_TYPE:string=Release
|
||||||
|
mingw32-make
|
||||||
|
|
||||||
|
* Using MSVC
|
||||||
|
|
||||||
|
open up cmd and navigate to the dfhack\build folder, run cmake:
|
||||||
|
cd build
|
||||||
|
cmake ..
|
||||||
|
|
||||||
|
This will generate MSVC solution and project files. Note that: you are working in the /build 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 cmake on them!
|
||||||
|
|
||||||
|
* Using some other compiler:
|
||||||
|
|
||||||
|
I'm afraid you are on your own. dfhack wasn't tested with any other compiler.
|
||||||
|
Try using a different cmake generator that's intended for your tools.
|
||||||
|
|
||||||
|
|
||||||
|
Building the shared memory hook library (SHM)
|
||||||
|
---------------------------------------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
For DF 40d15 - 40d17 on Windows, use MSVC 2008. You can get the Express 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't be debugged, because debug builds in MSVC use a different CRT!
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
* 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 lost.
|
||||||
|
|
||||||
|
|
||||||
|
Build targets
|
||||||
|
-------------
|
||||||
|
|
||||||
|
dfhack has a few build targets. If you're only after the library run 'make dfhack'.
|
||||||
|
'make' will build everything.
|
||||||
|
'make expbench' will build the expbench throughput testing program and the library.
|
||||||
|
|
||||||
|
|
||||||
|
Build types
|
||||||
|
-----------
|
||||||
|
|
||||||
|
cmake allows you to pick a build type by changing this variable: CMAKE_BUILD_TYPE
|
||||||
|
|
||||||
|
cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPE
|
||||||
|
|
||||||
|
Without specifying a build type or 'None', cmake uses the CMAKE_CXX_FLAGS variable for building.
|
||||||
|
Valid build types include 'Release' and 'Debug'. There are others, but they aren't really that useful.
|
||||||
|
|
||||||
|
Have fun.
|
||||||
@ -0,0 +1,174 @@
|
|||||||
|
Introduction
|
||||||
|
------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
It is an attempt to unite the various ways tools access DF memory and allow for
|
||||||
|
easier development of new tools.
|
||||||
|
|
||||||
|
|
||||||
|
Getting DFHack
|
||||||
|
----------------
|
||||||
|
The project is currently hosted on github:
|
||||||
|
http://github.com/peterix/dfhack
|
||||||
|
|
||||||
|
There's an SVN repository at sourceforge, but will only be updated for major releases:
|
||||||
|
https://sourceforge.net/projects/dfhack/
|
||||||
|
* subversion access:
|
||||||
|
svn co https://dfhack.svn.sourceforge.net/svnroot/dfhack/trunk dfhack
|
||||||
|
|
||||||
|
Compatibility
|
||||||
|
-------------
|
||||||
|
|
||||||
|
DFHack works on Windows XP, Vista, 7 or any modern Linux distribution.
|
||||||
|
|
||||||
|
Windows 2000 is currently *not supported* due to missing OS functionality.
|
||||||
|
If you know how to easily suspend processes, you can fix it :)
|
||||||
|
|
||||||
|
OSX is also not supported due to lack of developers with a Mac.
|
||||||
|
|
||||||
|
Currently supported Dwarf Fortress versions:
|
||||||
|
* Windows
|
||||||
|
40d
|
||||||
|
40d9 - 40d18
|
||||||
|
|
||||||
|
* Linux
|
||||||
|
40d9 - 40d18
|
||||||
|
|
||||||
|
|
||||||
|
Using the library
|
||||||
|
-----------------
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
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 :)
|
||||||
|
|
||||||
|
At the time of writing there's no API reference or documentation. The code does
|
||||||
|
have a lot of comments though.
|
||||||
|
|
||||||
|
|
||||||
|
Using DFHack Tools
|
||||||
|
------------------
|
||||||
|
|
||||||
|
The project comes with a special extra library you should add to your DF
|
||||||
|
installation. It's used to boost the transfer speed between DF and DFHack, and
|
||||||
|
provide data consistency and synchronization. DFHack will work without the
|
||||||
|
library, but at suboptimal speeds and the consistency of data written back
|
||||||
|
to DF is questionable.
|
||||||
|
|
||||||
|
!!! on Windows this currently only works with DF 40d15 - 40d18 !!!
|
||||||
|
On Linux, it works with the whole range of supported DF versions.
|
||||||
|
|
||||||
|
!!! use the pre-compiled library intended for your OS and version of DF !!!
|
||||||
|
You can find them in the 'precompiled' folder.
|
||||||
|
|
||||||
|
|
||||||
|
** Installing on Windows
|
||||||
|
- Open your DF folder, locate SDL.dll and rename it to SDLreal.dll (making
|
||||||
|
a backup of it is a good idea)
|
||||||
|
- Copy the right DFHack SDL.dll into your DF folder.
|
||||||
|
- Restart DF if it is running
|
||||||
|
|
||||||
|
** Unistalling on Windows
|
||||||
|
- Open your DF folder, locate SDL.dll and delete it
|
||||||
|
- Rename SDLreal.dll to SDL.dll
|
||||||
|
- Restart DF if it is running
|
||||||
|
|
||||||
|
|
||||||
|
** Installing on Linux
|
||||||
|
- Open your DF folder and the libs folder within it
|
||||||
|
- copy DFHack libdfconnect.so to the libs folder
|
||||||
|
- copy the df startup script, name it dfhacked
|
||||||
|
- open the new dfhacked startup script and add this line:
|
||||||
|
export LD_PRELOAD="./libs/libdfconnect.so" # Hack DF!
|
||||||
|
just before the line that launches DF
|
||||||
|
|
||||||
|
Here's an example how the file can look after the change:
|
||||||
|
#!/bin/sh
|
||||||
|
DF_DIR=$(dirname "$0")
|
||||||
|
cd "${DF_DIR}"
|
||||||
|
export SDL_DISABLE_LOCK_KEYS=1 # Work around for bug in Debian/Ubuntu SDL patch.
|
||||||
|
#export SDL_VIDEO_CENTERED=1 # Centre the screen. Messes up resizing.
|
||||||
|
ldd dwarfort.exe | grep SDL_image | grep -qv "not found$"
|
||||||
|
if [ $? -eq 0 ]; then
|
||||||
|
mkdir unused_libs
|
||||||
|
mv libs/libSDL* unused_libs/
|
||||||
|
fi
|
||||||
|
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:"./libs" # Update library search path.
|
||||||
|
export LD_PRELOAD="./libs/libdfconnect.so" # Hack DF!
|
||||||
|
./dwarfort.exe $* # Go, go, go! :)
|
||||||
|
|
||||||
|
- Use this new startup script to start DF
|
||||||
|
|
||||||
|
** Uninstalling on Linux
|
||||||
|
- Open your DF and DF/libs folders
|
||||||
|
- Delete libdfconnect.so and the dfhacked startup script
|
||||||
|
- Go back to using the df startup script
|
||||||
|
|
||||||
|
|
||||||
|
Tools
|
||||||
|
-----
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
If the tool writes back to DF's memory, make sure you are using the shared
|
||||||
|
memory interface mentioned in the previous section!
|
||||||
|
|
||||||
|
* reveal - plain old reveal tool. It reveals all the map blocks already
|
||||||
|
initialized by DF.
|
||||||
|
|
||||||
|
* prospector - scans the map for minerals. by default it only scans only visible
|
||||||
|
veins. You can make it show hidden things with '-a' and base rock
|
||||||
|
and soil layers with '-b'. These can be combined ('-ab')
|
||||||
|
|
||||||
|
* cleanmap - cleans mud, vomit, snow and all kinds of mess from the map.
|
||||||
|
It will clean your irrigated farms too, so consider yourself
|
||||||
|
warned.
|
||||||
|
|
||||||
|
* incremental - incremental search utility.
|
||||||
|
|
||||||
|
* bauxite - converts all mechanisms into bauxite mechanisms.
|
||||||
|
|
||||||
|
* itemdesignator - Allows mass-designating items by type and material - dump,
|
||||||
|
forbid, melt and set on fire ;)
|
||||||
|
* digger - allows designating tiles for digging/cutting/ramp removal
|
||||||
|
|
||||||
|
A list of accepted tile classes:
|
||||||
|
1 = WALL
|
||||||
|
2 = PILLAR
|
||||||
|
3 = FORTIFICATION
|
||||||
|
|
||||||
|
4 = STAIR_UP
|
||||||
|
5 = STAIR_DOWN
|
||||||
|
6 = STAIR_UPDOWN
|
||||||
|
|
||||||
|
7 = RAMP
|
||||||
|
|
||||||
|
8 = FLOOR
|
||||||
|
9 = TREE_DEAD
|
||||||
|
10 = TREE_OK
|
||||||
|
11 = SAPLING_DEAD
|
||||||
|
12 = SAPLING_OK
|
||||||
|
13 = SHRUB_DEAD
|
||||||
|
14 = SHRUB_OK
|
||||||
|
15 = BOULDER
|
||||||
|
16 = PEBBLES
|
||||||
|
|
||||||
|
Example : dfdigger -o 100,100,15 -t 9,10 -m 10
|
||||||
|
This will start looking for trees at coords 100,100,15 and designate ten of them for cutting.
|
||||||
|
|
||||||
|
|
||||||
|
Memory offset definitions
|
||||||
|
-------------------------
|
||||||
|
|
||||||
|
The file with memory offset definitions used by dfhack can be found in the
|
||||||
|
output folder.
|
||||||
|
|
||||||
|
~ EOF ~
|
||||||
Loading…
Reference in New Issue