diff --git a/docs/Contributing.rst b/docs/Contributing.rst index 7ce092a8e..ab92d0571 100644 --- a/docs/Contributing.rst +++ b/docs/Contributing.rst @@ -1,3 +1,5 @@ +.. _contributing: + ########################### How to contribute to DFHack ########################### diff --git a/docs/Dev-intro.rst b/docs/Dev-intro.rst index 6983693e8..b1961378c 100644 --- a/docs/Dev-intro.rst +++ b/docs/Dev-intro.rst @@ -2,41 +2,72 @@ DFHack development overview =========================== -Currently, the most direct way to use the library is to write a script or plugin that can be loaded by it. -All the plugins can be found in the 'plugins' folder. There's no in-depth documentation -on how to write one yet, but it should be easy enough to copy one and just follow the pattern. -``plugins/skeleton/skeleton.cpp`` is provided for this purpose. +DFHack has various components; this page provides an overview of some. If you +are looking to develop a tool for DFHack, developing a script or plugin is +likely the most straightforward choice. -Other than through plugins, it is possible to use DFHack via remote access interface, -or by writing scripts in Lua or Ruby. There are plenty of examples in the scripts folder. -The `lua-api` is quite well documented. +Other pages that may be relevant include: -The most important parts of DFHack are the Core, Console, Modules and Plugins. +- `contributing` +- `documentation` +- `license` -* Core acts as the centerpiece of DFHack - it acts as a filter between DF and - SDL and synchronizes the various plugins with DF. -* Console is a thread-safe console that can be used to invoke commands exported by Plugins. -* Modules actually describe the way to access information in DF's memory. You - can get them from the Core. Most modules are split into two parts: high-level - and low-level. High-level is mostly method calls, low-level publicly visible - pointers to DF's data structures. -* Plugins are the tools that use all the other stuff to make things happen. - A plugin can have a list of commands that it exports and an onupdate function - that will be called each DF game tick. -Rudimentary API documentation can be built using doxygen (see build options -in ``CMakeCache.txt`` or with ``ccmake`` or ``cmake-gui``). The full DFHack -documentation is built with Sphinx_, which runs automatically at compile time. +.. contents:: Contents + :local: -.. _Sphinx: http://www.sphinx-doc.org -DFHack consists of variously licensed code, but invariably weak copyleft. -The main license is zlib/libpng, some bits are MIT licensed, and some are -BSD licensed. See the `license` for more information. +Plugins +------- -Feel free to add your own extensions and plugins. Contributing back to -the DFHack repository is welcome and the right thing to do :) +DFHack plugins are written in C++ and located in the ``plugins`` folder. +Currently, documentation on how to write plugins is somewhat sparse. There are +templates that you can get use to get started in the ``plugins/skeleton`` +folder, and the source code of existing plugins can also be helpful. +If you want to compile a plugin that you have just added, you will need to add a +call to ``DFHACK_PLUGIN`` in ``plugins/CMakeLists.txt``. + +Plugins have the ability to make one or more commands available to users of the +DFHack console. Examples include `3dveins` (which implements the ``3dveins`` +command) and `reveal` (which implements ``reveal``, ``unreveal``, and several +other commands). + +Plugins can also register handlers to run on every tick, and can interface with +the built-in `enable` and `disable` commands. For the full plugin API, see the +skeleton plugins or ``PluginManager.cpp``. + +Scripts +------- + +DFHack scripts can currently be written in Lua or Ruby. The `Lua API ` +is more complete and currently better-documented, however. Referring to existing +scripts as well as the API documentation can be helpful when developing new +scripts. + +DFHack scripts live in a separate `scripts repository `_. +This can be found in the ``scripts`` submodule if you have +`cloned DFHack `, or the ``hack/scripts`` folder +of an installed copy of DFHack. + +Core +---- + +The DFHack core has a variety of low-level functions. It is responsible for +hooking into DF (via SDL), providing a console, and providing an interface +for plugins and scripts to interact with DF. + +Modules +------- + +A lot of shared code to interact with DF in more complicated ways is exposed by +**modules**. For example, the Units module contains functions for checking +various traits of units, changing nicknames properly, and more. Generally, +code that is useful to multiple plugins and scripts should go in the appropriate +module, if there is one. + +Several modules are also `exposed to Lua `, although +some functions (and some entire modules) are currently only available in C++. Remote access interface ----------------------- diff --git a/docs/Lua API.rst b/docs/Lua API.rst index 3e0f22116..4c7163623 100644 --- a/docs/Lua API.rst +++ b/docs/Lua API.rst @@ -802,6 +802,8 @@ Random number generation Dimension may be 1, 2 or 3 (default). +.. _lua-cpp-func-wrappers: + C++ function wrappers =====================