diff options
Diffstat (limited to 'man/mcpu-cpp.1')
| -rw-r--r-- | man/mcpu-cpp.1 | 432 |
1 files changed, 432 insertions, 0 deletions
diff --git a/man/mcpu-cpp.1 b/man/mcpu-cpp.1 new file mode 100644 index 0000000..489de41 --- /dev/null +++ b/man/mcpu-cpp.1 @@ -0,0 +1,432 @@ +.TH MCPU-CPP 1 "October 2026" "MCPU-CPP 1.0.2" "User Commands" +.SH NAME +mcpu-cpp \- preprocessor for MCPU languages +.SH SYNOPSIS +.B mcpu-cpp +.RI [ options ] +.RI [ input +.RI [ output ]] +.SH DESCRIPTION +.B mcpu-cpp +is the preprocessor for the MCPU toolchain. It processes source text before +language-specific frontends, expands macros, evaluates conditional compilation, +resolves include files, maintains source-location information, and can generate +Make dependencies. +.PP +External text is UTF-8. Text is represented internally as strict UCS-2 through +LibMPUIO. Preprocessing identifiers are Unicode-aware: the first character +must be underscore or have the Unicode XID_Start property; following characters +may also be dollar sign or have XID_Continue. The dollar sign cannot start an +identifier. +.PP +Preprocessor directives use canonical English names only. Unicode remains +available in identifiers, strings, comments, diagnostics, and ordinary source +text. +.PP +If +.I input +is omitted or is +.BR - , +standard input is read. If +.I output +is omitted or is +.BR - , +normal preprocessing output is written to standard output. +.SH TEXT PROCESSING +Backslash-newline splicing is performed before directive parsing. C block +comments and C++-style line comments are removed by the preprocessing phase. +Long invisible source regions are represented compactly while preserving source +coordinates: short forward gaps are emitted as newlines, while larger gaps use +corrective GNU-style line markers. +.SH DIRECTIVES +The principal supported directives are: +.TP +.B #define +Define an object-like or function-like macro. +.TP +.B #undef +Remove a macro definition. +.TP +.BR #if , " #ifdef" , " #ifndef" , " #elif" , " #else" , " #endif" +Control conditional compilation. The +.B defined +operator is supported in +.B #if +expressions. +.TP +.B #include +Include a quoted or angle-bracket header. The operand may be produced by macro +expansion. +.TP +.B #include_next +Continue header lookup after the search-chain element that found the current +header. It is intended primarily for wrapper headers. +.TP +.B #pragma once +Process a physical header only once. Physical file identity is used rather +than source spelling. +.TP +.B #line +Set the logical source line and, optionally, logical source file name. Its +arguments undergo macro expansion; output uses GNU-style line markers. +.TP +.B #error +Emit an error diagnostic and terminate preprocessing unsuccessfully. +.TP +.B #warning +Emit a warning diagnostic and continue unless warning policy promotes it to an +error. +.TP +.B #lang +Push an MCPU language state. The argument is one quoted language name. +.TP +.B #endlang +Restore the previous MCPU language state. +.PP +.B #lang +and +.B #endlang +remain in the output stream for the later frontend dispatcher. The supported +language names are +.BR diff , +.BR dift , +.BR alg , +.BR as , +.BR avm , +and +.BR ACS . +Language matching is case-insensitive in ASCII, while the quoted spelling is +preserved in normalized +.B #lang +output. +.SH MACROS +Object-like and function-like macros are supported, including recursive rescan, +stringification with +.BR # , +token concatenation with +.BR ## , +variadic macros using +.B ... +and +.BR __VA_ARGS__ , +and standard +.BR __VA_OPT__ . +.PP +Ordinary macro arguments are expanded before substitution except where raw +arguments are required by stringification or token concatenation. Replacement +list horizontal whitespace is normalized without changing whitespace inside +quoted tokens or actual arguments. +.SH CONDITIONAL EXPRESSIONS +.B #if +expressions support integer and character constants, the +.B defined +operator, unary, arithmetic, shift, relational, equality, bitwise, logical, +conditional +.BR ?: , +and comma operators, with short-circuit evaluation for +.BR && , +.BR || , +and +.BR ?: . +.PP +Expression evaluation uses one 64-bit model. MCPU also supports the +.B zNNN +and +.B zNNNU +width suffixes for source integer literals with widths not exceeding 64 bits. +A negative shift count reverses shift direction according to the MCPU +preprocessing contract. +.SH INCLUDE SEARCH +For +.BR "#include \"file\"" , +the physical directory containing the current source file is searched first. +This step is omitted for +.BR "#include <file>" . +The remaining effective search order is: +.PP +.nf +explicit -I +explicit -isystem +MCPU_CPP_<LANG>_INCLUDE_PATH +MCPU_CPP_INCLUDE_PATH +MCPU_CPP_SYSTEM_INCLUDE_PATH/<lang> +MCPU_CPP_SYSTEM_INCLUDE_PATH +explicit -idirafter +MCPU_CPP_AFTER_INCLUDE_PATH +.fi +.PP +Within one search class, insertion order is preserved. The logical file name +set by +.B #line +does not alter quoted-header lookup. +.SH OPTIONS +.TP +.BI -o " FILE" +Write normal preprocessing output to +.IR FILE . +.TP +.BI -D " NAME[=VALUE]" +Define a command-line macro. If no value is given, the replacement is +.BR 1 . +.TP +.BI -U " NAME" +Undefine a command-line macro. +.TP +.BI -imacros " FILE" +Preprocess +.I FILE +for its macro and preprocessing state, but discard its ordinary output. All +.B -imacros +files are processed before all +.B -include +files. +.TP +.BI -include " FILE" +Preprocess +.I FILE +before the primary input. +.TP +.BR "-I DIR" ", " "-IDIR" +Add a user include directory. +.TP +.BI -isystem " DIR" +Add an explicit system include directory. +.TP +.BI -idirafter " DIR" +Add an include directory searched after the configured system tree. +.TP +.B -nostdinc +Suppress the effective standard-system include tree. Explicit +.B -isystem +directories remain active. +.TP +.B -dM +After preprocessing, dump non-predefined macro definitions. +.TP +.B -dMP +Dump predefined macros first, followed by the other macro definitions. +.TP +.B -dD +Preserve +.B #define +directives in normal preprocessing output. +.TP +.B -dconfig +Print the effective MCPU-CPP configuration and exit. +.TP +.B -dsearch-dirs +Print the effective include search directories and exit. +.TP +.B -M +Write one Make dependency rule including system headers and suppress normal +preprocessing output. +.TP +.B -MM +Like +.BR -M , +but omit system dependencies. +.TP +.B -MG +With dependency-only +.B -M +or +.BR -MM , +treat missing headers and missing forced files as generated dependencies rather +than errors. It is not valid with +.B -MD +or +.BR -MMD . +.TP +.B -MD +Generate dependencies including system headers while retaining normal +preprocessing output. +.TP +.B -MMD +Like +.BR -MD , +but omit system dependencies. +.TP +.BI -MF " FILE" +Write dependencies to +.IR FILE . +A file name of +.B - +means standard output. This option requires dependency generation. +.TP +.BI -MT " TARGET" +Set an explicit Make dependency target without Make quoting. The option may be +repeated. +.TP +.BI -MQ " TARGET" +Set an explicit Make dependency target with Make quoting. The option may be +repeated. +.TP +.BI --object-suffix " SFX" +Set the suffix used for the automatically derived dependency target. The +default is +.BR .o . +.TP +.B -w +Suppress all warnings. +.TP +.BR -Wcomment , " -Wcomments" +Enable warnings for nested +.B /* +inside a block comment and for backslash-newline inside a +.B // +comment. +.TP +.BR -Wno-comment , " -Wno-comments" +Disable comment warnings, including when +.B -Wall +is present. +.TP +.B -Wall +Enable all optional MCPU-CPP warning classes. +.TP +.B -Werror +Promote every warning that would be emitted to an error. This does not enable +new warning classes. +.TP +.B -Wno-error +Keep emitted warnings as warnings. +.TP +.BI --config-file " FILE" +Read only +.I FILE +as the explicit configuration layer on top of runtime-derived defaults. +.TP +.B --no-config +Do not read configuration files. Runtime-derived defaults remain active. +.TP +.BR -v , " --verbose" +Print configuration and include activity. +.TP +.B --help +Print command-line help and exit successfully. +.TP +.B --version +Print the program version and exit successfully. +.TP +.B -E +Accepted and ignored for compiler-driver compatibility. It is intentionally +not listed by +.BR --help . +.SH DEPENDENCIES +Dependency generation uses the same include traversal as ordinary +preprocessing, including conditional compilation, computed includes, +.BR #include_next , +and +.BR "#pragma once" . +Physical dependencies are deduplicated by physical file identity. +.PP +With +.B -M +or +.BR -MM , +normal preprocessing output is suppressed. With +.B -MD +or +.BR -MMD , +normal preprocessing output is retained and a side-effect dependency file is +written. If +.B -MF +is not specified, the dependency file name is derived from the input or +ordinary +.B -o +output name and receives a +.B .d +suffix. +.SH CONFIGURATION +Before reading configuration files, MCPU-CPP derives +.B MCPU_CPP_SYSTEM_INCLUDE_PATH +as +.IR <runtime-root>/include . +The runtime root is determined from the actual executable location, normally +through Linux +.IR /proc/self/exe . +.PP +Configuration layers are applied in increasing priority: +.PP +.nf +<runtime-root>/etc/mcpu-cpp.conf +/etc/mcpu/mcpu-cpp.conf +$HOME/.mcpu/mcpu-cpp.conf +.fi +.PP +The user configuration path variables are +.BR MCPU_CPP_INCLUDE_PATH , +.BR MCPU_CPP_AFTER_INCLUDE_PATH , +.BR MCPU_CPP_DIFF_INCLUDE_PATH , +.BR MCPU_CPP_DIFT_INCLUDE_PATH , +.BR MCPU_CPP_ALG_INCLUDE_PATH , +.BR MCPU_CPP_AS_INCLUDE_PATH , +.BR MCPU_CPP_AVM_INCLUDE_PATH , +and +.BR MCPU_CPP_ACS_INCLUDE_PATH . +The effective system root is controlled by +.BR MCPU_CPP_SYSTEM_INCLUDE_PATH . +A later definition replaces an earlier one, including an empty value. +.SH SOURCE LOCATIONS +MCPU-CPP emits GNU-style line markers of the form: +.PP +.nf +# line "file" [flags] +.fi +.PP +Flag 1 denotes entry into an included file and flag 2 denotes return to the +including file. Input +.B #line +directives change the logical values observed by +.B __LINE__ +and +.BR __FILE__ . +The predefined source macros also include +.B __BASE_FILE__ +and +.BR __INCLUDE_LEVEL__ . +.SH GNU-COMPATIBLE FEATURES +MCPU-CPP is an independent MCPU preprocessor, but intentionally follows GNU CPP +behavior for documented operations including object-like and function-like +macros, rescan, +.BR # , +.BR ## , +variadic macros, +.BR __VA_OPT__ , +conditional directives, +.BR #include , +.BR #include_next , +.BR "#pragma once" , +.BR #line , +GNU line markers, forced files, Make dependency options, and supported warning +controls. +.PP +MCPU-specific facilities such as +.BR "#lang / #endlang" , +the +.B zNNN +integer-literal suffix, and MCPU ABI predefined macros are native extensions. +.SH FILES +.TP +.I <runtime-root>/etc/mcpu-cpp.conf +Configuration installed with the relocatable MCPU runtime tree. +.TP +.I /etc/mcpu/mcpu-cpp.conf +Optional machine-wide configuration override. +.TP +.I $HOME/.mcpu/mcpu-cpp.conf +Optional per-user configuration override with the highest normal configuration +priority. +.SH EXIT STATUS +.B mcpu-cpp +returns zero after successful preprocessing or after successful informational +operations such as +.B --help +and +.BR --version . +It returns nonzero when command-line processing, configuration, preprocessing, +diagnostics promoted to errors, or output generation fails. +.SH SEE ALSO +.BR libmpu (7), +.BR libmpuio (7), +.BR zubr (1) |