From 054fec0afc43146028a9154c37e2e0eb8f56f302 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Mr=C3=A1zek?= Date: Tue, 16 Feb 2010 07:21:38 +0100 Subject: [PATCH] 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 | 1 + COMPILE | 64 +++++++-- README | 126 +++++++++--------- examples/CMakeLists.txt | 63 +++++++++ {tools => examples}/attachtest.cpp | 0 {tools => examples}/buildingsdump.cpp | 0 {tools => examples}/creaturedump.cpp | 0 {tools => examples}/dfitemdump.cpp | 0 {tools => examples}/digger.cpp | 0 {tools => examples}/expbench.cpp | 0 {tools => examples}/materialtest.cpp | 0 {tools => examples}/position.cpp | 0 .../renamer.cpp | 0 {tools => examples}/suspendtest.cpp | 0 library/DFHackAPI.cpp | 2 +- tools/CMakeLists.txt | 62 +-------- 16 files changed, 190 insertions(+), 128 deletions(-) create mode 100644 examples/CMakeLists.txt rename {tools => examples}/attachtest.cpp (100%) rename {tools => examples}/buildingsdump.cpp (100%) rename {tools => examples}/creaturedump.cpp (100%) rename {tools => examples}/dfitemdump.cpp (100%) rename {tools => examples}/digger.cpp (100%) rename {tools => examples}/expbench.cpp (100%) rename {tools => examples}/materialtest.cpp (100%) rename {tools => examples}/position.cpp (100%) rename tools/customCreatureNameProf.cpp => examples/renamer.cpp (100%) rename {tools => examples}/suspendtest.cpp (100%) diff --git a/CMakeLists.txt b/CMakeLists.txt index ea6b29e8a..81a20e745 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -29,4 +29,5 @@ include_directories (${CMAKE_SOURCE_DIR}/shmserver/) add_subdirectory (library) add_subdirectory (tools) +add_subdirectory (examples) add_subdirectory (shmserver) \ No newline at end of file diff --git a/COMPILE b/COMPILE index 1cdbee429..9e1a2fae0 100644 --- a/COMPILE +++ b/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) -It can be put into DF/libs and preloaded using LD_PRELOAD +See the section on the shared memory hook library (SHM). 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 diff --git a/README b/README index f8ae168a4..15ef9b694 100644 --- a/README +++ b/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 -of new tools. +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 ---------------- + 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 -to easily suspend processes, you can fix it :) +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 - 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 -or add your own extensions. Contributing back to the dfhack repository is welcome and the right -thing to do :) +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. -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!!!! -On Linux, it works with the whole range of supported DF versions. +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) - - Copy the DFHack SDL.dll into your DF folder. - - Restart DF if it is already running + - 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 + - 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. - You can make it show hidden things with '-a' and base rock and soil layers - with '-b'. These can be combined ('-ab') +If the tool writes back to DF's memory, make sure you are using the shared +memory interface mentioned in the previous section! -* cleanmap - cleans mud, vomit, snow and all kinds of bloody mess from the map. It will - clean your irrigated farms too, so consider yourself warned. +* reveal - plain old reveal tool. It reveals all the map blocks already + 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 - -* 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 +* itemdesignator - Allows mass-designating items by type and material - dump, + forbid, melt and set on fire ;) + 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 ~ diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt new file mode 100644 index 000000000..e7c21d9fb --- /dev/null +++ b/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) \ No newline at end of file diff --git a/tools/attachtest.cpp b/examples/attachtest.cpp similarity index 100% rename from tools/attachtest.cpp rename to examples/attachtest.cpp diff --git a/tools/buildingsdump.cpp b/examples/buildingsdump.cpp similarity index 100% rename from tools/buildingsdump.cpp rename to examples/buildingsdump.cpp diff --git a/tools/creaturedump.cpp b/examples/creaturedump.cpp similarity index 100% rename from tools/creaturedump.cpp rename to examples/creaturedump.cpp diff --git a/tools/dfitemdump.cpp b/examples/dfitemdump.cpp similarity index 100% rename from tools/dfitemdump.cpp rename to examples/dfitemdump.cpp diff --git a/tools/digger.cpp b/examples/digger.cpp similarity index 100% rename from tools/digger.cpp rename to examples/digger.cpp diff --git a/tools/expbench.cpp b/examples/expbench.cpp similarity index 100% rename from tools/expbench.cpp rename to examples/expbench.cpp diff --git a/tools/materialtest.cpp b/examples/materialtest.cpp similarity index 100% rename from tools/materialtest.cpp rename to examples/materialtest.cpp diff --git a/tools/position.cpp b/examples/position.cpp similarity index 100% rename from tools/position.cpp rename to examples/position.cpp diff --git a/tools/customCreatureNameProf.cpp b/examples/renamer.cpp similarity index 100% rename from tools/customCreatureNameProf.cpp rename to examples/renamer.cpp diff --git a/tools/suspendtest.cpp b/examples/suspendtest.cpp similarity index 100% rename from tools/suspendtest.cpp rename to examples/suspendtest.cpp diff --git a/library/DFHackAPI.cpp b/library/DFHackAPI.cpp index bb53bb904..4047fc35b 100644 --- a/library/DFHackAPI.cpp +++ b/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 diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt index d99127df4..6a6fa9f95 100644 --- a/tools/CMakeLists.txt +++ b/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 -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) +# incrementalsearch - a bit like cheat engine, only DF-specific and very basic +ADD_EXECUTABLE(dfincremental incrementalsearch.cpp) +TARGET_LINK_LIBRARIES(dfincremental 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 -dfsuspend +dfbauxite +dfitemdesignator RUNTIME DESTINATION bin ) ENDIF(UNIX) \ No newline at end of file