Add initial README

README.md

@@ -0,0 +1,158 @@
+# Wrenpp #
+
+Wrenpp is a lightweight C++ wrapper for the official [Wren](http://wren.io/) C
+library. It aims to package all the features accessible through the C API in a
+modern C++ interface that is easy to use, while keeping the overhead to a
+minimum.
+
+* [Building](#building)
+	* [Wrenpp](#wrenpp)
+	* [Wren only](#wren-only)
+* [Usage](#usage)
+	* [Meson](#meson)
+	* [C++](#c)
+		* [Header files](#header-files)
+		* [Initialisation](#initialisation)
+
+## Building ##
+
+### Wrenpp ###
+
+You can make a release build like this:
+
+```bash
+mkdir build
+cd build
+meson setup -Dbuildtype=release ..
+ninja
+```
+
+The build scripts understand the following options (double check in
+`meson_options.txt`):
+
+1. `build_testing` set to true to compile Wren's unit tests too
+2. `build_examples` set to true to include examples from the `examples/`
+   directory in the build
+3. `wren_with_cli` set to false to exclude the command line tool from the Wren
+   subproject build
+4. `wren_with_rand` set to true to compile Wren with
+   [random](http://wren.io/modules/random/) support
+5. `wren_with_meta` set to true to compile Wren with
+   [meta](http://wren.io/modules/meta/) support
+
+Note that some example projects require random support in Wren, without which
+they will crash. If you want to run examples or you are getting "Address
+boundary error" segfaults recompile Wrenpp after enabling the example and/or
+meta options:
+
+```
+mkdir build
+cd build
+meson setup -Dbuildtype=debug -Dbuild_examples=true -Dwren_with_rand=true -Dwren_with_meta=true ..
+ninja
+```
+
+### Wren only ###
+
+If you only want to compile the C library of Wren, of course you can do that:
+
+```
+mkdir build
+cd build
+meson setup -Dbuildtype=release -Dwren_with_rand=true -Dwren_with_meta=true ../subprojects/wren
+ninja
+```
+
+This will build Wren as a shared object. If you want a static library instead
+you can add the `-Ddefault_library=static` parameter to your Meson command, or
+`-Ddefault_library=both` if you want tboth the shared and the static version of
+Wren.
+
+## Usage ##
+
+### Meson ###
+
+You can use Wrenpp as a Meson
+[subproject](https://mesonbuild.com/Reference-manual.html#subproject) like you
+would do normally. For example:
+
+```
+wrenpp = subproject('wrenpp', default_options: ['wren_with_rand=true'])
+wrenpp_dep = wrenpp.get_variable('wrenpp_dep')
+
+executable('my_project',
+  'main.cpp',
+  dependencies: wrenpp_dep,
+)
+```
+
+This will make Wrenpp build as part of your project with Wren's optional random
+module enabled.
+
+Alternatively you can use the subproject as a fallback if there is no Wrenpp
+installed in your system already:
+
+```
+wrenpp_dep = dependency('wrenpp', version: '>=0.1.0',
+  fallback: ['wrenpp', 'wrenpp_dep'],
+  default_options: ['wren_with_rand=true'],
+)
+```
+
+Note that when you use Wrenpp as a subproject, Wrenpp's subproject Wren will
+become a sub-subproject of your project. This is how Meson works and it simply
+means that in your top level source directory you will have to run this command
+before you will be able to compile (Meson should detect and print this as
+well):
+
+```
+meson wrap promote subprojects/wrenpp/subprojects/wren
+```
+
+### C++ ###
+
+For working examples refer to the source files in the `examples/` directory.
+
+#### Header files ####
+
+In order to use Wrenpp in your project you will need to include `wrenpp/vm.hpp`
+at least. A description of all the relevant header files follows:
+
+* `vm.hpp` The `VM` class provides simple wrappers around the C API functions.
+  It wraps and hides the `WrenVM` pointer and provides RAII around it.
+  Available methods aim to be as close to their C counterparts as possible. You
+  can use objects of this class in a way that mirrors very closely the way you
+  would use the C API.
+* `vm_fun.hpp` This header provides functions on top of the `VM` class. Their
+  goal is to make common operations easier and more compact in your code.
+* `def_configuration.hpp` The `DefConfiguration` struct extends the bare
+  `Configuration` struct by providing an implementation for `write_fn`,
+  `error_fn` and `reallocate_fn`. They are implemented in terms of `std::cout`,
+  `std::cerr` and `new[]`/`delete[]` respectively. You can safely ignore this
+  header if this is not suitable for your project.
+
+Other header files are intended for Wrenpp's use and you shouldn't need to use
+them. You are free to use them in your project if you think the code inside is
+useful to you, however keep in mind that those are not providing core Wrenpp
+functionalities and may be removed or modified in the future.
+
+
+#### Initialisation ####
+
+Wrenpp aims to make your code as clear and concise as possible. To instantiate
+a `VM` (which wraps `WrenVM`) and run a simple script you can do the following:
+
+```
+#include <wrenpp/vm.hpp>
+#include <wrenpp/def_configuration.hpp>
+
+int main() {
+	wren::DefConfiguration config;
+	wren::VM vm(&config, nullptr);
+
+	vm.interpret("main", "System.print(\"Hello world!\")");
+	return 0;
+}
+```
+
+*Work in progress*