Updated README with some basic development guidelines

develop
Petr Mrázek 2010-05-26 00:33:20 +02:00
parent 863eb2546f
commit 39f0eb29aa
1 changed files with 83 additions and 0 deletions

@ -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
-----