[hare] Hare compiler, written in C11 for POSIX OSs
Log | Files | Refs | README | LICENSE

runtime.txt (3245B)

      1 harec expects the runtime to provide some features under the "rt" namespace.
      3 @noreturn @symbol("rt.abort") fn _abort(msg: str) void;
      4 	Print a diagnostic message and terminate the program.
      6 @noreturn fn abort_fixed(reason: int) void;
      7 	Print a diagnostic message from a list of pre-determined abort reasons,
      8 	and terminate the program. The list of reasons are:
     10 	0: Slice or array access out-of-bounds
     11 	1: Type assertion failed
     12 	2: Out of memory
     13 	3: Static append exceeds slice capacity
     14 	4: Unreachable code
     16 fn memcpy(dest: *void, src: *void, n: size) void;
     17 	Copy "n" bytes from "src" to "dest". The memory areas shall not
     18 	overlap.
     20 fn memmove(dest: *void, src: *void, n: size) void;
     21 	Copy "n" bytes from "src" to "dest". The memory areas may overlap.
     23 fn memset(dest: *void, val: u8, n: size) void;
     24 	Set "n" bytes, starting from the address at "dest", to "val".
     26 fn strcmp(a: str, b: str) bool;
     27 	Compare strings "a" and "b", returning true of they are equal.
     29 "ensure" and "unensure" are called when slices are expanded or deleted. The
     30 "length" field of the slice will have been updated, and ensure should allocate
     31 or re-allocate the data field to have sufficient space, and update the capacity
     32 field accordingly. "unensure" is called when the space is no longer needed, and
     33 should shrink the allocation as appropriate.
     35 	type slice = struct {
     36 		data: nullable *void,
     37 		length: size,
     38 		capacity: size,
     39 	};
     41 	fn ensure(s: *slice, membsz: size) void;
     42 	fn unensure(s: *slice, membsz: size) void;
     44 "malloc" and "free" are required to support the "alloc" and "free" built-ins.
     46 	fn malloc(n: size) nullable *void;
     48 	@symbol("rt.free") fn free_(_p: nullable *void) void;
     50 The runtime is also expected to provide startup code. A list of function
     51 pointers of type `fn() void` is provided in the __init_array_start and
     52 __fini_array_start globals, which are respectively terminated by
     53 __init_array_end and __fini_array_end. The following Hare code will make these
     54 globals available to the current unit:
     56 	const @symbol("__init_array_start") init_start: [*]*fn() void;
     57 	const @symbol("__init_array_end") init_end: [*]*fn() void;
     58 	const @symbol("__fini_array_start") fini_start: [*]*fn() void;
     59 	const @symbol("__fini_array_end") fini_end: [*]*fn() void;
     61 The runtime must call each initialization function, then call the `main`
     62 function (of type `fn() void`), then call all of the finalization functions,
     63 before terminating the program normally.
     65 When building with +test (harec -T +test), @test functions will be emitted, and
     66 an ELF section, .test_array, will be populated similarly to init_array. The
     67 startup code can enumerate the available tests like so:
     69 	type test = struct {
     70 		name: str,
     71 		func: *fn() void,
     72 	};
     74 	const @symbol("__test_array_start") test_start: [*]test;
     75 	const @symbol("__test_array_end") test_end: [*]test;
     77 In order to use these symbols, a custom linker script must be used. A sample is
     78 provided in rt/hare.sc which is compatible with GNU's ld and LLVM's lld.
     80 It is expected that, when built in +test mode, the runtime will execute these
     81 test functions instead of calling main. Under these conditions, the runtime is
     82 still expected to call the @init and @fini functions as well, respectively
     83 before and after running the tests.