build system (first pass)

README.md

@@ -30,6 +30,32 @@ invocation in command-line order:
 `-l<name>`. `--c-include-path <dir>` and `--c-define <name[=value]>` configure
 C preprocessing.
 
+Instead of passing these on the command line, a project can describe its build
+in Brolang itself. `brolang build [root]` (root defaults to the current
+directory) reads a `config` constant from `root/build.bro` and compiles the
+program package it names:
+
+```bro
+b :: import "@std/build"
+
+config :: b.BuildConfig{
+	name = "manual",
+	source = "src",
+	libraries = &[],
+	lib_paths = &[],
+	includes = &[],
+	defines = &[],
+	links = &["examples/build/manual/native.c"],
+}
+```
+
+`source` is the program package, relative to `build.bro`. The list fields map to
+the matching C options (`libraries` → `-l`, `lib_paths` → `-L`, `includes` →
+`-I`, `defines` → C defines, `links` → linker inputs) and, like those flags,
+their paths are relative to the invocation directory. Lists take the address of
+an array literal; empty lists are written `&[]`. See `examples/build/` for
+runnable projects.
+
 Relative `.h` imports create synthetic package namespaces backed by libclang:
 
 ```bro