path: root/man/mcpu-cpp.1

.TH MCPU-CPP 1 "October 2026" "MCPU-CPP 1.0.3" "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
.BI --sys-root= PATH
Use
.I PATH
as the MCPU system root and do not read configuration files.  The effective
system include tree is
.IR PATH/include .
A relative path is resolved against the invocation working directory.
.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/etc/mcpu-cpp.conf
.fi
.PP
With
.BI --sys-root= PATH
these configuration files are not read and
.I PATH/include
becomes the effective system include root.  This option therefore also
suppresses an explicitly named
.BR --config-file .
.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/etc/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)