diff --git a/CMakeLists.txt b/CMakeLists.txt index e03a5727a..e4f4a0c5e 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -25,6 +25,7 @@ ENDIF(NOT DEFINED CMAKE_BUILD_TYPE) SET( LIBRARY_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack library" ) SET( EXECUTABLE_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack tools" ) SET( DATA_OUTPUT_PATH ${CMAKE_SOURCE_DIR}/output CACHE PATH "Output directory for the dfhack data (offset files)" ) +SET( DOXYGEN_OUTPUT_DIR ${CMAKE_SOURCE_DIR}/output/doxygen CACHE PATH "Output directory for doxygen") OPTION(BUILD_DFHACK_DOCUMENTATION "Create doxygen documentation for developers" OFF) OPTION(BUILD_DFHACK_EXAMPLES "Build example tools" OFF) diff --git a/COMPILE.rst b/COMPILE.rst index 8e1ec2645..45e1972be 100644 --- a/COMPILE.rst +++ b/COMPILE.rst @@ -26,6 +26,16 @@ is simple. Enter the build folder, run the tools. Like this:: make This will build the library and its tools and place them in ``/output``. + +Alternatively, you can use ccmake instead of cmake: + + cd build + ccmake .. + make + +This will show a curses-based interface that lets you set all of the +extra options. + You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI program. @@ -133,3 +143,124 @@ Valid an useful build types include 'Release', 'Debug' and 'RelWithDebInfo'. There are others, but they aren't really that useful. Have fun. + +================================ +Using the library as a developer +================================ +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 :) + +Rudimentary API documentation can be built using doxygen. + +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 files with memory offset definitions used by dfhack can be found in the +data folder. + diff --git a/Compile.html b/Compile.html index b4a252ccb..8e91e15f2 100644 --- a/Compile.html +++ b/Compile.html @@ -312,28 +312,49 @@ ul.auto-toc {
Contents
To run in the output folder (without installing) building the library is simple. Enter the build folder, run the tools. Like this:
@@ -350,8 +371,15 @@ 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 +
This will build the library and its tools and place them in /output.
+Alternatively, you can use ccmake instead of cmake:
++cd build +ccmake .. +make+
This will show a curses-based interface that lets you set all of the +extra options.
+You can also use a cmake-friendly IDE like KDevelop 4 or the cmake GUI program.
To be installed into the system or packaged:
@@ -370,19 +398,19 @@ make install
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.
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.
open up cmd and navigate to the dfhack\build folder, run cmake:
@@ -410,14 +438,14 @@ by changing cmake configs and running cmake on
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.
dfhack has a few build targets:
If you're only after the library run make dfhack.
@@ -443,7 +471,7 @@ cmake .. -DBUILD_DFHACK_EXAMPLES=ONcmake allows you to pick a build type by changing this variable: CMAKE_BUILD_TYPE
@@ -456,5 +484,119 @@ cmake .. -DCMAKE_BUILD_TYPE:string=BUILD_TYPEHave fun.
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 :)
+Rudimentary API documentation can be built using doxygen.
+Several things should be kept in mind when contributing to DFHack.
+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 ;)
+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.
+Tools live in the tools/ folder. There, they are split into three +categories.
+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.
+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.
+The files with memory offset definitions used by dfhack can be found in the +data folder.
+