Updated README, added Readme and Compile with DOS line endings

develop
Petr Mrázek 2010-02-24 15:06:40 +01:00
parent ce151458e4
commit b60ef9f70f
3 changed files with 346 additions and 11 deletions

@ -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.

@ -11,17 +11,14 @@ easier development of new tools.
Getting DFHack Getting DFHack
---------------- ----------------
The project is currently hosted on github:
http://github.com/peterix/dfhack
You can get the code at DFHack's sourceforge site: There's an SVN repository at sourceforge, but will only be updated for major releases:
https://sourceforge.net/projects/dfhack/ https://sourceforge.net/projects/dfhack/
* subversion access: * subversion access:
svn co https://dfhack.svn.sourceforge.net/svnroot/dfhack/trunk dfhack svn co https://dfhack.svn.sourceforge.net/svnroot/dfhack/trunk dfhack
It is also available on github:
http://github.com/peterix/dfhack
Compatibility Compatibility
------------- -------------
@ -35,10 +32,10 @@ OSX is also not supported due to lack of developers with a Mac.
Currently supported Dwarf Fortress versions: Currently supported Dwarf Fortress versions:
* Windows * Windows
40d 40d
40d9 - 40d17 40d9 - 40d18
* Linux * Linux
40d9 - 40d17 40d9 - 40d18
Using the library Using the library
@ -64,12 +61,13 @@ provide data consistency and synchronization. DFHack will work without the
library, but at suboptimal speeds and the consistency of data written back library, but at suboptimal speeds and the consistency of data written back
to DF is questionable. to DF is questionable.
!!! on Windows this currently only works with DF 40d15, 40d16 and 40d17 !!! !!! on Windows this currently only works with DF 40d15 - 40d18 !!!
On Linux, it works with the whole range of supported DF versions. On Linux, it works with the whole range of supported DF versions.
!!! use the pre-compiled library intended for your version of DF !!! !!! use the pre-compiled library intended for your OS and version of DF !!!
You can find them in the 'precompiled' folder. You can find them in the 'precompiled' folder.
** Installing on Windows ** Installing on Windows
- Open your DF folder, locate SDL.dll and rename it to SDLreal.dll (making - Open your DF folder, locate SDL.dll and rename it to SDLreal.dll (making
a backup of it is a good idea) a backup of it is a good idea)
@ -134,12 +132,37 @@ memory interface mentioned in the previous section!
It will clean your irrigated farms too, so consider yourself It will clean your irrigated farms too, so consider yourself
warned. warned.
* dfincremental - incremental search utility. * incremental - incremental search utility.
* bauxite - converts all mechanisms into bauxite mechanisms. * bauxite - converts all mechanisms into bauxite mechanisms.
* itemdesignator - Allows mass-designating items by type and material - dump, * itemdesignator - Allows mass-designating items by type and material - dump,
forbid, melt and set on fire ;) 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 Memory offset definitions

@ -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 ~