.TH MCPU-AS 1 "October 2026" "LibMCPU" "User Commands"

.SH NAME
mcpu-as \- assemble MCPU source into a MELF relocatable object
.SH SYNOPSIS
.B mcpu-as
.RI [ options ] " -o output.o input.s"
.SH DESCRIPTION
.B mcpu-as
reads one UTF-8 MCPU assembler source and writes one MELF
.B ET_REL
relocatable object.  The assembler does not have a separate compile-only mode:
ET_REL is its normal and only object output.  Input and the
.B -o
option may appear in either order.
.PP
The assembler records the symbols, sections and relocations explicitly described
by the source; it does not choose PROGRAM versus MODEL and does not synthesize
HLL CRT objects.  Final lifecycle ownership, automatic HLL CRT selection,
STACK and HEAP program headers are resolved later by
.BR mcpu-ld (1).
.SH OPTIONS
.TP
.BI -o " file"
Write the relocatable object to
.IR file .
This option is mandatory.
.TP
.BR -v ", " --verbose
Print the MELF ET_REL output-object summary after successful assembly.
The default successful invocation is quiet.
.TP
.BR -h ", " --help
Display command-line help and exit.
.SH PSW FLAG INSTRUCTIONS
The assembler accepts explicit arithmetic/status flag control instructions:
.nf
SETF flag
CLRF flag
CLRCPUF
CLRMPUF
.fi
.PP
.B SETF
and
.B CLRF
accept the named flags AF, CF, OF, SF, PF, ZF, RF, VF, DOMF, SNGF, OVFF,
UDFF, TLSF, PLSF, INDF and INXF, corresponding to PSW bits 0 through 15.
HF, TF and IF remain readable branch selectors but are not writable through
these instructions; MODE is a multi-bit field and has no selector.
.B CLRCPUF
clears PSW[7:0], while
.B CLRMPUF
clears PSW[15:8].  Both preserve all control/execution state above bit 15.
.SH SOURCE LOCATION CONTROL
The assembler accepts the source directive
.B #line
with a decimal line number and an optional quoted file name.  It is intended
for preprocessor output and changes subsequent diagnostic source locations;
it does not become part of the MELF object.
.SH FILES
.TP
.I *.s
MCPU assembler source.
.TP
.I *.o
Conventional name for MELF ET_REL output.
.TP
.B --version
Display the program name, MCPU toolchain identity and version, then exit.
.TP
.B --dump-version
Display only the MCPU package version number and exit.
.SH EXIT STATUS
Zero on success; nonzero on syntax, semantic, I/O or object-generation error.
.SH EXAMPLES
.nf
mcpu-as -o main.o main.s
mcpu-as helper.s -o helper.o
.fi
.SH SEE ALSO
.BR mcpu-ld (1),
.BR mcpu-readelf (1),
.BR mcpu-objdump (1),
.BR libmcpu (7)