1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
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)
|
