Updated README and COMPILE, split tools into tools and examples.

Tools are now useful, and with a working user interaction where applicable.
Examples are a collection of benchmarks, tests and simple unfinished ideas.

CMakeLists.txt

@@ -29,4 +29,5 @@ include_directories (${CMAKE_SOURCE_DIR}/shmserver/)
 
 add_subdirectory (library)
 add_subdirectory (tools)
+add_subdirectory (examples)
 add_subdirectory (shmserver)

COMPILE

@@ -4,6 +4,7 @@ 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:
 --------------------
 
@@ -30,8 +31,7 @@ library to $CMAKE_INSTALL_PREFIX/lib
 executables to $CMAKE_INSTALL_PREFIX/bin
 The Memory.xml file to /usr/share/dfhack
 
-A special library for adding a shared memory interface to DF is also compiled (libdfconnect.so)
+See the section on the shared memory hook library (SHM).
-It can be put into DF/libs and preloaded using LD_PRELOAD
 
 Building on Windows:
 --------------------
@@ -51,9 +51,6 @@ You'll have to add C:\MinGW\ to your PATH variable.
  cmake .. -G"MinGW Makefiles" -DCMAKE_BUILD_TYPE:string=Release
  mingw32-make
 
-A special library for adding a shared memory interface to DF is also compiled (SDL.dll)
-You can use it with DF by renaming the original SDL.dll to SDLreal.dll and dropping in the newly compiled library.
-
 * Using MSVC
 
 open up cmd and navigate to the dfhack\build folder, run cmake:
@@ -64,22 +61,73 @@ This will generate MSVC solution and project files. Note that: you are working i
 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!
 
-A special library for adding a shared memory interface to DF is also compiled (SDL.dll)
-You can use it with DF by renaming the original SDL.dll to SDLreal.dll and dropping in the newly compiled library.
-
 * 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

README

@@ -1,66 +1,84 @@
 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
+DFHack is a Dwarf Fortress memory access library and a set of basic tools using 
-of new tools.
+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
 ----------------
+
 You can get the code at DFHack's sourceforge site:
   https://sourceforge.net/projects/dfhack/
 
 * subversion access: 
   svn co https://dfhack.svn.sourceforge.net/svnroot/dfhack/trunk dfhack 
 
+It is also available on github:
+  http://github.com/peterix/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
+Windows 2000 is currently *not supported* due to missing OS functionality.
-to easily suspend processes, you can fix it :)
+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 - 40d16
+  40d9 - 40d17
 
 * Linux
-  40d9 - 40d16
+  40d9 - 40d17
+
 
 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
+The library is compilable under Linux with GCC and under Windows with MinGW32
-or add your own extensions. Contributing back to the dfhack repository is welcome and the right
+and MSVC compilers. It is using the cmake build system. See COMPILE for details.
-thing to do :)
+
+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.
 
-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.
 
-!!!!Please not that on Windows this currently only works with DF 40d15 and 40d16!!!!
+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, 40d16 and 40d17 !!!
      On Linux, it works with the whole range of supported DF versions.
 
+!!!     use the pre-compiled library intended for your 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)
+ - Open your DF folder, locate SDL.dll and rename it to SDLreal.dll (making
- - Copy the DFHack SDL.dll into your DF folder.
+   a backup of it is a good idea)
- - Restart DF if it is already running
+ - 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
+ - Rename SDLreal.dll to SDL.dll
  - Restart DF if it is running
 
 
@@ -94,56 +112,40 @@ export LD_PRELOAD="./libs/libdfconnect.so" # Hack DF!
  - 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!
-
-* expbench   - just exports the map 1000 times over. Meant to test how fast the
-               DFHack<->DF interface is. This can take 3-30+ seconds, depending on
-               your system and the size of the map.
 
-* reveal     - plain old reveal tool. Demonstrates writing map data back to DF.
+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.
 
-* prospector - scans the map for minerals. by default it only scans only visible veins.
+If the tool writes back to DF's memory, make sure you are using the shared
-               You can make it show hidden things with '-a' and base rock and soil layers
+memory interface mentioned in the previous section!
-               with '-b'. These can be combined ('-ab')
 
-* cleanmap   - cleans mud, vomit, snow and all kinds of bloody mess from the map. It will
+* reveal     - plain old reveal tool. It reveals all the map blocks already
-               clean your irrigated farms too, so consider yourself warned.
+               initialized by DF.
 
-* dfattachtest - Benchmark for the Attach, Detach, Suspend and Resume functions
+* 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')
 
-* dfbuildingsdump - exports some basic data about buildings of a given type on the game map
+* cleanmap   - cleans mud, vomit, snow and all kinds of mess from the map.
+               It will clean your irrigated farms too, so consider yourself
+               warned.
 
-* dfcreaturedump - exports some basic data about all the dwarves
+* dfincremental - incremental search utility.
 
-* dfcustomCreatureNameProf - allws you to change nicknames and custom professions of your dwarves
+* bauxite - converts all mechanisms into bauxite mechanisms.
 
-* dfincremental - incremental search utility - linux only right now
+* itemdesignator - Allows mass-designating items by type and material - dump,
+                   forbid, melt and set on fire ;)
 
-* dfitemdump - lists items under the current DF cursor (40d16 only)
-
-* dfmaterialtest - tries to load all the material types from DF, shows the first entry of each type
-
-* dfposition - shows you the current view coordinates and window size in tiles
-               (may not be implemented for older DF versions)
-
-* dfsuspend - tests the behavior of Suspend and Resume functions
  
 Memory offset definitions
 -------------------------
-The file with memory offset definitions used by dfhack can be found in the output folder. 
-It uses XML as the base format.
-
-It allows entry versioning and basing newer entries on older ones. These newer versions
-only have to specify the values that are different or a single 'rebase' value that is then
-used as an offset for all the addresses or object identifiers.
 
-This makes it possible to track the small d## releases pretty quickly.
+The file with memory offset definitions used by dfhack can be found in the
+output folder. 
 
 ~ EOF ~

examples/CMakeLists.txt

@@ -0,0 +1,63 @@
+# don't use this file directly. use the one in the root folder of the project
+
+# this is required to ensure we use the right configuration for the system.
+IF(UNIX)
+add_definitions(-DLINUX_BUILD)
+ENDIF(UNIX)
+
+# attachtest - 100x attach/detach, suspend/resume
+ADD_EXECUTABLE(dfattachtest attachtest.cpp)
+TARGET_LINK_LIBRARIES(dfattachtest dfhack)
+
+# a benchmark program, reads the map 1000x
+ADD_EXECUTABLE(dfexpbench expbench.cpp)
+TARGET_LINK_LIBRARIES(dfexpbench dfhack)
+
+# creaturedump - basic creature dump - a test of the creature related exports
+ADD_EXECUTABLE(dfcreaturedump creaturedump.cpp)
+TARGET_LINK_LIBRARIES(dfcreaturedump dfhack)
+
+# buildingsdump - dump buildings and their raw data filtered by type
+ADD_EXECUTABLE(dfbuildingsdump buildingsdump.cpp)
+TARGET_LINK_LIBRARIES(dfbuildingsdump dfhack)
+
+# materialtest - just list the first material of each type
+ADD_EXECUTABLE(dfmaterialtest materialtest.cpp)
+TARGET_LINK_LIBRARIES(dfmaterialtest dfhack)
+
+# position - check the DF window and cursor parameters
+ADD_EXECUTABLE(dfposition position.cpp)
+TARGET_LINK_LIBRARIES(dfposition dfhack)
+
+# suspendtest - test if suspend works. df should stop responding when suspended by dfhack
+ADD_EXECUTABLE(dfsuspend suspendtest.cpp)
+TARGET_LINK_LIBRARIES(dfsuspend dfhack)
+
+# itemdump - dump the item under the cursor
+ADD_EXECUTABLE(dfitemdump dfitemdump.cpp)
+TARGET_LINK_LIBRARIES(dfitemdump dfhack)
+
+# digger - designate for digging by tile class
+# Author: mizipzor
+ADD_EXECUTABLE(dfdigger digger.cpp)
+TARGET_LINK_LIBRARIES(dfdigger dfhack)
+
+# renamer - change the custom names and professions of creatures, sends keys to df directly
+ADD_EXECUTABLE(dfrenamer renamer.cpp)
+TARGET_LINK_LIBRARIES(dfrenamer dfhack)
+
+IF(UNIX)
+install(TARGETS
+dfattachtest
+dfbuildingsdump
+dfcreaturedump
+dfitemdump
+dfdigger
+dfexpbench
+dfmaterialtest
+dfposition
+dfrenamer
+dfsuspend
+RUNTIME DESTINATION bin
+)
+ENDIF(UNIX)

library/DFHackAPI.cpp

@@ -1301,7 +1301,7 @@ bool API::InitReadItems(uint32_t & numitems)
 }
 bool API::ReadItem (const uint32_t &index, t_item & item)
 {
-    assert (d->buildingsInited && d->itemsInited); //should change to the generic init rather than buildings
+    assert (d->itemsInited); //should change to the generic init rather than buildings
     t_item_df40d item_40d;
 
     // read pointer from vector at position

tools/CMakeLists.txt

@@ -5,10 +5,6 @@ IF(UNIX)
 add_definitions(-DLINUX_BUILD)
 ENDIF(UNIX)
 
-# a benchmark program, reads the map 1000x
-ADD_EXECUTABLE(dfexpbench expbench.cpp)
-TARGET_LINK_LIBRARIES(dfexpbench dfhack)
-
 # a reveal clone
 ADD_EXECUTABLE(dfreveal reveal.cpp)
 TARGET_LINK_LIBRARIES(dfreveal dfhack)
@@ -21,75 +17,27 @@ TARGET_LINK_LIBRARIES(dfprospector dfhack)
 ADD_EXECUTABLE(dfcleanmap cleanmap.cpp)
 TARGET_LINK_LIBRARIES(dfcleanmap dfhack)
 
-# creaturedump - basic creature dump - a test of the creature related exports
+# incrementalsearch - a bit like cheat engine, only DF-specific and very basic
-ADD_EXECUTABLE(dfcreaturedump creaturedump.cpp)
-TARGET_LINK_LIBRARIES(dfcreaturedump dfhack)
-
-# buildingsdump - dump buildings and their raw data filtered by type
-ADD_EXECUTABLE(dfbuildingsdump buildingsdump.cpp)
-TARGET_LINK_LIBRARIES(dfbuildingsdump dfhack)
-
-
-# attachtest - 100x attach/detach, 100x reads, 100x writes
-ADD_EXECUTABLE(dfattachtest attachtest.cpp)
-TARGET_LINK_LIBRARIES(dfattachtest dfhack)
-
-# materialtest - just list the first material of each type
-ADD_EXECUTABLE(dfmaterialtest materialtest.cpp)
-TARGET_LINK_LIBRARIES(dfmaterialtest dfhack)
-
-# materialtest - just list the first material of each type
-ADD_EXECUTABLE(dfposition position.cpp)
-TARGET_LINK_LIBRARIES(dfposition dfhack)
-
-#currently only stable on linux
-IF(UNIX)
-    # incremental - incremental memory search tool, a foreshadowing of the future direction of dfhack
 ADD_EXECUTABLE(dfincremental incrementalsearch.cpp)
 TARGET_LINK_LIBRARIES(dfincremental dfhack)
-ENDIF(UNIX)
-
-# suspendtest - test if suspend works. df should stop responding when suspended by dfhack
-ADD_EXECUTABLE(dfsuspend suspendtest.cpp)
-TARGET_LINK_LIBRARIES(dfsuspend dfhack)
-
-# itemdump - dump the item under the cursor
-ADD_EXECUTABLE(dfitemdump dfitemdump.cpp)
-TARGET_LINK_LIBRARIES(dfitemdump dfhack)
 
 # bauxite - turn all mechanisms into bauxite mechanisms
 # Author: Alex Legg
 ADD_EXECUTABLE(dfbauxite dfbauxite.cpp)
 TARGET_LINK_LIBRARIES(dfbauxite dfhack)
 
-# digger - designate for digging by tile class
-# Author: mizipzor
-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
 ADD_EXECUTABLE(dfitemdesignator itemdesignator.cpp)
 TARGET_LINK_LIBRARIES(dfitemdesignator dfhack)
 
-# customCtreatureNameProf - change the custom names and professions of creatures, sends keys to df directly
-ADD_EXECUTABLE(dfcustomCreatureNameProf customCreatureNameProf.cpp)
-TARGET_LINK_LIBRARIES(dfcustomCreatureNameProf dfhack)
-
 IF(UNIX)
 install(TARGETS
-dfexpbench
-dfreveal
 dfreveal
 dfprospector
 dfcleanmap
-dfcreaturedump
-dfattachtest
-dfmaterialtest
-dfbuildingsdump
-dfposition
 dfincremental
-dfitemdump
+dfbauxite
-dfsuspend
+dfitemdesignator
 RUNTIME DESTINATION bin
 )
 ENDIF(UNIX)