1 files changed, 67 insertions, 0 deletions
diff --git a/docs/appendices/native-libraries.md b/docs/appendices/native-libraries.md
new file mode 100644
index 00000000..14cf0c6b
--- /dev/null
+++ b/docs/appendices/native-libraries.md
@@ -0,0 +1,67 @@
+# Native library construction
+
+The complete compiler is [Chapter 28b](../../chapter28b/README.md). This appendix
+collects the library and native support that accompanied the old combined
+Chapter 25. The split preserves that functionality in Chapter 28b.
+
+## Building the library
+
+From `chapter28b`, run:
+
+```sh
+make lib release
+```
+
+Make builds `build/release/Simple.jar` and, under the selected CPU/ABI directory,
+`sys.o` and `simple_crt.o`. The default CPU is x86-64; the default calling
+convention is win64 on Windows and SystemV elsewhere. Rebuild serialized
+objects after changing the compiler or object format.
+
+`src/main/smp/sys.smp` exposes child units for native libc bindings, I/O,
+characters, scanners, arrays, growable buffers, and bitsets. These compile into
+one `sys.o`. Clients import its declarations and ideal IR and link calls that
+remain out of line. Currently selecting that object loads all its saved IR;
+member-selective loading and reliable incremental rebuilding remain future work.
+
+The `simple.sh`, `simple.ps1`, and `simple.bat` launchers set `SIMPLE_HOME` so
+the compiler can find the release library. The CLI accepts `-L` for additional
+Simple objects or search directories. The chapter README gives an explicit
+library/client example that needs no library source in the client root.
+
+## Native symbols and pointer sizes
+
+Native function calls and numeric native data symbols have ELF relocations.
+The historical `Chapter25Test.testExternDataEncoding` and `testExternDataImports`
+exercise native data; `StaticDataTest` covers addresses
+and static images. A data symbol names storage, whereas a function symbol names
+callable code; loading the former and calling the latter require different IR.
+
+Simple function pointers currently occupy four bytes. On AMD64, a native
+function address names a low-address tail-jump thunk, which can reach native
+code outside that range. A weak symbol gives static fields and computed
+addresses the same entry across objects; direct calls can still use the native
+PLT. This preserves constant initialization of function fields without storing
+an eight-byte native address in a four-byte slot. The native linker must place
+these Simple entries in the representable address range.
+
+Data pointers still occupy eight bytes. Compact code/data arenas and distinct
+full-width native pointer types are [future designs](../roadmap.md#compact-code-and-data-arenas).
+
+## Runtime and examples
+
+`src/main/c/simple_crt.c` supplies the errno accessor and converts native process
+arguments to Simple byte arrays for an exported `simple_main` function. This
+explicit function entry is distinct from the language's class initializer:
+the selected initializer still receives the integer `arg`. General class
+initializer argument arrays remain a roadmap item.
+
+The executable examples live in
+[`src/test/smp/examples`](../../chapter28b/src/test/smp/examples): Hello World,
+Bubble Sort, Capitalize, Dijkstra, and FileIO. The existing Chapter25Test tests
+compile and link them through the native harness. `make tests` builds the
+library/runtime prerequisites and runs those checks; a Java-only build does
+not produce the native prerequisites.
+
+The compiler's in-memory evaluator and the native driver have different entry
+interfaces. Use the matching harness when comparing their results, especially
+for programs taking an argument array or performing I/O.