Lazarus/FPC Libraries: what changed

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

Old	New		Line
1	1		This page describes the possibilities for creating libraries with Lazarus/FPC and using them in projects and packages.
2	2
3	3		## Related Topics
4	4
5	5		- [[Creating bindings for C libraries]] - How to convert C header files (.h) to pascal units
6	6
7	7		## General
8	8
9	9		### Static linking
10	10
11	11		FPC compiles and links a static executable by default. That means it tells the linker to put all .o files of the project and all packages into one big executable.
12	12
13	13		- Advantages:
14	14		- No external dependencies.
15	15		- Disadvantages:
16	16		- No code is shared between different programs on the same computer.
17	17		- You can not load/unload a plugin.
18	18
19	19		### Dynamic libraries
20	20
21	21		The alternative to static linking is using dynamic libraries. The idea of dynamic libraries is to share code between programs,
22	22
23	23		- Advantages:
24	24		- Saving the memory of the code
25	25		- Reducing startup time for often used libraries
26	26		- Allowing plugins.
27	27		- Disadvantages:
28	28		- They are slower for seldomly used libs.
29	29		- Their structure and internals are more complicated (this is mainly a problem for the compiler).
30	30		- Their initialization is different (see below)
31	31		- Sharing code requires a version system to only mix compatible code.
32	32
33	33		## Operating Systems
34	34
35	35		\| Operating System \| Dynamic library extension \| Static library extension \| Library prefix \|
36	36		\|----\|----\|----\|----\|
37	37		\| FreeBSD \| .so \| .a \| lib \|
38	38		\| macOS \| .dylib \| .a \| lib \|
39	39		\| Linux \| .so \| .a \| lib \|
40	40		\| Windows \| .dll \| .lib \| n/a \|
41	41		\| Haiku \| .so \| .a \| lib \|
42	42
43	43		The library prefix and extension columns indicate how the names of libraries are resolved and created for the listed operating systems.
44	44
45	45		### FreeBSD
46	46
47	47		To Do.
48	48
49	49		### macOS
50	50
51	51		Under macOS, the library name will always have the lib prefix when it is created. So if you create a dynamic library called test, this will result in the file `libtest.dylib`. When importing routines from shared libraries, it is not necessary to give the library prefix or the library filename extension.
52	52
53	53		Before [[User Changes 2.2.2\|FPC 2.2.2]] released in August 2008, 32 bit .dylibs required exported symbols to be prefixed with an underscore. This is no longer the case.
54	54
55	55		The standard locations for dynamic libraries are `~/lib`, `/usr/local/lib`, and `/usr/lib`. Starting with macOS 10.15 (Catalina) `/usr/lib` is on the system read-only volume so cannot be used for third-party libraries. While you may also place the .dylib file in a non-standard location in your file system, you then must add that location to one of these environment variables:
56	56
57	57		- LD_LIBRARY_PATH
58	58		- DYLD_LIBRARY_PATH
59	59		- DYLD_FALLBACK_LIBRARY_PATH
60	60
61	61		Private shared libraries should be included in your application's [[Application Bundle]]. This is especially important for libraries which do not have a stable ABI (eg OpenSSL) so that they are revision-locked to the application and cannot be superseded by any other, even newer, versions that may be available to the operating system.
62	62
63	63		Refer to the See also section below for additional macOS information.
64	64
65	65		### Linux
66	66
67	67		A dynamic library filename always has the form 'lib'+packagename+'.so'+version. For example: `libz.so.1` and `libz.so.1.2.2`.
68	68
69	69		Linux searches a library in this order:
70	70
71	71		- first in the paths of the environment variable `LD_LIBRARY_PATH`
72	72		- then in /lib
73	73		- then /usr/lib
74	74		- finally the paths of `/etc/ld.so.conf`
75	75
76	76		Using `ldconfig` after copying your library file into a lib directory may help with caching issues.
77	77
78	78		To share memory (`GetMem`/`FreeMem`, strings) with other libraries (not written in FPC) under Linux, you should use the unit cmem. This unit must be added as the very first unit in the uses section of the project main source file (typically .lpr), so that its initialization section is called before any other unit can allocate memory.
79	79
80	80		### Windows
81	81
82	82		Windows searches a library in:
83	83
84	84		- first in the current directory
85	85		- then the system directory
86	86		- finally the directories specified in the environment variable PATH (system and user path).
87	87
88	88		to do: wasn't there a change in Vista+ behaviour for this?
89	89
90	90		When using an FPC made DLL with a non-FPC host application, exception handling can lead to some problems. Workarounds are mentioned in the #Initialization section.
91	91
92	92		## ppumove, .ppu, .ppl
93	93
94	94		FPC normally creates for every unit a .ppu and .o file. The .ppu file contains every important information of the .pas/.pp file (types, required filenames like the .o file), while the .o file contains the assembler code and the mangled names understood by the current system.
95	95
96	96		The ppumove tool included with every FPC installation, converts one or several .ppu and .o files into a dynamic library. It does this by calling the linker to gather all .o files into a .so (windows: .dll) file and removes the .o filename references from the .ppu file. These new .ppu files are normally called .ppl files.
97	97
98	98		For example:
99	99
100	100		You have the output directory of a package (where the .ppu files are):
101	101
102	102		``` bash
103	103		ppumove -o packagename -e ppl *.ppu
104	104		```
105	105
106	106		This will convert all .ppu files into .ppl files and creates a libpackagename.so (windows: packagename.dll). Note that under Linux the prefix 'lib' is always prepended.
107	107
108	108		This new library can already be used by other programming languages like C. Or by FPC programs by using the external modifiers. But the initialization/finalization sections must be called automatically. This includes the initialization/finalization of the heap manager. This means no strings or GetMem. Of course FPC programmers are spoiled and they can get more.
109	109
110	110		## External - statically loading a dynamic library
111	111
112	112		The static loading of a dynamic library can be done in code, by using the external keyword, like in the example below which shows how a gtk function is loaded:
113	113
114	114		``` pascal
115	115		const
116	116		{$ifdef win32}
117	117		gtklib = 'libgtk-win32-2.0-0.dll';
118	118		{$else}
119	119		{$ifdef darwin}
120	120		gtklib = 'gtk-x11-2.0';
121	121		{$linklib gtk-x11-2.0}
122	122		{$else}
123	123		gtklib = 'libgtk-x11-2.0.so';
124	124		{$endif}
125	125		{$endif}
126	126
127	127		procedure gtk_widget_set_events(widget:PGtkWidget; events:gint); cdecl; external gtklib;
128	128		```
129	129
130	130		## Loadlibrary - dynamically loading a dynamic library
131	131
132	132		Loading a dynamic library is simple with the Loadlibrary function of the unit dynlibs.
133	133
134	134		The main problem is to get the filename, which depends on the version and the operating system. Since 2.2.2, a constant "sharedsuffix" is declared in unit dynlibs to ease this. It maps to the relevant extension (dll/so/dylib) without a point as prefix.
135	135
136	136		Here are the functions declared in the unit dynlibs:
137	137
138	138		``` pascal
139	139		Function SafeLoadLibrary(Name : AnsiString) : TLibHandle;
140	140		Function LoadLibrary(Name : AnsiString) : TLibHandle;
141	141		Function GetProcedureAddress(Lib : TlibHandle; ProcName : AnsiString) : Pointer;
142	142		Function UnloadLibrary(Lib : TLibHandle) : Boolean;
143	143		```
144	144
145	145		SafeLoadLibrary is the same as LoadLibrary but it also disables arithmetic exceptions which some libraries expect to be off on loading.
146	146
147	147		Pseudocode of the usage:
148	148
149	149		``` pascal
150	150		uses dynlibs;
151	151
152	152		var
153	153		MyLibC: TLibHandle;
154	154		MyProc: TMyProc;
155	155		begin
156	156		MyLibC := LoadLibrary('libc.' + SharedSuffix);
157	157		if MyLibC = 0 then Exit;
158	158		MyProc := TMyProc(GetProcedureAddress(MyLibC, 'getpt');
159	159		if MyProc = nil then Exit;
160	160		end;
161	161		```
162	162
163	163		Pseoudocode for using a function, taking parameters:
164	164
165	165		``` pascal
166	166		uses ...dynlibs...
167	167
168	168		procedure UseDLL;
169	169		type
170	170		TMyFunc=function (aInt:Integer; aStr: string):String; StdCall;
171	171		var
172	172		MyLibC: TLibHandle= dynlibs.NilHandle;
173	173		MyFunc: TMyFunc;
174	174		FuncResult: string;
175	175		begin
176	176		MyLibC := LoadLibrary('libc.' + SharedSuffix);
177	177		if MyLibC = dynlibs.NilHandle then Exit; //DLL was not loaded successfully
178	178		MyFunc:= TMyFunc(GetProcedureAddress(MyLibC, 'MyFunc');
179	179		FuncResult:= MyFunc (5,'Test'); //Executes the function
180	180		if MyLibC <> DynLibs.NilHandle then if FreeLibrary(MyLibC) then MyLibC:= DynLibs.NilHandle; //Unload the lib, if already loaded
181	181		end;
182	182		```
183	183
184	184		> Note: Before 1.9.4, the unit dl was used for this. Since 1.9.4, dynlibs provides a portable alternative. Note that pretty much any use of unit dl that can't be substituted by using dynlibs is typically already unportable amongst Unices. This alone makes it advisable to use unit dynlibs as much as possible.
185	185
186	186		### Simplified overview of the system, when loading a shared library under Linux
187	187
188		-	~~<img src="lazarus_free_pascal_libraries_loading_under_linux.png" title="Loading a shared library..." width="350" alt="Loading a shared library..." />\~~
	188	+	![Loading a shared library...](/wiki-images/a/ad/Lazarus_free_pascal_libraries_loading_under_linux.png)\
189	189		This chart summarizes how to configure a shared library (referenced by its soname, and its real-name, at least) in /etc/ld.so.conf and to update the library cache using ldconfig utility, to inform the Linux system library loader named ldd (other methods to load a shared library, with an environment variable like LD_LIBRARY_PATH, with code, by inclusion in the binary elf, etc, are also illustrated in the chart). For information, it's often necessary to check if a soft-symlink exists between the soname and the real-name, at least. The installation of development packages (-dev.deb files, for a Debian installation) always delivers such soft-symlink (ex.: abc.so) pointing to the soname (ex.: abc.so.{9}) on which the development package depends. Release packages sometimes forget this, whereas they are best placed to retrieve and to make point an old installation towards a new installed real-name library: indeed, shared libraries should respect the takeover of precedence in their existing APIs, features, at least inside the same soname (backward compatibility).
190	190
191	191		## Creating a library
192	192
193	193		See the Free Pascal Documentation: <http://www.freepascal.org/docs-html/prog/progse55.html>
194	194
195	195		## Initialization
196	196
197	197		Every unit can contain an initialization section. The order of the initialization sections depend on the uses sections of each unit.
198	198
199	199		The initialization of the RTL itself (in system.pp) that is done before your initialization sections are entered slightly differs between a program and a shared library. Most notably there is a difference in how the exception handling is initialized:
200	200
201	201		### Exception handling
202	202
203	203		#### Windows
204	204
205	205		On Windows systems it has been [reported](http://bugs.freepascal.org/view.php?id=12974) that there is no exception handler installed to catch hardware exceptions like access violations or floating point errors; all other native Pascal exceptions that are raised with Raise will work however.
206	206
207	207		If you really need to catch these hardware exceptions you have to install your own handler, on Windows (beginning with versions XP and later) this is conveniently possible with AddVectoredExceptionHandler() and RemoveVectoredExceptionHandler(), there are some code examples in the above mentioned bug report. Note: work has been started in FPC 2.7.1/trunk to address this problem using 32 bit SEH.
208	208
209	209		#### UNIX and UNIX-like systems
210	210
211	211		On UNIX and UNIX-like systems (BSD, Darwin, Linux etc) no exception handler is installed to catch hardware exceptions (signals) like access violations in shared libraries. If you wish to catch these exceptions (signals) in a library code, you need to explicitly call `HookSignal(RTL_SIGDEFAULT)` during library initialization and call `UnhookSignal(RTL_SIGDEFAULT)` during finalization.
212	212
213	213		Keep in mind that when you enable signal handling in your shared library, it will replace signal handlers installed by a host application or other shared libraries of the current process. It may cause unexpected behavior. It is known that Java on Linux uses the SIGSEGV signal for its internal functionality and will crash if a third-party JNI library overrides the SIGSEGV signal handler.
214	214
215	215		### FPU mask
216	216
217	217		For Delphi compatibility reasons, Free Pascal on i386 will [unmask](http://bugs.freepascal.org/view.php?id=16801) all FPU exceptions in the floating point unit (but without installing a handler for the dll, see above). This unmasking is done before your initialization section begins. If your DLL will be used with a host application that is made with a different compiler (almost all other compilers except FPC and Delphi/ C++ Builder please verify C++ builder) this will badly interfere with the host application's exception handling.
218	218
219	219		After the LoadLibrary() call, the host application won't be able to catch any floating point exceptions anymore. The FPU will suddenly have gained the ability to throw hardware exceptions (in the thread that called LoadLibrary()), and the host application will most likely not expect this to happen and not be able to handle it properly. The workaround is to put
220	220
221	221		``` pascal
222	222		Set8087CW(Get8087CW or $3f);
223	223		```
224	224
225	225		in the initialization section to mask them again for the thread that loaded the library. This won't have any unwanted side effects other than restoring what the host application had all the time. In your DLL you would not have been able to catch them anyway (at least not on Windows, see above). If you really need to catch zero-divide and related errors in a DLL that is written for a non-FPC application, you have to
226	226
227	227		- have a handler installed like mentioned above
228	228		- temporarily unmask the FPU before the try
229	229		- mask it again before you return to the host application
230	230
231	231		## Finalization
232	232
233	233		Every unit can contain a finalization section. The order is the reverse order of the initialization sections.
234	234
235	235		After all finalization sections are executed it will call the procedure that you have previously assigned to Dll_Process_Detach_Hook.
236	236
237	237		Be very careful what you do in this procedure:
238	238
239	239		- all other units will already be finalized
240	240		- parts of the RTL might not work as expected anymore
241	241		- creating and freeing objects on the heap or even using Pascal strings inside this procedure is a sure way to call for trouble.
242	242
243	243		If you have to stop threads and free objects you must find a way to do this before the library unloading - it is too late to do it here.
244	244
245	245		## Versions, Distribution
246	246
247	247		Libraries tend to grow and change over time. Adding new features is no problem, but removing a public method or changing its parameters makes the library incompatible. That means either an installed library (.so, .dll, .dylib) is replaced by a compatible one or a new library must be added to the system. That's why every library contains a version.
248	248
249	249		To do: explain how to set/use this version both on Windows and *nix
250	250
251	251		To load a dynamic library (dlopen of unit dynlibs) the correct filename must be known. Under Linux this means that you have to know the version number.
252	252
253	253		To do: proposal how the IDE should create version numbers
254	254
255	255		## See also
256	256
257	257		- [[macOS Programming Tips\|macOS Programming Tips - Libraries]]
258	258		- [[macOS Dynamic Libraries]]
259	259		- [[macOS Static Libraries]]
260	260		- FPC [[shared library]]
261	261		- FPC [[packages]]
262	262		- [[Translations / i18n / localizations for programs]]
263	263
264	264		---
265	265		From the Free Pascal wiki, page "Lazarus/FPC Libraries", as it stood on 2021-09-24 after a change by Eric69, 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