From 2e31cbeb70d93bb0f5512064f181990db189d1f6 Mon Sep 17 00:00:00 2001 From: Sebastiano Tronto Date: Sun, 4 Oct 2026 20:02:15 +0200 Subject: Initial commit --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) create mode 100644 README.md (limited to 'README.md') 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()`. -- cgit v1.3