From 18e28bd5b64d45145773d0bac7a0fa2a884d4fcc Mon Sep 17 00:00:00 2001 From: King_DuckZ Date: Sun, 3 May 2020 15:17:35 +0200 Subject: [PATCH] Add initial README --- README.md | 158 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2d02e0c --- /dev/null +++ b/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 +#include + +int main() { + wren::DefConfiguration config; + wren::VM vm(&config, nullptr); + + vm.interpret("main", "System.print(\"Hello world!\")"); + return 0; +} +``` + +*Work in progress*