Version 0.4.00.4.0

1 files changed, 180 insertions, 0 deletions

diff --git a/man/mcpu-ld.1 b/man/mcpu-ld.1
new file mode 100644
index 0000000..05172bd
--- /dev/null
+++ b/man/mcpu-ld.1
@@ -0,0 +1,180 @@
+.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)