docs: document EXTERN and INCLUDE_OBJ

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

3 files changed, 78 insertions, 1 deletions

diff --git a/doc/language/keyword/cpsc-keyword-c_type.7.md b/doc/language/keyword/cpsc-keyword-c_type.7.md
index 3951e26..4ac4141 100644
--- a/doc/language/keyword/cpsc-keyword-c_type.7.md
+++ b/doc/language/keyword/cpsc-keyword-c_type.7.md
@@ -17,7 +17,7 @@ C_TYPE and parenthesized casts are compiler extensions. C_TYPE requires a string
 
 Supported base types are _Bool; char, signed char and unsigned char; signed and unsigned short, int, long and long long; and float, double and long double. Legal C combinations such as unsigned, signed int and unsigned long int are accepted. Type spelling is case-sensitive. void is allowed for pointer pointees and function return types, but not variables, fields or parameters. Multiple pointer stars may precede or follow the base type: `"**char"` and `"char**"` are equivalent. Whitespace is allowed. Mixed star placement, const/volatile, structs, unions, C typedef names, array types, function pointers, complex types and compiler-specific types are unsupported.
 
-C widths, char signedness and floating-point formats come from the compiler's build platform. Generated programs must use the same platform ABI; cross-target compilation and EXTERN declarations are not implemented. INTEGER remains signed 64-bit, CHAR remains an unsigned byte, and REAL remains double precision. In particular, C_CHAR need not have CHAR's signedness.
+C widths, char signedness and floating-point formats come from the compiler's build platform. Generated programs must use the same platform ABI; cross-target compilation is not implemented. EXTERN declarations use these types to call C functions; see [cpsc-keyword-extern(7)](cpsc-keyword-extern.7.md). INTEGER remains signed 64-bit, CHAR remains an unsigned byte, and REAL remains double precision. In particular, C_CHAR need not have CHAR's signedness.
 
 A cast has unary precedence and converts its following operand. Declare a type alias before using its name in a cast. Numeric, character and boolean values can be explicitly converted between pseudocode and C types. STRING can be cast to char* and back, and C pointer types can be cast to other C pointer types. C void* and original pseudocode pointer types can be explicitly cast to each other. Pointer/integer casts and casts involving pseudocode enums or whole records are unsupported. Casts are values, not assignable locations.
 
diff --git a/doc/language/keyword/cpsc-keyword-extern.7.md b/doc/language/keyword/cpsc-keyword-extern.7.md
new file mode 100644
index 0000000..db1bde4
--- /dev/null
+++ b/doc/language/keyword/cpsc-keyword-extern.7.md
@@ -0,0 +1,37 @@
+% CPSC-KEYWORD-EXTERN(7)
+
+# NAME
+
+cpsc-keyword-extern, cpsc-keyword-extern_function, cpsc-keyword-extern_procedure - declare a C function
+
+# SYNOPSIS
+
+```text
+EXTERN "C" EXTERN_FUNCTION name(type, ...) RETURNS type
+EXTERN "C" EXTERN_PROCEDURE name(type, ...)
+```
+
+# DESCRIPTION
+
+EXTERN is a compiler extension, allowed only at top level. It declares a C function without a body; there is no ENDFUNCTION or ENDPROCEDURE. The name is the exact C symbol; calls from pseudocode remain case insensitive. Call an EXTERN_FUNCTION in an expression and an EXTERN_PROCEDURE with CALL.
+
+Parameters list only types. Parameter and result types must be C types: C_INT, C_CHAR, C_STRING, C_DOUBLE or a C_TYPE alias, including pointers. void is not allowed; use EXTERN_PROCEDURE for a C function returning void. EXTERN_FUNCTION requires RETURNS and EXTERN_PROCEDURE does not accept it. Structs, BYREF and BYVAL are unsupported; declare a C pointer parameter and pass ^Variable instead. Pseudocode values must be cast, as for other C values.
+
+A final `...` makes the function variadic. Variadic arguments must also be C values; they receive C default argument promotions (float to double, narrow integers and _Bool to int or unsigned int).
+
+Every EXTERN symbol must be defined by an object named with INCLUDE_OBJ, otherwise compilation fails. EXTERN cannot be combined with OVERLOAD, and a name may be declared once across all input files; put shared declarations in one file and INCLUDE it.
+
+# EXAMPLE
+
+```text
+INCLUDE_OBJ "__libc"
+EXTERN "C" EXTERN_FUNCTION printf(C_STRING, ...) RETURNS C_INT
+EXTERN "C" EXTERN_FUNCTION abs(C_INT) RETURNS C_INT
+DECLARE Count : C_INT
+Count <- printf((C_STRING)"%d|", abs((C_INT)-5))
+OUTPUT ""
+```
+
+# SEE ALSO
+
+[cpsc-keyword-include_obj(7)](cpsc-keyword-include_obj.7.md), [cpsc-keyword-c_type(7)](cpsc-keyword-c_type.7.md), [cpsc-keyword-call(7)](cpsc-keyword-call.7.md), [cpsc-language-overview(7)](../cpsc-language-overview.7.md).
diff --git a/doc/language/keyword/cpsc-keyword-include_obj.7.md b/doc/language/keyword/cpsc-keyword-include_obj.7.md
new file mode 100644
index 0000000..1c4851a
--- /dev/null
+++ b/doc/language/keyword/cpsc-keyword-include_obj.7.md
@@ -0,0 +1,40 @@
+% CPSC-KEYWORD-INCLUDE_OBJ(7)
+
+# NAME
+
+cpsc-keyword-include_obj - link a C object file or the C library
+
+# SYNOPSIS
+
+```text
+INCLUDE_OBJ "path.o"
+INCLUDE_OBJ "__libc"
+```
+
+# DESCRIPTION
+
+INCLUDE_OBJ is a compiler extension, allowed only at top level. It names an object file whose functions EXTERN declarations may call. Resolve the path relative to the including source's directory; it must name a `.o` object file built for the same platform, for example with `cc -c lib.c`. The special name `"__libc"` selects the C standard library, including the math library; it must be included explicitly before declaring C library functions.
+
+INCLUDE_OBJ applies to the whole program: objects from every input file are linked together, and repeated objects are linked once. Each EXTERN symbol must be defined by one of them. Native output links the objects, and `-r` loads them for execution. `-S` writes IR only; link any objects yourself when building the IR manually.
+
+# EXAMPLE
+
+`lib.c`, compiled with `cc -c lib.c`:
+
+```text
+int add3(int a, int b, int c) { return a + b + c; }
+```
+
+`me.cps`:
+
+```text
+INCLUDE_OBJ "lib.o"
+EXTERN "C" EXTERN_FUNCTION add3(C_INT, C_INT, C_INT) RETURNS C_INT
+OUTPUT add3((C_INT)1, (C_INT)2, (C_INT)3)
+```
+
+Run with `cpsc me.cps -r` to print `6`.
+
+# SEE ALSO
+
+[cpsc-keyword-extern(7)](cpsc-keyword-extern.7.md), [cpsc-keyword-include(7)](cpsc-keyword-include.7.md), [cpsc(1)](../../cpsc.1.md).