Hare bindings for termbox2

This repository contains hare bindings for the terminal I/O library 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 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().