commit 71b4c6d7b1dafcf229573a6662558c10c64dff4f
parent 1b0fc58f155539dd081b27922c8cc6bce4243541
Author: Drew DeVault <sir@cmpwn.com>
Date: Sat, 16 Jan 2021 15:19:27 -0500
Add initial documentation
Diffstat:
2 files changed, 52 insertions(+), 0 deletions(-)
diff --git a/README.md b/README.md
@@ -0,0 +1,26 @@
+# harec
+
+This is a [Hare](https://harelang.org) compiler written in C11 for
+POSIX-compatible systems.
+
+## Building
+
+```
+mkdir build
+cd build
+../configure
+make
+```
+
+Optionally, build and run the test suite as well:
+
+```
+make check
+```
+
+## Runtime
+
+harec includes a minimal runtime under `rt` which is suitable for running the
+test suite, but not recommended for production use. See `docs/runtime.txt` for
+details on how to provide your own runtime implementation, or use the [Hare
+standard library](https://git.sr.ht/~sircmpwn/stdlib).
diff --git a/docs/runtime.txt b/docs/runtime.txt
@@ -0,0 +1,26 @@
+harec expects the runtime to provide some features under the "rt" namespace.
+
+fn @noreturn rt::abort(msg: str) void
+ Print a diagnostic message and terminate the program.
+
+fn @noreturn rt::abort_fixed(reason: int) void
+ Print a diagnostic message from a list of pre-determined abort reasons,
+ and terminate the program. The list of reasons are:
+
+ 0: Slice or array access out-of-bounds
+ 1: Type assertion failed
+
+The runtime is also expected to provide startup code. A list of function
+pointers of type `fn() void` is provided in the __init_array_start and
+__fini_array_start globals, which are respectively terminated by
+__init_array_end and __fini_array_end. The following Hare code will make these
+globals available to the current unit:
+
+ const @symbol("__init_array_start") init_start: [*]*fn() void;
+ const @symbol("__init_array_end") init_end: [*]*fn() void;
+ const @symbol("__fini_array_start") fini_start: [*]*fn() void;
+ const @symbol("__fini_array_end") fini_end: [*]*fn() void;
+
+The runtime must call each initialization function, then call the `main`
+function (of type `fn() void`), then call all of the finalization functions,
+before terminating the program normally.
