# 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()`.