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