restricted c header imports

README.md

@@ -22,12 +22,28 @@ invocation in command-line order:
 
 ```sh
 ./build/brolang examples/interop/manual -o build/manual \
-  --link examples/interop/manual/native.c
+  --c-link examples/interop/manual/native.c
 ```
 
-`--link` accepts C sources, object files, and direct library paths.
-`--library-path <dir>` becomes `-L<dir>`, and `--library <name>` becomes
-`-l<name>`.
+`--c-link` accepts C sources, object files, archives, and direct library paths.
+`--c-library-path <dir>` becomes `-L<dir>`, and `--c-library <name>` becomes
+`-l<name>`. `--c-include-path <dir>` and `--c-define <name[=value]>` configure
+C preprocessing.
+
+Relative `.h` imports create synthetic package namespaces backed by libclang:
+
+```bro
+native :: import "../include/native.h"
+
+main :: func() void {
+	_ = native.imported_add(20, 22)
+}
+```
+
+Header imports expose supported external functions, typedefs, C scalars, and
+pointers to opaque records. They never add linker inputs; implementations must
+still be supplied explicitly with the C-prefixed linking options. Set
+`BROLANG_LIBCLANG_PATH` when libclang is not installed in a standard location.
 
 Compilation phases are isolated under `compiler/`:
 
@@ -63,10 +79,11 @@ Current prototype features:
 - Explicit `.ptr`/`.len`, slicing, postfix pointer dereference and optional unwrap, and keyed struct literals
 - Contextual integer constants and compile-time folding of addition and unary negation trees
 - Directory packages with merged declarations and file-local relative imports
+- Relative C header imports as synthetic package namespaces
 - Qualified imported globals and functions with package-aware symbol mangling
 - Demand-monomorphized Brolang and C-ABI functions
 - Bodyless concrete C function declarations with exact external symbol names
-- Ordered linking of additional C sources, objects, and libraries
+- Ordered linking of additional C sources, objects, archives, and libraries
 - Checked signed addition and unary negation
 - Static, eager runtime, and deferred problematic globals
 - Runtime diagnostics followed by `llvm.trap`