1 files changed, 87 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7620429
--- /dev/null
+++ b/README.md
@@ -0,0 +1,87 @@
+# Hare bindings for termbox2
+
+This repository contains [hare](https://harelang.org) bindings for the
+terminal I/O library [termbox2](https://github.com/termbox/termbox2).
+
+There are some differences between the Hare bindings and the original
+C code, for example the fact that the prefixes `tb_` and `TB_` have been
+replaced by the namespace `termbox2::`. See the haredoc documentation
+in `termbox2/README` for more information.
+
+## Using this library
+
+There are two ways to build termbox2 for this library. Both involve
+building termbox2 as a standalone library or object file, rather than
+including it as a header-only library as one could do in a C program.
+
+### Using the system's termbox2 (default)
+
+This method assumes that termbox2 is already installed as a library
+system-wide, for example by using your OS's package manager or by
+installing it from source using `make install_lib`.
+
+Once termbox2 is installed, you can run `make install`. This will
+copy the hare bindings to `/usr/local/src/hare/third-party/` so that
+you can include them in your Hare project as any other module. Do
+not forget to add the `-ltermbox2` option to build any program that
+uses this library.
+
+To uninstall the bindings, run `make uninstall`.
+
+You can also run `make demos` (or simply `make`) to build the demo
+programs contained in `demo/`, and then you can run them from the
+`build/` folder. For example, to run the `hjkl` demo you can run
+`make && ./build/demo/hjkl`. 
+
+### Using a local termbox2
+
+This method is useful if you just want to experiment with termbox2
+programming in Hare, for example by running and modifying the demos
+in `demo/`, without installing anything system-wide.
+
+To do this, the original library is provided as a
+[git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules)
+in this repository. You can download it with:
+
+```
+git submodule init
+```
+
+(Alternative, you can place the source code for termbox2 in
+`vendor/termbox2`). Then you can build termbox2 locally with
+
+```
+make local
+```
+
+This will directly build all the demo programs from `demo/`, placing
+the resulting binaries in `build/demo`.
+
+Technical note: this will include the compiled termbox object file
+`termbox.o` directly in the compiled binaries.
+
+To build the demo programs using this method, run `make local-demos`.
+
+## Notes on build options
+
+The original termbox2 library offers several build options via `TB_OPT_*`
+constants. Two of them, `TB_OPT_ATTR_W` and `TB_OPT_EGC`, are relevant for
+the API.
+
+* `TB_OPT_ATTR_W` (in the Hare bindings: `termbox2::OPT_ATTR_W`) can be
+either `16`, `32` or `64`, and is used to enable more output attributer
+(e.g. truecolor). The termbox2 sources claim that the default value is
+`16`, but this is only true when including termbox2 as a header-only
+library. When building it as an external library, the default is `64`.
+Since these bindings are meant to be used with termbox2 compiled as an
+external library, we use `64` as default. The hare build tags `attrw16`
+and `attrw32` are offered if one wants to use a different value.
+
+* `TB_OPT_EGC` (in the Hare bindings: `termbox2::OPT_EGC`) can be set or
+not set (in the bindings: it is a boolean value, `true` for set, `false`
+for not set). Similarly to `TB_OPT_ATTR_W`, it is by default set when
+building termbox2 as an external library, unlike when including it as a
+header-only library. An `noegc` tag is available to disable this option.
+
+Note: the consistency of these two build options between the C library
+and the Hare bindings is checked and enforced in `termbox2::init()`.