macOS Static Libraries: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Example FPC static library
2	2
3	3		> Tip: If you use "cdecl", FPC ensures that your function completely adheres to all ABI requirements (naming, parameter passing, etc). If you don't, then you are on your own.
4	4
5	5		test.pas:
6	6
7	7		``` pascal
8	8		{$mode objfpc} {$H+}
9	9
10	10		// Note this is a unit and not a library
11	11		unit test;
12	12
13	13		interface
14	14
15	15		uses
16	16		// needed for UpperCase
17	17		SysUtils;
18	18
19	19		implementation
20	20
21	21		// library subroutine
22	22		function cvtString(strIn : string) : PChar; Cdecl;
23	23		begin
24	24		cvtString := PChar(UpperCase(strIn));
25	25		end;
26	26
27	27		end.
28	28		```
29	29
30	30		Compile:
31	31
32		-	~~` fpc test.pas`~~
	32	+	```text
	33	+	fpc test.pas
	34	+	```
33	35
34	36		which produces an object file named `test.o` which we will now convert into a static library archive named `libtest.a` using the `libtool` command line utility:
35	37
36		-	~~` libtool -static -o libtest.a test.o`~~
	38	+	```text
	39	+	libtool -static -o libtest.a test.o
	40	+	```
37	41
38	42		## Example FPC application to use FPC static library
39	43
40	44		statlibdemo.pas:
41	45
42	46		``` pascal
43	47		{$mode objfpc} {$H+}
44	48
45	49		// Link in our static library
46	50		// - note the prefix (lib) and extension (.a) are not necessary
47	51		{$LinkLib test}
48	52
49	53		program statlibdemo;
50	54
51	55		// Declare our function
52	56		function cvtString(strIn : string) : PChar; Cdecl; External Name 'cvtString';
53	57
54	58		begin
55	59		WriteLn(cvtString('hello world'));
56	60		end.
57	61		```
58	62
59	63		Compile:
60	64
61		-	~~` fpc statlibdemo.pas`~~
	65	+	```text
	66	+	fpc statlibdemo.pas
	67	+	```
62	68
63	69		which unexpectedly produces:
64	70
65	71		```text
66	72		Free Pascal Compiler version 3.3.1 [2020/04/20] for x86_64
67	73		Copyright (c) 1993-2020 by Florian Klaempfl and others
68	74		Target OS: Darwin for x86_64
69	75		Compiling staticlibdemo.pas
70	76		Assembling (pipe) staticlibdemo.s
71	77		Linking staticlibdemo
72	78		Undefined symbols for architecture x86_64:
73	79		"_cvtString", referenced from:
74	80		_PASCALMAIN in staticlibdemo.o
75	81		ld: symbol(s) not found for architecture x86_64
76	82		An error occurred while linking
77	83		staticlibdemo.pas(11,34) Error: Error while linking
78	84		staticlibdemo.pas(11,34) Fatal: There were 1 errors compiling module, stopping
79	85		Fatal: Compilation aborted
80	86		Error: /usr/local/bin/ppcx64 returned an error exitcode
81	87		```
82	88
83	89		What happened? Why wasn't our library function `cvtString` found? Let's look for our function in the `test.o` object file by running the `objdump` command line utility:
84	90
85	91		``` asm
86	92		$ objdump -d test.o
87	93		test.o: file format Mach-O 64-bit x86-64
88	94
89	95		Disassembly of section __TEXT,__text:
90	96		_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR:
91	97		0: 55 pushq %rbp
92	98		1: 48 89 e5 movq %rsp, %rbp
93	99		4: 48 8d 64 24 80 leaq -128(%rsp), %rsp
94	100		9: 48 89 7d f8 movq %rdi, -8(%rbp)
95	101		d: 48 8b 7d f8 movq -8(%rbp), %rdi
96	102		11: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x16>
97	103		16: 48 c7 45 88 00 00 00 00 movq $0, -120(%rbp)
98	104		1e: 48 8d 55 d8 leaq -40(%rbp), %rdx
99	105		22: 48 8d 75 98 leaq -104(%rbp), %rsi
100	106		26: bf 01 00 00 00 movl $1, %edi
101	107		2b: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x30>
102	108		30: 48 89 c7 movq %rax, %rdi
103	109		33: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x38>
104	110		38: 48 63 d0 movslq %eax, %rdx
105	111		3b: 48 89 55 90 movq %rdx, -112(%rbp)
106	112		3f: 83 f8 00 cmpl $0, %eax
107	113		42: 75 22 jne 34 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x66>
108	114		44: 48 8b 75 f8 movq -8(%rbp), %rsi
109	115		48: 48 8d 7d 88 leaq -120(%rbp), %rdi
110	116		4c: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x51>
111	117		51: 48 8b 45 88 movq -120(%rbp), %rax
112	118		55: 48 83 f8 00 cmpq $0, %rax
113	119		59: 75 07 jne 7 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x62>
114	120		5b: 48 8b 05 00 00 00 00 movq (%rip), %rax
115	121		62: 48 89 45 f0 movq %rax, -16(%rbp)
116	122		66: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x6b>
117	123		6b: 48 8d 7d f8 leaq -8(%rbp), %rdi
118	124		6f: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x74>
119	125		74: 48 8d 7d 88 leaq -120(%rbp), %rdi
120	126		78: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x7d>
121	127		7d: 48 8b 45 90 movq -112(%rbp), %rax
122	128		81: 48 83 f8 00 cmpq $0, %rax
123	129		85: 74 0f je 15 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x96>
124	130		87: e8 00 00 00 00 callq 0 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x8c>
125	131		8c: 48 c7 45 90 00 00 00 00 movq $0, -112(%rbp)
126	132		94: eb d0 jmp -48 <_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR+0x66>
127	133		96: 48 8b 45 f0 movq -16(%rbp), %rax
128	134		9a: 48 89 ec movq %rbp, %rsp
129	135		9d: 5d popq %rbp
130	136		9e: c3 retq
131	137		```
132	138
133	139		Aha! Our function name has been well and truly mangled. It is obvious we need to use the mangled name `TEST_$$_CVTSTRING$ANSISTRING$$PCHAR` (omit the underscore as the linker will automatically add it) rather than the unmangled `cvtString`. Our example application now looks like:
134	140
135	141		``` pascal
136	142		{$mode objfpc} {$H+}
137	143
138	144		// Link in our static library
139	145		// - note the prefix (lib) and extension (.a) are not necessary
140	146		{$LinkLib test}
141	147
142	148		program statlibdemo;
143	149
144	150		// Declare our function
145	151		function cvtString(strIn : string) : PChar; Cdecl; External Name 'TEST_$$_CVTSTRING$ANSISTRING$$PCHAR';
146	152
147	153		begin
148	154		WriteLn(cvtString('hello world'));
149	155		end.
150	156		```
151	157
152	158		Compile:
153	159
154		-	~~` fpc statlibdemo.pas`~~
	160	+	```text
	161	+	fpc statlibdemo.pas
	162	+	```
155	163
156	164		which again dashes our hopes and produces:
157	165
158	166		```text
159	167		Free Pascal Compiler version 3.3.1 [2020/04/20] for x86_64
160	168		Copyright (c) 1993-2020 by Florian Klaempfl and others
161	169		Target OS: Darwin for x86_64
162	170		Compiling staticlibdemo.pas
163	171		Assembling (pipe) staticlibdemo.s
164	172		Linking staticlibdemo
165	173		Undefined symbols for architecture x86_64:
166	174		"_SYSUTILS_$$_UPPERCASE$ANSISTRING$$ANSISTRING", referenced from:
167	175		_TEST_$$_CVTSTRING$ANSISTRING$$PCHAR in libtest.a(test.o)
168	176		ld: symbol(s) not found for architecture x86_64
169	177		An error occurred while linking
170	178		staticlibdemo.pas(11,34) Error: Error while linking
171	179		staticlibdemo.pas(11,34) Fatal: There were 1 errors compiling module, stopping
172	180		Fatal: Compilation aborted
173	181		Error: /usr/local/bin/ppcx64 returned an error exitcode
174	182		```
175	183
176	184		Unfortunately we are missing the object file for the `UpperCase` function which was pulled in from the FPC SysUtils unit. What to do? Simply add the SysUtils unit to the the Uses clause of the application. Our example application now looks like:
177	185
178	186		``` pascal
179	187		{$mode objfpc} {$H+}
180	188
181	189		// Link in our static library
182	190		// - note the prefix (lib) and extension (.a) are not necessary
183	191		{$LinkLib test}
184	192
185	193		program statlibdemo;
186	194
187	195		// Needed for linking in the UpperCase function
188	196		Uses
189	197		SysUtils;
190	198
191	199		// Declare our function
192	200		function cvtString(strIn : string) : PChar; Cdecl; External Name 'TEST_$$_CVTSTRING$ANSISTRING$$PCHAR';
193	201
194	202		begin
195	203		WriteLn(cvtString('hello world'));
196	204		end.
197	205		```
198	206
199	207		Third time lucky, compile:
200	208
201		-	~~` fpc statlibdemo.pas`~~
	209	+	```text
	210	+	fpc statlibdemo.pas
	211	+	```
202	212
203	213		Run:
204	214
205	215		``` bash
206	216		$ ./statlibdemo
207	217		HELLO WORLD
208	218		```
209	219
210	220		## Example C static library
211	221
212	222		myfunc1.c
213	223
214	224		``` c
215	225		#include <stdio.h>
216	226
217	227		void myfunc1()
218	228		{
219	229		printf("This is my func1!\n");
220	230		}
221	231		```
222	232
223	233		myfunc2.c
224	234
225	235		``` c
226	236		#include <ctype.h>
227	237
228	238		int myfunc2(int c)
229	239		{
230	240		c = toupper(c);
231	241		return(c);
232	242		}
233	243		```
234	244
235	245		Compile:
236	246
237	247		> Note: If you do not specify the minimum macOS version, the C compiler will compile for your current operating system version, but your Free Pascal Compiler will compile for 10.5 (FPC 3.0.4) or 10.8 (FPC 3.2.0 and later) by default.
238	248
239		-	~~`cc -c -mmacosx-version-min=10.8 myfunc1.c myfunc2.c`~~
	249	+	```text
	250	+	cc -c -mmacosx-version-min=10.8 myfunc1.c myfunc2.c
	251	+	```
240	252
241	253		which produces object files named myfunc1.o and myfunc2.o which we will now convert into a static library archive named `libmyfuncs.a` using the `libtool` command line utility:
242	254
243		-	~~`libtool -static -o libmyfuncs.a myfunc1.o myfunc2.o`~~
	255	+	```text
	256	+	libtool -static -o libmyfuncs.a myfunc1.o myfunc2.o
	257	+	```
244	258
245	259		## Example FPC application to use C static library
246	260
247	261		statlibdemo.pas:
248	262
249	263		``` pascal
250	264		{$mode objfpc}
251	265		{$linklib myfuncs}
252	266
253	267		procedure myfunc1; cdecl; external;
254	268		function myfunc2(c : integer) : integer; cdecl; external;
255	269
256	270		begin
257	271		myfunc1;
258	272
259	273		write('This is my func2 - Before: "b" ');
260	274		writeLn('After : ' + '"' + chr(myfunc2(ord('b'))) + '"');
261	275		end.
262	276		```
263	277
264	278		Compile:
265	279
266		-	~~`fpc statlibdemo.pas`~~
	280	+	```text
	281	+	fpc statlibdemo.pas
	282	+	```
267	283
268	284		Run:
269	285
270	286		``` bash
271	287		$ ./statlibdemo
272	288		This is my func1!
273	289		This is my func2 - Before: "b" After : "B"
274	290		```
275	291
276	292		If you need to check whether your external routines have been linked into the final application, you can use the `objdump` command line utility:
277	293
278	294		``` asm
279	295		$ objdump -d staticlibdemo \| grep -A13 ^_myfunc
280	296		_myfunc1:
281	297		100000830: 55 pushq %rbp
282	298		100000831: 48 89 e5 movq %rsp, %rbp
283	299		100000834: 48 83 ec 10 subq $16, %rsp
284	300		100000838: 48 8d 3d 7f 44 02 00 leaq 148607(%rip), %rdi
285	301		10000083f: b0 00 movb $0, %al
286	302		100000841: e8 e6 3d 02 00 callq 146918 <dyld_stub_binder+0x10002462c>
287	303		100000846: 89 45 fc movl %eax, -4(%rbp)
288	304		100000849: 48 83 c4 10 addq $16, %rsp
289	305		10000084d: 5d popq %rbp
290	306		10000084e: c3 retq
291	307		10000084f: 90 nop
292	308
293	309		_myfunc2:
294	310		100000850: 55 pushq %rbp
295	311		100000851: 48 89 e5 movq %rsp, %rbp
296	312		100000854: 48 83 ec 10 subq $16, %rsp
297	313		100000858: 89 7d fc movl %edi, -4(%rbp)
298	314		10000085b: 8b 7d fc movl -4(%rbp), %edi
299	315		10000085e: e8 29 3e 02 00 callq 146985 <dyld_stub_binder+0x10002468c>
300	316		100000863: 89 45 fc movl %eax, -4(%rbp)
301	317		100000866: 8b 45 fc movl -4(%rbp), %eax
302	318		100000869: 48 83 c4 10 addq $16, %rsp
303	319		10000086d: 5d popq %rbp
304	320		10000086e: c3 retq
305	321		10000086f: 90 nop
306	322		```
307	323
308	324		If you don't care for the assembly language, you can also use the `nm` command line utility:
309	325
310	326		``` bash
311	327		nm staticlibdemo \| grep myfunc
312	328		0000000100000830 T _myfunc1
313	329		0000000100000850 T _myfunc2
314	330		```
315	331
316	332		## See also
317	333
318	334		- [[macOS Dynamic Libraries]] for the same FPC library being used as a dynamic library.
319	335		- [[macOS Frameworks]] - structured directories for dynamic libraries and associated resources.
320	336		- [[macOS Programming Tips\|macOS Libraries]].
321	337
322	338		---
323	339		From the Free Pascal wiki, page "macOS Static Libraries", as it stood on 2022-02-04 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history