Update readme and fix up some build system problems

develop
Petr Mrázek 2010-03-26 12:20:30 +01:00
parent 0560ce66aa
commit 02b7d92135
4 changed files with 141 additions and 84 deletions

@ -5,6 +5,18 @@ First, there is one dependency, regardless of the OS you use:
cmake - it's the build system
Dependencies
============
You'll need cmake and 'a' compiler for building the main lib and the various tools.
To build the libdfconnect on Linux, you'll have to make a 32bit build.
To build the fake SDL.dll on Windows, you'll have to use MSVC 2008 Express and make
a Release or RelWithDebInfo build.
The python bindings require SWIG and the python devel libs for building.
(Linux only) Veinlook requires the wide-character ncurses library (libncursesw)
Building on Linux:
--------------------
@ -36,9 +48,11 @@ 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
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:
@ -51,16 +65,22 @@ You'll have to add C:\MinGW\ to your PATH variable.
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
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!
Alo, 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:
I'm afraid you are on your own. dfhack wasn't tested with any other compiler.
@ -70,19 +90,22 @@ 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.
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.
For DF 40d15 - 40d19_2 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!
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
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]
@ -104,26 +127,30 @@ Example of (a part of a) relevant output from a working SHM installation:
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.
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.
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.
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.
Build targets
-------------
dfhack has a few build targets. If you're only after the library run 'make dfhack'.
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.
'make expbench' will build the expbench testing program and the library.
Build types
-----------
@ -132,7 +159,9 @@ cmake allows you to pick a build type by changing this variable: CMAKE_BUILD_TYP
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.
Without specifying a build type or 'None', cmake uses the CMAKE_CXX_FLAGS
variable for building.
Valid an useful build types include 'Release', 'Debug' and 'RelWithDebInfo'.
There are others, but they aren't really that useful.
Have fun.

103
README

@ -8,16 +8,31 @@ 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:
The project is currently hosted on github, for both source and binaries:
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
* Packages
The library and tools are packaged for Archlinux and are available both in AUR
and the arch-games repository.
The package name is dfhack-git :)
Clarification
-------------
'fake SDL.dll', 'SHM', 'libdfconnect' and 'shim library' are basically the same
thing. A library that sits between DFHack and DF, provides some extra features,
synchronisation and access control. You should use it for everything that writes
data back to DF.
You'll need the SHM to attach more than one tool to DF on Linux.
The DFHack version of Dwarf Therapist requires it for writing creature names
and professions.
See 'Using DFHack Tools' for instructions on installing it.
Compatibility
-------------
@ -31,15 +46,20 @@ OSX is also not supported due to lack of developers with a Mac.
Currently supported Dwarf Fortress versions:
* Windows
40d
40d9 - 40d18
38a - 40d19_2
* Linux
40d9 - 40d18
40d2 - 40d19
Currently supported DF versions *by the SHM*:
* Windows
40d15 - 40d19
Using the library
-----------------
* Linux
40d9 - 40d19 (40d2 - 40d8 might work, but are untested)
Using the library as a developer
--------------------------------
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.
@ -49,7 +69,7 @@ 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.
have a lot of comments though (and getting better all the time).
Using DFHack Tools
@ -61,8 +81,8 @@ 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.
!!! on Windows this currently only works with DF 40d15 - 40d19_2 !!!
On Linux, it works with DF 40d9 - 40d19
!!! use the pre-compiled library intended for your OS and version of DF !!!
You can find them in the 'precompiled' folder.
@ -83,28 +103,13 @@ to DF is questionable.
** 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! :)
- copy the df-hacked script to your DF folder
- Use this new startup script to start DF
** Replacing libdfconnect.so
- Make sure you close DF before you replace this file! DF crashes whn you don't
close it first!
** Uninstalling on Linux
- Open your DF and DF/libs folders
- Delete libdfconnect.so and the dfhacked startup script
@ -121,9 +126,16 @@ 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!
* catsplosion- Makes all cats pregnant and due in 100 game steps. Use with care.
* magma_create - creates 7/7 magma at the DF's cursor
* reveal - plain old reveal tool. It reveals all the map blocks already
initialized by DF.
* veinlook - a silly map viewer. It can mass-dig veins in a map square.
(Linux only)
* 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')
@ -132,7 +144,7 @@ memory interface mentioned in the previous section!
It will clean your irrigated farms too, so consider yourself
warned.
* incremental - incremental search utility.
* incrementalsearch - incremental search utility (Linux only).
* bauxite - converts all mechanisms into bauxite mechanisms.
@ -150,16 +162,17 @@ memory interface mentioned in the previous section!
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
8 = RAMP_TOP
9 = FLOOR
10 = TREE_DEAD
11 = TREE_OK
12 = SAPLING_DEAD
13 = SAPLING_OK
14 = SHRUB_DEAD
15 = SHRUB_OK
16 = BOULDER
17 = 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.

@ -29,7 +29,8 @@ TARGET_LINK_LIBRARIES(dfmaterialtest dfhack)
ADD_EXECUTABLE(dfposition position.cpp)
TARGET_LINK_LIBRARIES(dfposition dfhack)
# suspendtest - test if suspend works. df should stop responding when suspended by dfhack
# suspendtest - test if suspend works. df should stop responding when suspended
# by dfhack
ADD_EXECUTABLE(dfsuspend suspendtest.cpp)
TARGET_LINK_LIBRARIES(dfsuspend dfhack)
@ -44,8 +45,8 @@ TARGET_LINK_LIBRARIES(dfhotkeynotedump dfhack)
# findnameindexes
# Author: belal
ADD_EXECUTABLE(dffindnameindexes findnameindexes.cpp)
TARGET_LINK_LIBRARIES(dffindnameindexes dfhack)
#ADD_EXECUTABLE(dffindnameindexes findnameindexes.cpp)
#TARGET_LINK_LIBRARIES(dffindnameindexes dfhack)
# settlementdump - dumps the settlements on the loaded map
# Author: belal
@ -53,8 +54,8 @@ ADD_EXECUTABLE(dfsettlementdump settlementdump.cpp)
TARGET_LINK_LIBRARIES(dfsettlementdump dfhack)
# veccheck - read vector values at address
ADD_EXECUTABLE(dfvecc veccheck.cpp)
TARGET_LINK_LIBRARIES(dfvecc dfhack)
#ADD_EXECUTABLE(dfvecc veccheck.cpp)
#TARGET_LINK_LIBRARIES(dfvecc dfhack)
# catsplosion - Makes every cat pregnant, and almost due...
# Author: Zhentar
@ -97,21 +98,27 @@ IF(UNIX)
ENDIF(CURSES_FOUND)
ENDIF(UNIX)
# renamer - change the custom names and professions of creatures, sends keys to df directly
# renamer - change the custom names and professions of creatures, sends keys to
# df directly
# Author: belal
ADD_EXECUTABLE(dfrenamer renamer.cpp)
TARGET_LINK_LIBRARIES(dfrenamer dfhack)
IF(UNIX)
install(TARGETS
dfattachtest
dfbuildingsdump
dfcreaturedump
dfitemdump
dfexpbench
dfcreaturedump
dfbuildingsdump
dfmaterialtest
dfposition
dfrenamer
dfsuspend
dfitemdump
dfhotkeynotedump
#dffindnameindexes
dfsettlementdump
dfrenamer
#dfvecc
dfcatsplosion
RUNTIME DESTINATION bin
)

@ -17,9 +17,12 @@ TARGET_LINK_LIBRARIES(dfprospector dfhack)
ADD_EXECUTABLE(dfcleanmap cleanmap.cpp)
TARGET_LINK_LIBRARIES(dfcleanmap dfhack)
# incrementalsearch - a bit like cheat engine, only DF-specific and very basic
IF(UNIX)
# incrementalsearch - a bit like cheat engine, only DF-specific, very basic
# and Linux-only
ADD_EXECUTABLE(dfincremental incrementalsearch.cpp)
TARGET_LINK_LIBRARIES(dfincremental dfhack)
ENDIF(UNIX)
# bauxite - turn all mechanisms into bauxite mechanisms
# Author: Alex Legg
@ -31,22 +34,27 @@ TARGET_LINK_LIBRARIES(dfbauxite dfhack)
ADD_EXECUTABLE(dfdigger digger.cpp)
TARGET_LINK_LIBRARIES(dfdigger dfhack)
# itemdesignator - change some item designations (dump, forbid, on-fire) for all items of a given type and material
# itemdesignator - change some item designations (dump, forbid, on-fire) for all
# items of a given type and material
# Author: belal
ADD_EXECUTABLE(dfitemdesignator itemdesignator.cpp)
TARGET_LINK_LIBRARIES(dfitemdesignator dfhack)
# a magma creation toold
# a magma creation tool
# Author: Aleric
ADD_EXECUTABLE(dfmagma_create magma_create.cpp)
TARGET_LINK_LIBRARIES(dfmagma_create dfhack)
IF(UNIX)
install(TARGETS
dfreveal
dfprospector
dfbauxite
dfcleanmap
dfdigger
dfincremental
dfbauxite
dfitemdesignator
dfmagma_create
dfprospector
dfreveal
RUNTIME DESTINATION bin
)
ENDIF(UNIX)