macOS Dynamic 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 dynamic 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		library TestLibrary;
9	9
10	10		{$mode objfpc} {$H+}
11	11
12	12		uses
13	13		// needed for UpperCase
14	14		SysUtils;
15	15
16	16		// library subroutine
17	17		function cvtString(strIn : string) : PChar; cdecl;
18	18		begin
19	19		cvtString := PChar(UpperCase(strIn));
20	20		end;
21	21
22	22		// exported subroutine(s)
23	23		exports
24	24		cvtString;
25	25		end.
26	26		```
27	27
28	28		Compile:
29	29
30		-	~~` fpc test.pas`~~
	30	+	```text
	31	+	fpc test.pas
	32	+	```
31	33
32	34		which produces the dynamic library file named libtest.dylib.
33	35
34	36		## Universal 32 bit and 64 bit dynamic library
35	37
36	38		If needed to support both 32 bit and 64 bit architectures, `test.pas` can be compiled as a universal dynamic library that contains both 32 bit and 64 bit libraries:
37	39
38		-	~~`ppc386 test.pas`\~~
39		-	~~`ppcx64 -olibtest64.dylib test.pas`\~~
40		-	~~`lipo -create libtest.dylib libtest64.dylib -output libtest.dylib`~~
	40	+	```text
	41	+	ppc386 test.pas
	42	+	ppcx64 -olibtest64.dylib test.pas
	43	+	lipo -create libtest.dylib libtest64.dylib -output libtest.dylib
	44	+	```
41	45
42	46		To check that both architectures have been included in the dynamic library:
43	47
44		-	~~`$ file libtest.dylib`\~~
45		-	~~`libtest.dylib: Mach-O universal binary with 2 architectures: [i386:Mach-O dynamically linked shared library i386] [x86_64:Mach-O 64-bit dynamically linked shared library x86_64]`\~~
46		-	~~`libtest.dylib (for architecture i386): Mach-O dynamically linked shared library i386`\~~
47		-	~~`libtest.dylib (for architecture x86_64): Mach-O 64-bit dynamically linked shared library x86_64`~~
	48	+	```text
	49	+	$ file libtest.dylib
	50	+	libtest.dylib: Mach-O universal binary with 2 architectures: [i386:Mach-O dynamically linked shared library i386] [x86_64:Mach-O 64-bit dynamically linked shared library x86_64]
	51	+	libtest.dylib (for architecture i386): Mach-O dynamically linked shared library i386
	52	+	libtest.dylib (for architecture x86_64): Mach-O 64-bit dynamically linked shared library x86_64
	53	+	```
48	54
49	55		Too easy!
50	56
51	57		## Example application to load FPC dynamic library
52	58
53	59		This version of the example application loads the dynamic library on demand when necessary (load-time dynamic linking aka dynamic loading) and can also unload it when it is no longer necessary. You can successfully compile the application even if the dynamic library does not exist.
54	60
55	61		The alternative example version that follows loads the dynamic library at start-up (run-time dynamic linking aka dynamic linking) and cannot unload it until the application quits. You cannot successfully compile the application unless the dynamic library exists.
56	62
57	63		dynlibdemo.pas:
58	64
59	65		``` pascal
60	66		Program dynlibdemo;
61	67
62	68		{$mode objfpc}{$H+}
63	69
64	70		uses
65	71		Dynlibs,
66	72		SysUtils;
67	73
68	74		type
69	75		// definition of the subroutine to be called as defined in the dynamic library to be loaded
70	76		TcvtString = function(strToConvert : string) : PChar; cdecl;
71	77
72	78		var
73	79		// create suitable variable for the dynamic library subroutine
74	80		cvtString : TcvtString;
75	81
76	82		// create a handle for the dynamic library
77	83		LibHandle : TLibHandle;
78	84
79	85		begin
80	86		// load and get the dynamic library handle
81	87		LibHandle := LoadLibrary(PChar('libtest.dylib'));
82	88
83	89		// check whether loading was successful
84	90		if LibHandle <> 0 then
85	91		begin
86	92		// assign address of the subroutine call to the variable cvtString
87	93		Pointer(cvtString) := GetProcAddress(LibHandle, 'cvtString');
88	94
89	95		// check whether a valid address has been returned
90	96		if @cvtString <> nil then
91	97		WriteLn(cvtString('hello world'))
92	98		// error message on no valid address
93	99		else
94	100		WriteLn('GetLastOSError1 = ', SysErrorMessage(GetLastOSError));
95	101		end
96	102		else
97	103		// error message on load failure
98	104		WriteLn('GetLastOSError2 = ', SysErrorMessage(GetLastOSError));
99	105
100	106		// release memory
101	107		cvtString := nil;
102	108
103	109		// unload library
104	110		if LibHandle <> NilHandle then
105	111		UnloadLibrary(LibHandle);
106	112
107	113		LibHandle := NilHandle;
108	114		end.
109	115		```
110	116
111	117		Compile:
112	118
113		-	~~` fpc dynlibdemo.pas`~~
	119	+	```text
	120	+	fpc dynlibdemo.pas
	121	+	```
114	122
115	123		Run:
116	124
117	125		``` bash
118	126		$ ./dynlibdemo
119	127		HELLO WORLD
120	128		```
121	129
122	130		## Alternative example application to load FPC dynamic library
123	131
124	132		This version of the example application loads the dynamic library at startup (run-time dynamic linking aka dynamic linking) and cannot unload it. You cannot successfully compile the application unless the dynamic library exists.
125	133
126	134		The previous version of the example application loads the dynamic library when necessary (load-time dynamic linking aka dynamic loading) and can also unload it when it is no longer necessary. You can successfully compile the application even if the dynamic library does not exist.
127	135
128	136		alt_dynlibdemo.pas:
129	137
130	138		``` pascal
131	139		{$linklib libtest}
132	140
133	141		program alt_dynlibdemo;
134	142
135	143		{$mode objfpc} {$H+}
136	144
137	145		function cvtString(const strToConvert: string): PChar; cdecl; external;
138	146
139	147		begin
140	148		WriteLn(cvtString('hello world'));
141	149		end.
142	150		```
143	151
144	152		Compile:
145	153
146		-	~~` fpc alt_dynlibdemo.pas`~~
	154	+	```text
	155	+	fpc alt_dynlibdemo.pas
	156	+	```
147	157
148	158		Run:
149	159
150	160		``` bash
151	161		$ ./alt_dynlibdemo
152	162		HELLO WORLD
153	163		```
154	164
155	165		If you think the code looks like it statically links the library, you can verify that it does not by moving the library or renaming it and then re-running the demo application which produces output similar to this:
156	166
157	167		``` bash
158	168		$ ./alt_dynlibdemo
159	169		dyld: Library not loaded: /Users/[user]/fpc_dynamic_lib2/libtest.dylib
160	170		Referenced from: /Users/[user]/fpc_dynamic_lib2/./alt_dynlibdemo
161	171		Reason: image not found
162	172		Abort
163	173		```
164	174
165	175		## Additional steps using a Lazarus project
166	176
167	177		If you turn the pure FPC dynlibdemo.pas example above into a Lazarus project named project1 your unit should resemble:
168	178
169	179		``` pascal
170	180		unit Unit1;
171	181
172	182		{$mode objfpc}{$H+}
173	183
174	184		interface
175	185
176	186		uses
177	187		Dynlibs,
178	188		Classes, SysUtils, Forms, Controls, Graphics, Dialogs, StdCtrls;
179	189
180	190		type
181	191		// definition of the subroutine to be called as defined in the dynamic library to be loaded
182	192		TcvtString = function(strToConvert : string) : PChar; cdecl;
183	193
184	194		type
185	195
186	196		{ TForm1 }
187	197
188	198		TForm1 = class(TForm)
189	199		Button1: TButton;
190	200		procedure Button1Click(Sender: TObject);
191	201		private
192	202
193	203		public
194	204
195	205		end;
196	206
197	207		var
198	208		Form1: TForm1;
199	209
200	210		implementation
201	211
202	212		{$R *.lfm}
203	213
204	214		{ TForm1 }
205	215
206	216		procedure TForm1.Button1Click(Sender: TObject);
207	217		var
208	218		// create suitable variable for the dynamic library subroutine
209	219		cvtString : TcvtString;
210	220		// create a handle for the dynamic library
211	221		LibHandle : TLibHandle;
212	222		begin
213	223		// load and get the dynamic library handle
214	224		LibHandle := LoadLibrary(PChar('libtestlibrary.dylib'));
215	225
216	226		// check whether loading was successful
217	227		if LibHandle <> 0 then
218	228		begin
219	229		// assign address of the subroutine call to the variable cvtString
220	230		Pointer(cvtString) := GetProcAddress(LibHandle, 'cvtString');
221	231
222	232		// check whether a valid address has been returned
223	233		if @cvtString <> nil then
224	234		ShowMessage(cvtString('hello world'))
225	235		// error message on no valid address
226	236		else
227	237		ShowMessage('GetLastOSError1 = ' + SysErrorMessage(GetLastOSError));
228	238		end
229	239		else
230	240		// error message on load failure
231	241		ShowMessage('GetLastOSError2 = ' + SysErrorMessage(GetLastOSError));
232	242
233	243		// release memory
234	244		cvtString := nil;
235	245
236	246		// unload library
237	247		if LibHandle <> NilHandle then
238	248		UnloadLibrary(LibHandle);
239	249
240	250		LibHandle := NilHandle;
241	251		end;
242	252
243	253		end.
244	254		```
245	255
246	256		After creating an [[Application Bundle\|application bundle]] then you need to:
247	257
248	258		- Open a Terminal (Applications \> Utilities \> Terminal)
249	259		- Delete the `project1.app/Contents/MacOS/project1` symbolic link to the project1 executable file
250	260		- Copy the project1 executable file into the `project1.app/Contents/MacOS` directory
251	261		- Copy libtest.dylib into the `project1.app/Contents/Frameworks` directory (you need to create the Frameworks directory)
252	262		- Change into the `project1.app/Contents/MacOS` directory
253	263		- Either:
254	264		- Enter: `install_name_tool -add_rpath "@executable_path/../Frameworks/." project1` =or=
255	265		- In the Lazarus IDE go to Project \> Project Options \> Compiler Options \> Compilation and Linking and there you will have to check the option "Pass options to linker with -k, delimiter is space" and enter the following: `-rpath @executable_path/../Frameworks` (Do NOT include -k which Lazarus adds for FPC automatically).
256	266
257	267		This ensures that the project1 executable in your application bundle will look in your application bundle's Frameworks directory to find your dynamic library.
258	268
259	269		For more information on the install_name_tool command line utility, open a Terminal and enter:
260	270
261		-	~~` man install_name_tool`~~
	271	+	```text
	272	+	man install_name_tool
	273	+	```
262	274
263	275		For more information on the linker command line utility, open a Terminal and enter:
264	276
265		-	~~` man ld`~~
	277	+	```text
	278	+	man ld
	279	+	```
266	280
267	281		## Example application to load libc dynamic library
268	282
269	283		demo.pas
270	284
271	285		``` pascal
272	286		{$mode objfpc}
273	287		{$linklib C}
274	288
275	289		// Declarations for the standard C functions strlen and toupper
276	290		function strlen (P : pchar) : longint; cdecl; external;
277	291		function toupper(P : integer) : integer; cdecl; external;
278	292
279	293		begin
280	294		Write('"Programming is fun!" is ');
281	295		Write(strlen('Programming is fun!'));
282	296		WriteLn(' characters long.');
283	297		WriteLn('Before: "c" and after "' + chr(toupper(ord('c'))) + '".');
284	298		end.
285	299		```
286	300
287	301		Compile:
288	302
289		-	~~` fpc demo.pas`~~
	303	+	```text
	304	+	fpc demo.pas
	305	+	```
290	306
291	307		Run:
292	308
293		-	~~` $./demo`\~~
294		-	~~` "Programming is fun!" is 19 characters long.`\~~
295		-	~~` Before: "c" and after "C".`~~
	309	+	```text
	310	+	$./demo
	311	+	"Programming is fun!" is 19 characters long.
	312	+	Before: "c" and after "C".
	313	+	```
296	314
297	315		Be aware that, unlike for example FreeBSD and Linux, there is no static libc library on macOS. Instead, there is the dynamic system library (`/usr/lib/libSystem.dylib`) which includes the following libraries:
298	316
299	317		- libc
300	318		- The standard C library. This library contains the functions used by C programmers on all platforms.
301	319		- libinfo
302	320		- The NetInfo library.
303	321		- libkvm
304	322		- The kernel virtual memory library.
305	323		- libm
306	324		- The math library, which contains arithmetic functions.
307	325		- libpthread
308	326		- The POSIX threads library, which allows multiple tasks to run concurrently within a single program.
309	327		- libutil
310	328		- The library that provides functions related to login, logout, terminal assignment, and logging.
311	329
312	330		There are symbolic links in `/usr/lib` for all of these libraries pointing to `/usr/lib/libSystem.dylib` except libutil.
313	331
314	332		## Observe the dynamic linker in action
315	333
316	334		If you want to observe the dynamic linker in action, you can use the command line utility `dtruss`. Open a Terminal and run:
317	335
318		-	~~`$ sudo dtruss ./dynlibdemo`~~
	336	+	```text
	337	+	$ sudo dtruss ./dynlibdemo
	338	+	```
319	339
320	340		which will produce output similar to:
321	341
322	342		```text
323	343		SYSCALL(args) = return
324	344		HELLO WORLD
325	345		...
326	346		stat64("libtest.dylib\0", 0x7FFEE96A3A20, 0x0) = 0 0
327	347		open("libtest.dylib\0", 0x0, 0x0) = 3 0
328	348		...
329	349		fcntl(0x3, 0x62, 0x7FFEE969B1B0) = 0 0
330	350		mmap(0x106726000, 0x84000, 0x5, 0x12, 0x3, 0x0) = 0x106726000 0
331	351		mmap(0x1067AA000, 0x1D000, 0x3, 0x12, 0x3, 0x84000) = 0x1067AA000 0
332	352		mmap(0x1067C9000, 0x2A28, 0x1, 0x12, 0x3, 0xA1000) = 0x1067C9000 0
333	353		fcntl(0x3, 0x32, 0x7FFEE969B440) = 0 0
334	354		close(0x3) = 0 0
335	355		...
336	356		```
337	357
338	358		It is even more instructive to temporarily rename your dynamic library so it will not be found. This will produce output similar to:
339	359
340	360		```text
341	361		...
342	362		stat64("libtest.dylib\0", 0x7FFEE00E95E0, 0x0) = -1 Err#2
343	363		stat64("libtest.dylib\0", 0x7FFEE00E9A20, 0x0) = -1 Err#2
344	364		stat64("/Users/[user]/lib/libtest.dylib\0", 0x7FFEE00E9990, 0x0) = -1 Err#2
345	365		stat64("/Users/[user]/lib/libtest.dylib\0", 0x7FFEE00E9DD0, 0x0) = -1 Err#2
346	366		stat64("/\0", 0x7FFEE00E7D78, 0x0) = 0 0
347	367		getattrlist("/Users\0", 0x117102048, 0x7FFEE00E96D0) = 0 0
348	368		getattrlist("/Users/[user]\0", 0x117102048, 0x7FFEE00E96D0) = 0 0
349	369		getattrlist("/Users/[user]/lib\0", 0x117102048, 0x7FFEE00E96D0) = -1 Err#2
350	370		stat64("/Users/[user]/lib\0", 0x7FFEE00E9560, 0x0) = -1 Err#2
351	371		stat64("/Users/[user]/lib\0", 0x7FFEE00E99A0, 0x0) = -1 Err#2
352	372		stat64("/usr/local/lib/libtest.dylib\0", 0x7FFEE00E9990, 0x0) = -1 Err#2
353	373		stat64("/usr/local/lib/libtest.dylib\0", 0x7FFEE00E9DD0, 0x0) = -1 Err#2
354	374		getattrlist("/usr\0", 0x117102048, 0x7FFEE00E96D0) = 0 0
355	375		getattrlist("/usr/local\0", 0x117102048, 0x7FFEE00E96D0) = 0 0
356	376		getattrlist("/usr/local/lib\0", 0x117102048, 0x7FFEE00E96D0) = 0 0
357	377		getattrlist("/usr/local/lib/libtest.dylib\0", 0x117102048, 0x7FFEE00E96D0) = -1 Err#2
358	378		stat64("/usr/local/lib/libtest.dylib\0", 0x7FFEE00E9560, 0x0) = -1 Err#2
359	379		stat64("/usr/local/lib/libtest.dylib\0", 0x7FFEE00E99A0, 0x0) = -1 Err#2
360	380		stat64("/usr/lib/libtest.dylib\0", 0x7FFEE00E99A0, 0x0) = -1 Err#2
361	381		stat64("/usr/lib/libtest.dylib\0", 0x7FFEE00E9DE0, 0x0) = -1 Err#2
362	382		getattrlist("/usr\0", 0x117102048, 0x7FFEE00E96E0) = 0 0
363	383		getattrlist("/usr/lib\0", 0x117102048, 0x7FFEE00E96E0) = 0 0
364	384		getattrlist("/usr/lib/libtest.dylib\0", 0x117102048, 0x7FFEE00E96E0) = -1 Err#2
365	385		stat64("/usr/lib/libtest.dylib\0", 0x7FFEE00E9570, 0x0) = -1 Err#2
366	386		stat64("/usr/lib/libtest.dylib\0", 0x7FFEE00E99B0, 0x0) = -1 Err#2
367	387		open(".\0", 0x0, 0x1) = 3 0
368	388		fstat64(0x3, 0x7FFEE00E7CF0, 0x0) = 0 0
369	389		fcntl(0x3, 0x32, 0x7FFEE00E9CB0) = 0 0
370	390		close(0x3) = 0 0
371	391		stat64("/Users/[user]/LAZPROJECTS/fpc_dynamic_lib\0", 0x7FFEE00E7C60, 0x0) = 0 0
372	392		stat64("/Users/[user]/LAZPROJECTS/fpc_dynamic_lib\0", 0x7FFEE00E7EF8, 0x0) = 0 0
373	393		getattrlist("/Users/[user]/LAZPROJECTS/fpc_dynamic_lib/libtest.dylib\0", 0x117102048, 0x7FFEE00E9850) = -1 Err#2
374	394		stat64("/Users/[user]/LAZPROJECTS/fpc_dynamic_lib/libtest.dylib\0", 0x7FFEE00E96E0, 0x0) = -1 Err#2
375	395		stat64("/Users/[user]/LAZPROJECTS/fpc_dynamic_lib/libtest.dylib\0", 0x7FFEE00E9B20, 0x0) = -1 Err#2
376	396		...
377	397		```
378	398
379	399		The highlighted lines above show all the places the the system looked for the missing dynamic library.
380	400
381	401		## Standard locations for dynamic libraries
382	402
383	403		While in the above example we stored the dynamic library in the application bundle, the standard locations for dynamic libraries are `~/lib` (for single user) and `/usr/local/lib` (for multiple users). There used to also be `/usr/lib`, but that was locked-down in macOS 10.15 (Catalina) and later on the system read-only volume. You need to use the standard locations if you want to share the dynamic library among multiple applications.
384	404
385	405		If you must place the dynamic library file in a non-standard location in the file system, you then must also add that location to one of these environment variables:
386	406
387	407		- LD_LIBRARY_PATH
388	408		- DYLD_LIBRARY_PATH
389	409		- DYLD_FALLBACK_LIBRARY_PATH
390	410
391	411		Note: You cannot distribute an application through the Mac App Store that depends on a custom library being installed first by the user into `/usr/local/lib` so it is best to store your dynamic library or libraries in the application bundle.
392	412
393	413		For applications with a graphical user interface it not only makes sense to include any needed libraries in your application's Frameworks folder, Apple encourages it.
394	414
395	415		## Logging dynamic loader events
396	416
397	417		As you develop and use dynamic libraries, you may want to know when certain events occur. For example, you want to know when the dynamic loader binds a particular undefined external symbol or how long it took for an application to launch. Environment variables to the rescue. The environment variables that affect dynamic loader logging are:
398	418
399	419		\| Environment variable \| Description \|
400	420		\|----\|----\|
401	421		\| DYLD_PRINT_LIBRARIES \| Logs when images are loaded. \|
402	422		\| DYLD_PRINT_LIBRARIES_POST_LAUNCH \| Logs when images are loaded as a result of a dlopen call. Includes a dynamic libraries’ dependent libraries. \|
403	423		\| DYLD_PRINT_APIS \| Logs the invocation that causes the dynamic loader to return the address of a symbol. \|
404	424		\| DYLD_PRINT_STATISTICS \| Logs statistical information on an application’s launch process, such as how many images were loaded, when the application finishes launching. \|
405	425		\| DYLD_PRINT_INITIALIZERS \| Logs when the dynamic loader calls initializer and finalizer functions. \|
406	426		\| DYLD_PRINT_SEGMENTS \| Logs when the dynamic loader maps a segment of a dynamic library to the current process’s address space. \|
407	427		\| DYLD_PRINT_BINDINGS \| Logs when the dynamic loader binds an undefined external symbol with its definition. \|
408	428
409	429		For example, Open an Applications \> Utilities \> Terminal - note the shell being used below is `tcsh`:
410	430
411		-	~~`$ setenv DYLD_PRINT_STATISTICS`\~~
412		-	~~`$ ./my_app`\~~
413		-	~~`Total pre-main time: 13.41 milliseconds (100.0%)`\~~
414		-	~~` dylib loading time: 6.39 milliseconds (47.6%)`\~~
415		-	~~` rebase/binding time: 0.97 milliseconds (7.2%)`\~~
416		-	~~` ObjC setup time: 0.46 milliseconds (3.4%)`\~~
417		-	~~` initializer time: 5.40 milliseconds (40.2%)`\~~
418		-	~~` slowest intializers :`\~~
419		-	~~` libSystem.B.dylib : 1.19 milliseconds (8.9%)`\~~
420		-	~~` libobjc.A.dylib : 0.47 milliseconds (3.5%)`\~~
421		-	~~` CoreFoundation : 2.35 milliseconds (17.5%)`\~~
422		-	~~` AppKit : 0.61 milliseconds (4.6%)`\~~
423		-	~~`$ unsetenv DYLD_PRINT_STATISTICS`~~
	431	+	```text
	432	+	$ setenv DYLD_PRINT_STATISTICS
	433	+	$ ./my_app
	434	+	Total pre-main time: 13.41 milliseconds (100.0%)
	435	+	dylib loading time: 6.39 milliseconds (47.6%)
	436	+	rebase/binding time: 0.97 milliseconds (7.2%)
	437	+	ObjC setup time: 0.46 milliseconds (3.4%)
	438	+	initializer time: 5.40 milliseconds (40.2%)
	439	+	slowest intializers :
	440	+	libSystem.B.dylib : 1.19 milliseconds (8.9%)
	441	+	libobjc.A.dylib : 0.47 milliseconds (3.5%)
	442	+	CoreFoundation : 2.35 milliseconds (17.5%)
	443	+	AppKit : 0.61 milliseconds (4.6%)
	444	+	$ unsetenv DYLD_PRINT_STATISTICS
	445	+	```
424	446
425	447		For the default macOS shell `zsh`, use `export DYLD_PRINT_STATISTICS=1` and `unset DYLD_PRINT_STATISTICS` to set and unset an environment variable.
426	448
427	449		## See also
428	450
429	451		- [[Application Bundle]] - structure of a macOS application
430	452
431	453		- [[macOS Static Libraries]] for the same FPC library being used as a static library.
432	454
433	455		- [[macOS Frameworks]] - structured directories for dynamic libraries and associated resources.
434	456
435	457		- [[macOS Programming Tips\|macOS Libraries]].
436	458
437	459		- [[shared library\|FPC Shared Libraries]].
438	460
439	461		- [[macOS Big Sur changes for developers\|Big Sur's built-in dynamic linker cache]].
440	462
441	463		## External links
442	464
443	465		- [Apple Documentation: Dynamic Library Programming Topics](https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/DynamicLibraries/000-Introduction/Introduction.html#//apple_ref/doc/uid/TP40001908-SW1).
444	466
445	467		---
446	468		From the Free Pascal wiki, page "macOS Dynamic Libraries", as it stood on 2021-09-08 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