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

.SH NAME
mcpu-ld \- link MCPU MELF objects, archives and shared libraries
.SH SYNOPSIS
.B mcpu-ld
.RI [ link-options ] " -o output input ..."
.SH DESCRIPTION
.B mcpu-ld
links MELF ET_REL objects and MCPU static libraries.  It can produce a
partially linked ET_REL object, a fully static ABI-v1 ET_EXEC, a frozen ABI-v3
startup-dynamic ET_EXEC, or an ABI-v3 ET_DYN shared object.
.PP
The default output, when none of
.BR -r ,
.B --shared
or
.B --dynamic
is present, is a fully static ABI-v1 ET_EXEC.
.SH OUTPUT MODES
.TP
.B -r
Produce one partial-link MELF ET_REL object.  Unresolved strong symbols and
RELA records may remain for a later final link.  STACK, HEAP, SONAME and shared
objects are not part of this mode.
.TP
.B --shared
Produce a frozen ABI-v3 MELF ET_DYN shared object.  A logical
.B --soname
is mandatory.  Shared objects may contain only .text/.data/.bss allocated
sections and own no lifecycle, model spaces, STACK or HEAP.
.TP
.B --dynamic
Produce a frozen ABI-v3 startup-dynamic MELF ET_EXEC.  Normal dependencies are
recorded as DT_NEEDED SONAMEs.
.SH AUTOMATIC HLL CRT
For final static or dynamic ET_EXEC output, mcpu-ld examines the explicitly
listed ET_REL input objects before processing -l libraries.  It recognizes two
compiler-normalized complete-program forms:
.nf
PROGRAM: strong GLOBAL/FUNC main + fini in one ET_REL
MODEL:   strong GLOBAL/FUNC init + life + fini in one ET_REL
.fi
.PP
PROGRAM and MODEL roots are mutually exclusive.  Incomplete or split MODEL
definitions are rejected, as are split PROGRAM main/fini definitions.  A final
link that mixes HLL roots with low-level _start/_life lifecycle ownership is an
error.  The linker does not use library members or shared-library definitions to
classify the complete program.
.PP
After classification, mcpu-ld automatically inserts:
.nf
PROGRAM: crt0.o crti.o <explicit input objects> crtn.o
MODEL:   crt1.o crti.o <explicit input objects> crtn.o
.fi
The CRT objects are loaded from <MCPU-root>/lib/mcpu, where <MCPU-root> is the
active installation/system root.  Missing or unreadable required CRT objects
are fatal errors.  There is no fallback CRT search in another root and no
fallback from an HLL link to low-level linking.
.PP
Low-level ET_EXEC inputs that own _start/_life themselves are linked without HLL
CRT insertion.  The -r and --shared modes never perform HLL complete-program
classification or CRT insertion.
.SH SYSTEM ROOT AND CONFIGURATION
.TP
.B --no-config
Do not read mcpu-ld.conf files.  The executable-derived runtime root remains
active and supplies its default lib directory.
.TP
.BI --sys-root= PATH
Use PATH as the MCPU system root and do not read configuration files.  PATH/lib
becomes the system library directory.  A relative PATH is resolved from the
invocation working directory.
.TP
.BI --sys-root " PATH"
Equivalent two-argument form.
.TP
.B --dump-config
Print the effective MCPU configuration and exit.
.TP
.B --print-search-dirs
Print effective library search directories in search order and exit.
.SH LIBRARY OPTIONS
.TP
.BI -L " dir"
.TQ
.BI -L dir
Add an explicit library search directory.  Explicit -L directories precede
the configured system library path.
.TP
.BI -l " name"
.TQ
.BI -l name
Link against libNAME.  ABI-v1 and -r search only libNAME.a.  ABI-v3 dynamic
and shared links search each directory in directory-major order, trying
libNAME.so before libNAME.a.
.TP
.B --static
Force every -l lookup to use libNAME.a without changing the selected output
mode.  Static archive members are copied into the result and do not create
DT_NEEDED entries.
.SH SHARED-LIBRARY IDENTITY
.TP
.BI --soname= NAME
.TQ
.BI --soname " NAME"
Set the mandatory ABI-v3 ET_DYN SONAME.  NAME is a logical library identity
and must not contain a slash.
.SH EXECUTABLE LAYOUT OPTIONS
.TP
.BI -o " file"
Write the result to file.
.TP
.BI --stack-size= size
Set fixed executable STACK size.  The value must be positive and 16-byte
aligned.  The default is 1048576 bytes.
.TP
.BI --heap-size= size
Set initial HEAP size.  Default: 1048576 bytes.
.TP
.BI --heap-limit= size
Set immutable maximum HEAP size.  Default: 1048576 bytes.
.TP
.B --no-heap
Omit PT_MCPU_HEAP from an executable.
.TP
.BR -v ", " --verbose
Print the MELF output-object summary after a successful link.
The default successful invocation is quiet.
.TP
.BR -h ", " --help
Display command-line help and exit.
.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.
.PP
Size operands are bytes by default.  K/KiB, M/MiB and G/GiB are accepted;
K, M and G use binary multipliers.
.SH ARCHIVES AND SYMBOL RESOLUTION
Static libraries are ordinary deterministic UNIX ar containers whose ordinary
members are MELF ET_REL objects.  Archive members are extracted selectively
when they satisfy currently unresolved strong GLOBAL symbols.  An unresolved
WEAK reference does not by itself pull an archive member.
.PP
For ABI-v3 dynamic output, selecting an ET_DYN provider records its SONAME as
DT_NEEDED.  Selecting an archive provider links the required members
statically and records no dependency for that archive.
.SH FILES
.TP
.I <runtime-root>/lib/mcpu/crt0.o, crt1.o, crti.o, crtn.o
Required automatic HLL CRT objects for PROGRAM/MODEL final executable links.
.TP
.I <runtime-root>/etc/mcpu-ld.conf
Relocatable-tree configuration installed with LibMCPU.
.TP
.I /etc/mcpu/mcpu-ld.conf
Optional machine-wide override.
.TP
.I $HOME/.mcpu/etc/mcpu-ld.conf
Optional per-user override.
.SH EXIT STATUS
Zero on success; nonzero on command-line, input-validation, symbol-resolution,
relocation or output error.
.SH EXAMPLES
.nf
mcpu-ld --stack-size=64K --no-heap -o program main.o helper.o
mcpu-ld -r -o combined.o a.o b.o
mcpu-ld --shared --soname=libfoo.so.1 -o libfoo.so.1.0.0 foo.o
mcpu-ld --dynamic -L ./lib -lfoo -o program main.o
mcpu-ld --dynamic --static -L ./lib -lchoice -o program main.o
.fi
.SH SEE ALSO
.BR mcpu-as (1),
.BR mcpu-ar (1),
.BR mcpu-run (1),
.BR mcpu-readelf (1),
.BR libmcpu (7)