1 files changed, 52 insertions, 0 deletions
diff --git a/Sluift/README.md b/Sluift/README.md
new file mode 100644
index 0000000..ae43846
--- /dev/null
+++ b/Sluift/README.md
@@ -0,0 +1,52 @@
+# Sluift
+
+## Building/Installing
+
+If you have a Lua installed on your system, edit `config.py` to point the build
+to it using the `lua_libdir`, `lua_includedir`, and `lua_libname` (usually 
+only needed on Windows) variables.
+
+In case no Lua installation is found, a bundled Lua version will be used.
+Note that there are several limitations when using the bundled Lua:
+
+- The standalone Sluift binary will not support dynamic loading of modules.
+- The Sluift module will not be built
+
+The standalone executable will be placed into `Sluift/exe`, and the loadable
+Lua module in `Sluift/dll`.
+
+In order to use the Sluift Lua module, make sure it is copied to a location in the
+Lua search path (`LUA_PATH`, or the built-in path). On Linux and Mac OS X, this is
+typically `<LUA_INSTALLPREFIX>/lib/lua/<LUA_VERSION>/`. If `require 'sluift'` fails,
+the error message will give an indication what this path is.
+
+
+## Examples
+
+Example scripts can be found in `Examples/`, and in the Swift tree under
+`Swiften/QA/ScriptedTests`.
+
+## Extending
+
+### Adding support for payloads
+
+To add support for a specific Swiften payload, create a new `LuaElementConvertor`
+in `ElementConvertors/` by inheriting from `GenericLuaElementConvertor`, and register
+it it `LuaElementConvertors.cpp`. The name of the convertor passed in the constructor
+of `GenericLuaElementConvertor` should correspond to the snake case version of the 
+Swiften element it converts. For examples, see the existing convertors in
+`ElementConvertors/`.
+
+When the convertor is registered, you can use it in message bodies, or in get/set
+queries. For example, for the `command` convertor:
+  
+    client:set{to = 'alice@wonderland.lit', query = {_type = 'command', 
+      type = 'execute', node = 'uptime'}}
+
+Optionally, you can add a convenience `set_<type>` shortcut on the client object by
+adding it to the list of `get_set_shortcuts` in `boot.lua`. With such a shortcut, the
+command above can be rewritten as:
+
+    client:set_command{to = 'alice@wonderland.lit', command = {
+      type = 'execute', node = 'uptime'}}
+