From 0454dc6ab7cdf9370a06a95419a4412b9c212ea8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Petr=20Mr=C3=A1zek?= Date: Sun, 25 Jul 2010 10:03:47 +0200 Subject: [PATCH] Removed old README and COMPILE files, added rst->html bash script that uses docutils --- COMPILE | 156 -------------- Compile.html | 506 ++++++++++++++++++++++++++++++++++++++++++++ README | 179 ---------------- README.rst | 4 +- Readme.html | 586 +++++++++++++++++++++++++++++++++++++++++++++++++++ fixTexts.sh | 3 + 6 files changed, 1097 insertions(+), 337 deletions(-) delete mode 100644 COMPILE create mode 100644 Compile.html delete mode 100644 README create mode 100644 Readme.html create mode 100755 fixTexts.sh diff --git a/COMPILE b/COMPILE deleted file mode 100644 index b37080dcd..000000000 --- a/COMPILE +++ /dev/null @@ -1,156 +0,0 @@ -Here's how you build dfhack! ----------------------------- - -Dependencies -============ - -You'll need cmake and 'a' compiler for building the main lib and the various tools. -(Linux only) Veinlook requires the wide-character ncurses library (libncursesw) -(Linux only) You'll need X11 dev libraries. - -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! - -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. -Try using a different cmake generator that's intended for your tools. - -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 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 an useful build types include 'Release', 'Debug' and 'RelWithDebInfo'. -There are others, but they aren't really that useful. - -Have fun. - -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 31.01 - 31.10 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 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 - -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 most probably lost. diff --git a/Compile.html b/Compile.html new file mode 100644 index 000000000..1e4180548 --- /dev/null +++ b/Compile.html @@ -0,0 +1,506 @@ + + + + + + +Compiling DFHACK + + + +
+

Compiling DFHACK

+

Here's how you build dfhack!

+ + +
+

Dependencies

+
    +
  • cmake
    • +
  • A compiler for building the main lib and the various tools.
    • +
  • (Linux only) Veinlook requires the wide-character ncurses library (libncursesw)
    • +
  • (Linux only) You'll need X11 dev libraries.
    • +
+
+
+

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: http://www.mingw.org/

+

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

+

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!

+
+

Also, 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.

+

Try using a different cmake generator that's intended for your tools.

+
+
+
+

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 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 an useful build types include 'Release', 'Debug' and +'RelWithDebInfo'. There are others, but they aren't really that useful.

+

Have fun.

+
+
+

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 31.01 - 31.10 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 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
+
+

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 most probably lost.

+
+
+ + diff --git a/README b/README deleted file mode 100644 index 5a574482c..000000000 --- a/README +++ /dev/null @@ -1,179 +0,0 @@ -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, for both source and binaries: - http://github.com/peterix/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 :) - -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 - 0.31.01 - 0.31.03 legacy - 0.31.04 - 0.31.10 SDL - -* Linux - 0.31.04 - 0.31.10 native. - There are missing offsets but Map tools should be OK. Linux support is a bit lacking, I'm working on it. - All supported Windows versions running in wine can be used with DFHack. - -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. - -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 (and getting better all the time). - -Contributing to DFHack ----------------------- - -Several things should be kept in mind when contributing to DFHack. - -**** Coding style **** - -DFhack uses ANSI formatting and four spaces as indentation. Line endings are -UNIX. The files use UTF-8 encoding. Code not following this won't make me happy, -because I'll have to fix it. There's a good chance I'll make *you* fix it ;) - -**** How to get new code into DFHack **** - -You can send patches or make a clone of the github repo and ask me on the -IRC channel to pull your code in. I'll review it and see if there are any -problems. I'll fix them if they are minor. - -Fixes are higher in priority. If you want to work on something, but don't -know what, check out http://github.com/peterix/dfhack/issues -- this is also -a good place to dump new ideas and/or bugs that need fixing. - -**** Layout for tools **** - -Tools live in the tools/ folder. There, they are split into three categories: - -distributed: these tools get distributed with binary releases and are installed - by doing 'make install' on linux. They are supposed to be stable - and supported. Experimental, useless, buggy or untested stuff - doesn't belong here. -examples : examples are tools that aren't very useful, but show how DF - and DFHack work. They should use only DFHack API functions. - No actual hacking or 'magic offsets' are allowed. -playground : This is a catch-all folder for tools that aren't ready to be - examples or be distributed in binary releases. All new tools - should start here. They can contain actual hacking, magic values - and other nasty business. - -**** Modules - what are they? **** - -DFHack uses modules to partition sets of features into manageable chunks. -A module can have both client and server side. - -Client side is the part that goes into the main library and is generally -written in C++. It is exposed to the users of DFHack. - -Server side is used inside DF and serves to accelerate the client modules. -This is written mostly in C style. - -There's a Core module that shouldn't be changed, because it defines -the basic commands like reading and writing raw data. The client parts -for the Core module are the various implementations of the Process -interface. - -A good example of a module is Maps. Named the same in both client and -server, it allows accelerating the reading of map blocks. - -Communication between modules happens by using shared memory. This is -pretty fast, but needs quite a bit of care to not break. - -**** Dependencies **** - -Internal : either part of the codebase or statically linked. -External : linked as dynamic loaded libraries (.dll, .so, etc.) - -If you want to add dependencies, think twice about it. All internal dependencies -for core dfhack should be either public domain or require attribution at most. -External dependencies for tools can be either that, or any Free Software -licenses. - -** Current internal dependencies ** - -tinyxml : used by core dfhack to read offset definitions from Memory.xml -md5 : an implementation of the MD5 hash algorithm. Used for identifying - DF binaries on Linux. -argstream: Allows reading terminal application arguments. GPL! - -** Current external dependencies ** - -wide-character ncurses : used for the veinlook tool on Linux. -x11 libraries : used for sending key events on linux - -** Build-time dependencies ** -cmake: you need cmake to generate the build system and some configuration - headers - - -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. - - - dfcleanmap : Cleans all the splatter that get scattered all over the map. - Only exception is mud. It leaves mud alone. - - dfexpbench : Just a simple benchmark of the data export speed. - - dfliquids : A command prompt for liquid creation and manipulation - (the Moses effect included!) - Also allows painting obsidian walls directly. - Note: - Spawning and deleting liquids can F up pathing data and - temperatures (creating heat traps). You've been warned. - - dfposition : Prints the current DF window properties and cursor position. - - dfprospector: Lists all available minerals on the map and how much - of them there is. - - dfreveal : Reveals the whole map, waits for input and hides it again. - If you close the tool while it waits, the map remains revealed. - - dfsuspend : Test of the process suspend/resume mechanism. - - dfunstuck : Use if you prematurely close any of the tools and DF - appears to be stuck. - - dfvdig : Designates a whole vein for digging. Point the cursor at a vein - and run this thing :) - - - dfflows : A tool for checking how many liquid tiles are actively checked - for flows. - - Your tool here: Write one ;) - - -Memory offset definitions -------------------------- - -The file with memory offset definitions used by dfhack can be found in the -output folder. - -~ EOF ~ diff --git a/README.rst b/README.rst index d94bc3e75..b2a4541e1 100644 --- a/README.rst +++ b/README.rst @@ -45,11 +45,11 @@ Windows fix it :) 0.31.01 - 0.31.03 legacy -0.31.04 - 0.31.10 SDL +0.31.04 - 0.31.11 SDL Linux ===== -0.31.04 - 0.31.10 native. +0.31.04 - 0.31.11 native. There are missing offsets but Map tools should be OK. Linux support is a bit lacking, I'm working on it. All supported Windows versions running in wine can be used with DFHack. diff --git a/Readme.html b/Readme.html new file mode 100644 index 000000000..f13661541 --- /dev/null +++ b/Readme.html @@ -0,0 +1,586 @@ + + + + + + + + + + +
+ + +
+

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, for both source and +binaries at http://github.com/peterix/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 :)

+
+
+
+

Compatibility

+

DFHack works on Windows XP, Vista, 7 or any modern Linux distribution.

+

OSX is not supported due to lack of developers with a Mac.

+

Currently supported Dwarf Fortress versions are Windows and Linux.

+
+

Windows

+
+

Note

+

Windows 2000 is currently not supported due to missing OS +functionality. If you know how to easily suspend processes, you can +fix it :)

+
+

0.31.01 - 0.31.03 legacy +0.31.04 - 0.31.11 SDL

+
+
+

Linux

+

0.31.04 - 0.31.11 native. +There are missing offsets but Map tools should be OK. Linux support is +a bit lacking, I'm working on it. All supported Windows versions +running in wine can be used with DFHack.

+
+
+
+

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.

+
+

dfcleanmap

+

Cleans all the splatter that get scattered all over the map. +Only exception is mud. It leaves mud alone.

+
+
+

dfexpbench

+

Just a simple benchmark of the data export speed.

+
+
+

dfliquids

+

A command prompt for liquid creation and manipulation (the Moses +effect included!) Also allows painting obsidian walls directly.

+
+

Note

+

Spawning and deleting liquids can F up pathing data and +temperatures (creating heat traps). You've been warned.

+
+
+
+

dfposition

+

Prints the current DF window properties and cursor position.

+
+
+

dfprospector

+

Lists all available minerals on the map and how much of them there is.

+
+
+

dfreveal

+

Reveals the whole map, waits for input and hides it again. If you close +the tool while it waits, the map remains revealed.

+
+
+

dfsuspend

+

Test of the process suspend/resume mechanism.

+
+
+

dfunstuck

+

Use if you prematurely close any of the tools and DF appears to be +stuck.

+
+
+

dfvdig

+

Designates a whole vein for digging. Point the cursor at a vein and run +this thing :)

+
+
+

dfflows

+

A tool for checking how many liquid tiles are actively checked for +flows.

+
+
+

Your tool here

+

Write one ;)

+
+
+
+

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.

+

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 (and getting better all the +time).

+
+

Contributing to DFHack

+

Several things should be kept in mind when contributing to DFHack.

+
+

Coding style

+

DFhack uses ANSI formatting and four spaces as indentation. Line +endings are UNIX. The files use UTF-8 encoding. Code not following this +won't make me happy, because I'll have to fix it. There's a good chance +I'll make you fix it ;)

+
+
+

How to get new code into DFHack

+

You can send patches or make a clone of the github repo and ask me on +the IRC channel to pull your code in. I'll review it and see if there +are any problems. I'll fix them if they are minor.

+

Fixes are higher in priority. If you want to work on something, but +don't know what, check out http://github.com/peterix/dfhack/issues -- +this is also a good place to dump new ideas and/or bugs that need +fixing.

+
+
+

Layout for tools

+

Tools live in the tools/ folder. There, they are split into three +categories.

+
+
distributed
+
these tools get distributed with binary releases and are installed +by doing 'make install' on linux. They are supposed to be stable +and supported. Experimental, useless, buggy or untested stuff +doesn't belong here.
+
examples
+
examples are tools that aren't very useful, but show how DF and +DFHack work. They should use only DFHack API functions. No actual +hacking or 'magic offsets' are allowed.
+
playground
+
This is a catch-all folder for tools that aren't ready to be +examples or be distributed in binary releases. All new tools should +start here. They can contain actual hacking, magic values and other +nasty business.
+
+
+
+

Modules - what are they?

+

DFHack uses modules to partition sets of features into manageable +chunks. A module can have both client and server side.

+

Client side is the part that goes into the main library and is +generally written in C++. It is exposed to the users of DFHack.

+

Server side is used inside DF and serves to accelerate the client +modules. This is written mostly in C style.

+

There's a Core module that shouldn't be changed, because it defines the +basic commands like reading and writing raw data. The client parts for +the Core module are the various implementations of the Process +interface.

+

A good example of a module is Maps. Named the same in both client and +server, it allows accelerating the reading of map blocks.

+

Communication between modules happens by using shared memory. This is +pretty fast, but needs quite a bit of care to not break.

+
+
+

Dependencies

+
+
Internal
+
either part of the codebase or statically linked.
+
External
+
linked as dynamic loaded libraries (.dll, .so, etc.)
+
+

If you want to add dependencies, think twice about it. All internal +dependencies for core dfhack should be either public domain or require +attribution at most. External dependencies for tools can be either +that, or any Free Software licenses.

+
+

Current internal dependencies

+
+
tinyxml
+
used by core dfhack to read offset definitions from Memory.xml
+
md5
+
an implementation of the MD5 hash algorithm. Used for identifying +DF binaries on Linux.
+
argstream
+
Allows reading terminal application arguments. GPL!
+
+
+
+

Current external dependencies

+
+
wide-character ncurses
+
used for the veinlook tool on Linux.
+
x11 libraries
+
used for sending key events on linux
+
+
+
+

Build-time dependencies

+
+
cmake
+
you need cmake to generate the build system and some configuration +headers
+
+
+
+
+
+
+

Memory offset definitions

+

The file with memory offset definitions used by dfhack can be found in the +output folder.

+
+
+ + diff --git a/fixTexts.sh b/fixTexts.sh new file mode 100755 index 000000000..30ee0c52c --- /dev/null +++ b/fixTexts.sh @@ -0,0 +1,3 @@ +#!/bin/bash +rst2html README.rst > Readme.html +rst2html COMPILE.rst > Compile.html