|
|
|
@ -50,6 +50,89 @@ 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.
|
|
|
|
|
|
|
|
|
|
Keep the same coding style. DFhack uses ANSI formatting and four spaces as
|
|
|
|
|
indentation. Line endings are UNIX. Code not following this won't make
|
|
|
|
|
me happy, because I'll have to 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
|
|
|
|
|
the place for new ideas.
|
|
|
|
|
|
|
|
|
|
* Layout for tools
|
|
|
|
|
dfhack/ The folder for core dfhack. The libraries are in there.
|
|
|
|
|
tools/ This is used for stable and supported tools. These get distributed
|
|
|
|
|
in binary releases and should be tested.
|
|
|
|
|
examples/ This folder has some examples that show how to use certain parts
|
|
|
|
|
of dfhack.
|
|
|
|
|
playground/ And finally, here should be placed any quick hacks and testing
|
|
|
|
|
tools.
|
|
|
|
|
|
|
|
|
|
Don't put untested or experimental things in tools/.
|
|
|
|
|
|
|
|
|
|
* Layout for core dfhack
|
|
|
|
|
dfhack/ -- the main library lives here
|
|
|
|
|
dfhack/include -- header files for the main library belong here
|
|
|
|
|
dfhack/modules -- source of the client modules goes here
|
|
|
|
|
dfhack/include/modules -- headers for client modules
|
|
|
|
|
dfhack/shm -- the server part along with its modules
|
|
|
|
|
dfhack/python -- folder for the pytthon bindings
|
|
|
|
|
dfhack/depends -- dependencies. an XML parser, an MD5 implementation
|
|
|
|
|
and terminal arguments parser.
|
|
|
|
|
|
|
|
|
|
* 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
|
|
|
|
|
|
|
|
|
|
If you want to add dependencies, think twice about it. All dependencies
|
|
|
|
|
for core dfhack should be either public domain or require attribution
|
|
|
|
|
at most.
|
|
|
|
|
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.
|
|
|
|
|
python 2.6: required for building and using the python bindings.
|
|
|
|
|
|
|
|
|
|
* Build-time dependencies
|
|
|
|
|
|
|
|
|
|
cmake: you need cmake to generate the build system and some configuration
|
|
|
|
|
headers
|
|
|
|
|
|
|
|
|
|
Tools
|
|
|
|
|
-----
|
|
|
|
|