## Reference documentation on available primitives ### Data Structures For memory safety, the following data structures are opaque and only modified using functions described further down. I still find it useful to understand how they work under the hood. - Handles: addresses to objects allocated on the heap. They're augmented with book-keeping to guarantee memory-safety, and so cannot be stored in registers. See [mu.md](mu.md) for details, but in brief: - You need `addr` values to access data they point to. - You can't store `addr` values in other types. They're temporary. - You can store `handle` values in other types. - To convert `handle` to `addr`, use `lookup`. - Reclaiming memory (currently unimplemented) invalidates all `addr` values. - Arrays: size-prefixed regions of memory containing multiple elements of a single type. Contents are preceded by 4 bytes (32 bits) containing the `size` of the array in bytes. - Slices: a pair of 32-bit addresses denoting a [half-open](https://en.wikipedia.org/wiki/Interval_(mathematics)) \[`start`, `end`) interval to live memory with a consistent lifetime. Invariant: `start` <= `end` - Streams: strings prefixed by 32-bit `write` and `read` indexes that the next write or read goes to, respectively. - offset 0: write index - offset 4: read index - offset 8: size of array (in bytes) - offset 12: start of array data Invariant: 0 <= `read` <= `write` <= `size` Writes to a stream abort if it's full. Reads to a stream abort if it's empty. - Graphemes: 32-bit fragments of utf-8 that encode a single Unicode code-point. - Code-points: 32-bit integers representing a Unicode character. ### Functions The most useful functions from 400.mu and later .mu files. Look for definitions (using `ctags`) to see type signatures. - `abort`: print a message in red on the bottom left of the screen and halt #### assertions for tests - `check`: fails current test if given boolean is false (`= 0`). - `check-not`: fails current test if given boolean isn't false (`!= 0`). - `check-ints-equal`: fails current test if given ints aren't equal. - `check-strings-equal`: fails current test if given strings have different bytes. - `check-stream-equal`: fails current test if stream's data doesn't match string in its entirety. Ignores the stream's read index. - `check-array-equal`: fails if an array's elements don't match what's written in a whitespace-separated string. - `check-next-stream-line-equal`: fails current test if next line of stream until newline doesn't match string. #### predicates - `handle-equal?`: checks if two handles point at the identical address. Does not compare payloads at their respective addresses. - `array-equal?`: checks if two arrays (of ints only for now) have identical elements. - `string-equal?`: compares two strings. - `stream-data-equal?`: compares a stream with a string. - `next-stream-line-equal?`: compares with string the next line in a stream, from `read` index to newline. - `slice-empty?`: checks if the `start` and `end` of a slice are equal. - `slice-equal?`: compares a slice with a string. - `slice-starts-with?`: compares the start of a slice with a string. - `stream-full?`: checks if a write to a stream would abort. - `stream-empty?`: checks if a read from a stream would abort. #### arrays - `populate`: allocates space for `n` objects of the appropriate type. - `copy-array`: allocates enough space and writes out a copy of an array of some type. - `slice-to-string`: allocates space for an array of bytes and copies the slice into it. #### streams - `populate-stream`: allocates space in a stream for `n` objects of the appropriate type. - `write-to-stream`: writes arbitrary objects to a stream of the appropriate type. - `read-from-stream`: reads arbitrary objects from a stream of the appropriate type. - `stream-to-array`: allocates just enough space and writes out a stream's data between its read index (inclusive) and write index (exclusive). - `clear-stream`: resets everything in the stream to `0` (except its `size`). - `rewind-stream`: resets the read index of the stream to `0` without modifying its contents. - `write`: writes a string into a stream of bytes. Doesn't support stream
#!/bin/sh
# Translate SubX files to a bootable disk image.
#
# A couple of gotchas:
# * Many phases here have no error-checking. Perhaps I should use a
#   version of translate_subx_debug for baremetal.
# * Don't pass in numbered .subx files without translated .mu files. Our test
#   harness is in test.mu, and only Mu programs can run tests in baremetal.
#
# The top level is in general not as rigorous about avoiding dependency cycles
# as the lower-level tools in linux/

set -e

cat $*