diff options
Diffstat (limited to 'man/mcpu-ld.1')
| -rw-r--r-- | man/mcpu-ld.1 | 180 |
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) |