From 9467ae311ddc0ce8b4c329f3dbcec88fb279719d Mon Sep 17 00:00:00 2001 From: _ov4 Date: Sat, 17 Oct 2026 09:18:23 +0000 Subject: docs: multi-file builds Document INCLUDE visibility, primitive GLOBAL variables and MAIN entry rules, and highlight the new keywords in the editor grammar. Co-Authored-By: Claude Opus 5.5 --- doc/cpsc.1.md | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) (limited to 'doc/cpsc.1.md') diff --git a/doc/cpsc.1.md b/doc/cpsc.1.md index 92f73b5..2bb1f1c 100644 --- a/doc/cpsc.1.md +++ b/doc/cpsc.1.md @@ -6,15 +6,19 @@ cpsc - compile and run CIE pseudocode # SYNOPSIS -**cpsc** [**-r**] [**-S**] [**-o** *output*] *source* +**cpsc** [**-r**] [**-S**] [**-o** *output*] *source* [*source* ...] **cpsc** **-h** # DESCRIPTION -Compile one pseudocode source file to a native executable, or to textual LLVM IR with **-S**. Options may appear before or after the source path. Source input from stdin is not supported. +Compile one or more pseudocode source files to a native executable, or to textual LLVM IR with **-S**. Options may appear among the source paths. Source input from stdin is not supported. -Without **-o**, save beside the source file, replacing its extension with `.out` for an executable or `.ll` for IR. This naming also applies on Windows. With **-r** alone, run without saving a file. +Without **-o**, save beside the entry source file, replacing its extension with `.out` for an executable or `.ll` for IR. This naming also applies on Windows. With **-r** alone, run without saving a file. + +Each input is a compilation unit. Use top-level `INCLUDE "lib.cps"` to import another input's exported definitions, including its transitive imports. Paths are relative to the including source; every included file must also appear on the command line. Repeated includes and include cycles are harmless. Giving the same input twice, including symbolic or hard links, is an error. Duplicate definitions across files are errors even if the files do not include each other. + +Exactly one file may contain top-level executable statements (including top-level DECLARE). Alternatively, define a parameterless `FUNCTION MAIN RETURNS INTEGER` in one file and have no top-level executable statements anywhere. Builds containing only definitions and no MAIN fail with `error: no main program`. GLOBAL blocks declare shared primitive variables. INCLUDE, GLOBAL and MAIN entry points are compiler extensions beyond the Cambridge guide. # OPTIONS @@ -25,7 +29,7 @@ Without **-o**, save beside the source file, replacing its extension with `.out` : Save to the specified path. Without **-S**, save a native executable; with **-S**, save LLVM IR. Use the path exactly as given; its extension does not select the output format. May be specified only once. With **-r**, keep this file even if execution fails. **-S** -: Save textual LLVM IR instead of a native executable. Without **-o**, use the source filename with a `.ll` extension beside the source file. May be combined with **-r** to save IR and run the program. +: Save textual LLVM IR instead of a native executable. Without **-o**, use the entry source filename with a `.ll` extension beside the source file. May be combined with **-r** to save IR and run the program. **-r** : Run the compiled program with the runner selected at build time (see EXECUTION MODES). Save output first when **-S** or **-o** is also present; otherwise do not save a file. The program inherits stdin, stdout and stderr; `INPUT` can read terminal or piped input. @@ -88,6 +92,12 @@ cpsc test.cps -o test.out ./test.out ``` +Compile a program whose `me.cps` contains `INCLUDE "lib.cps"`: + +```sh +cpsc me.cps lib.cps -r +``` + # EXIT STATUS **0** @@ -96,13 +106,13 @@ cpsc test.cps -o test.out **1** : An argument, file, compilation or execution-engine error occurred, including missing input, when PATH mode cannot validate `lli` from LLVM 23 or NONE mode receives **-r**. -With **-r**, return the executed program's exit status. In PATH mode, failure to launch `lli` or a child-process crash returns 1. +With **-r**, return the executed program's exit status. MAIN's INTEGER result is truncated to 32 bits before returning to the operating system. In PATH mode, failure to launch `lli` or a child-process crash returns 1. An uncaught program exception returns 1 after printing `Unhandled exception. Program terminated.` to standard output. Runtime check failures print the source line and error reason to standard output before throwing and can be handled with TRY/CATCH/ENDTRY. # NOTES -Compiler diagnostics go to stderr. Failed source compilation does not write output; failed native linking does not replace an existing output file. Successful compilation overwrites an existing output file, but an output path that refers to the source file (including a symbolic or hard link) is rejected. +Compiler diagnostics go to stderr. With multiple input files, lexer, parser and code generation diagnostics include the source path after the line number. Failed source compilation does not write output; failed native linking does not replace an existing output file. Successful compilation overwrites an existing output file, but an output path that refers to any input source file (including a symbolic or hard link) is rejected. Missing input, including invoking `cpsc` without arguments, reports `cpsc: fatal error: no input files`. Ordinary lexical, syntax and semantic errors use `error:`; failures that prevent compilation, such as file I/O errors, use `fatal error:`. Compilation and argument failures end with one `compilation terminated.` line. Execution-stage failures do not print that line. -- cgit v1.3.1-4-g156e