docs: document EXTERN and INCLUDE_OBJ

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

4 files changed, 82 insertions, 3 deletions

diff --git a/doc/language/cpsc-language-overview.7.md b/doc/language/cpsc-language-overview.7.md
index 93d2457..2e2a393 100644
--- a/doc/language/cpsc-language-overview.7.md
+++ b/doc/language/cpsc-language-overview.7.md
@@ -12,7 +12,7 @@ Assign with ASCII `<-`: `Count <- Count + 1`. Compare with `=`, `<>`, `<`, `>`,
 
 Precedence, from highest to lowest: unary operators, `* / DIV MOD`, `+ - &`, comparisons, AND, OR. Parentheses override precedence.
 
-Parenthesized type casts, such as (C_INT)Number, have unary precedence. C_INT, C_CHAR, C_STRING and C_DOUBLE are native C aliases; TYPE name = C_TYPE("...") imports other supported C base types and pointers. Conversions between C and pseudocode types must be explicit. These are compiler extensions; see [cpsc-keyword-c_type(7)](keyword/cpsc-keyword-c_type.7.md).
+Parenthesized type casts, such as (C_INT)Number, have unary precedence. C_INT, C_CHAR, C_STRING and C_DOUBLE are native C aliases; TYPE name = C_TYPE("...") imports other supported C base types and pointers. Conversions between C and pseudocode types must be explicit. These are compiler extensions; see [cpsc-keyword-c_type(7)](keyword/cpsc-keyword-c_type.7.md). EXTERN "C" declares C functions from objects named with INCLUDE_OBJ; see [cpsc-keyword-extern(7)](keyword/cpsc-keyword-extern.7.md).
 
 Literals include integers, decimal real numbers, TRUE/FALSE, strings in double quotes, and single-byte characters in single quotes. Negative numbers use unary minus. There are no string or character escape sequences. Comments begin with `//` and continue to the end of the line.
 
@@ -46,6 +46,8 @@ Multi-file builds use the compiler extensions INCLUDE and GLOBAL. Pass every sou
 - [cpsc-keyword-closefile(7)](keyword/cpsc-keyword-closefile.7.md): close a text file.
 - [cpsc-keyword-type(7)](keyword/cpsc-keyword-type.7.md): define enumerations, pointers, and records.
 - [cpsc-keyword-c_type(7)](keyword/cpsc-keyword-c_type.7.md): import native C types and explicitly cast values.
+- [cpsc-keyword-extern(7)](keyword/cpsc-keyword-extern.7.md): declare and call C functions.
+- [cpsc-keyword-include_obj(7)](keyword/cpsc-keyword-include_obj.7.md): link a C object file or the C library.
 - [cpsc-keyword-delete(7)](keyword/cpsc-keyword-delete.7.md): destroy objects and release heap allocations.
 - [cpsc-keyword-class(7)](keyword/cpsc-keyword-class.7.md): define a class with fields and methods.
 - [cpsc-keyword-and(7)](keyword/cpsc-keyword-and.7.md): combine conditions with logical AND.
@@ -54,7 +56,7 @@ Multi-file builds use the compiler extensions INCLUDE and GLOBAL. Pass every sou
 - [cpsc-keyword-div(7)](keyword/cpsc-keyword-div.7.md): perform integer division.
 - [cpsc-keyword-mod(7)](keyword/cpsc-keyword-mod.7.md): find the integer division remainder.
 
-Closing and auxiliary keywords are documented with their main constructs: THEN/ELSE/ENDIF with IF; OF/OTHERWISE/ENDCASE with CASE; CATCH/ENDTRY/THROW with TRY; ENDWHILE with WHILE; UNTIL with REPEAT; TO/STEP/NEXT with FOR; RETURN/RETURNS/BYVAL/BYREF and function/procedure closing keywords with FUNCTION/PROCEDURE; READ/WRITE/APPEND with OPENFILE; ARRAY/OF and INTEGER/REAL/BOOLEAN/CHAR/STRING with DECLARE; ENDGLOBAL with GLOBAL; ENDTYPE with TYPE; PUBLIC/PRIVATE/ENDCLASS with CLASS. TRUE/FALSE are BOOLEAN literals.
+Closing and auxiliary keywords are documented with their main constructs: THEN/ELSE/ENDIF with IF; OF/OTHERWISE/ENDCASE with CASE; CATCH/ENDTRY/THROW with TRY; ENDWHILE with WHILE; UNTIL with REPEAT; TO/STEP/NEXT with FOR; RETURN/RETURNS/BYVAL/BYREF and function/procedure closing keywords with FUNCTION/PROCEDURE; READ/WRITE/APPEND with OPENFILE; ARRAY/OF and INTEGER/REAL/BOOLEAN/CHAR/STRING with DECLARE; ENDGLOBAL with GLOBAL; ENDTYPE with TYPE; EXTERN_FUNCTION/EXTERN_PROCEDURE with EXTERN; PUBLIC/PRIVATE/ENDCLASS with CLASS. TRUE/FALSE are BOOLEAN literals.
 
 # BUILT-IN FUNCTIONS
 
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).