minor liquids bugfix, added typedef for planecoord so that stonesense builds. Build system bits. Doxygen bits.

Author: peterix

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)

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.
+