Lazarus/FPC Libraries: what changed
Revision 2 to 3. 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 | - | ||
| 14 | - | ||
| 15 | - | ||
| 16 | - | ||
| 17 | - | ||
| 13 | + | * Advantages: | |
| 14 | + | * No external dependencies. | |
| 15 | + | * Disadvantages: | |
| 16 | + | * No code is shared between different programs on the same computer. | |
| 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 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 29 | - | ||
| 30 | - | ||
| 31 | - | ||
| 23 | + | * Advantages: | |
| 24 | + | * Saving the memory of the code | |
| 25 | + | * Reducing startup time for often used libraries | |
| 26 | + | * Allowing plugins. | |
| 27 | + | * Disadvantages: | |
| 28 | + | * They are slower for seldomly used libs. | |
| 29 | + | * Their structure and internals are more complicated (this is mainly a problem for the compiler). | |
| 30 | + | * Their initialization is different (see below) | |
| 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 | - | ||
| 58 | - | ||
| 59 | - | ||
| 57 | + | * LD_LIBRARY_PATH | |
| 58 | + | * DYLD_LIBRARY_PATH | |
| 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 | - | ||
| 72 | - | ||
| 73 | - | ||
| 74 | - | ||
| 71 | + | * first in the paths of the environment variable `LD_LIBRARY_PATH` | |
| 72 | + | * then in /lib | |
| 73 | + | * then /usr/lib | |
| 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 | - | ||
| 85 | - | ||
| 86 | - | ||
| 84 | + | * first in the current directory | |
| 85 | + | * then the system directory | |
| 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 | - | ||
| 95 | - | ||
| 96 | - | ||
| 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. | |
| 97 | 95 | ||
| 98 | - | ||
| 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**. | |
| 99 | 97 | ||
| 100 | - | ||
| 98 | + | For example: | |
| 101 | 99 | ||
| 102 | - | ||
| 100 | + | You have the output directory of a package (where the .ppu files are): | |
| 101 | + | ``` | |
| 103 | 102 | ppumove -o packagename -e ppl *.ppu | |
| 104 | 103 | ``` | |
| 105 | 104 | ||
| 106 | - | ||
| 105 | + | 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 | 106 | ||
| 108 | - | ||
| 107 | + | 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 | 108 | ||
| 110 | 109 | ## External - statically loading a dynamic library | |
| 111 | 110 | ||
| 112 | - | ||
| 113 | - | ||
| 114 | - | ||
| 111 | + | 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: | |
| 112 | + | ``` | |
| 115 | 113 | const | |
| 116 | - | ||
| 117 | - | ||
| 118 | - | ||
| 119 | - | ||
| 120 | - | ||
| 121 | - | ||
| 122 | - | ||
| 123 | - | ||
| 124 | - | ||
| 125 | - | ||
| 126 | - | ||
| 127 | - | ||
| 114 | + | {$ifdef win32} | |
| 115 | + | gtklib = 'libgtk-win32-2.0-0.dll'; | |
| 116 | + | {$else} | |
| 117 | + | {$ifdef darwin} | |
| 118 | + | gtklib = 'gtk-x11-2.0'; | |
| 119 | + | {$linklib gtk-x11-2.0} | |
| 120 | + | {$else} | |
| 121 | + | gtklib = 'libgtk-x11-2.0.so'; | |
| 122 | + | {$endif} | |
| 123 | + | {$endif} | |
| 124 | + | ||
| 125 | + | procedure gtk_widget_set_events(widget:PGtkWidget; events:gint); cdecl; external gtklib; | |
| 128 | 126 | ``` | |
| 129 | 127 | ||
| 130 | 128 | ## Loadlibrary - dynamically loading a dynamic library | |
| 131 | 129 | ||
| 132 | - | ||
| 133 | - | ||
| 134 | - | ||
| 130 | + | Loading a dynamic library is simple with the Loadlibrary function of the unit dynlibs. | |
| 135 | 131 | ||
| 136 | - | ||
| 132 | + | 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. | |
| 137 | 133 | ||
| 138 | - | ||
| 134 | + | Here are the functions declared in the unit dynlibs: | |
| 135 | + | ``` | |
| 139 | 136 | Function SafeLoadLibrary(Name : AnsiString) : TLibHandle; | |
| 140 | - | ||
| 141 | - | ||
| 142 | - | ||
| 137 | + | Function LoadLibrary(Name : AnsiString) : TLibHandle; | |
| 138 | + | Function GetProcedureAddress(Lib : TlibHandle; ProcName : AnsiString) : Pointer; | |
| 139 | + | Function UnloadLibrary(Lib : TLibHandle) : Boolean; | |
| 143 | 140 | ``` | |
| 144 | 141 | ||
| 145 | - | ||
| 146 | - | ||
| 147 | - | ||
| 142 | + | SafeLoadLibrary is the same as LoadLibrary but it also disables arithmetic exceptions which some libraries expect to be off on loading. | |
| 148 | 143 | ||
| 149 | - | ||
| 144 | + | Pseudocode of the usage: | |
| 145 | + | ``` | |
| 150 | 146 | uses dynlibs; | |
| 151 | - | ||
| 152 | - | ||
| 153 | - | ||
| 154 | - | ||
| 155 | - | ||
| 156 | - | ||
| 157 | - | ||
| 158 | - | ||
| 159 | - | ||
| 160 | - | ||
| 147 | + | ||
| 148 | + | var | |
| 149 | + | MyLibC: TLibHandle; | |
| 150 | + | MyProc: TMyProc; | |
| 151 | + | begin | |
| 152 | + | MyLibC := LoadLibrary('libc.' + SharedSuffix); | |
| 153 | + | if MyLibC = 0 then Exit; | |
| 154 | + | MyProc := TMyProc(GetProcedureAddress(MyLibC, 'getpt'); | |
| 155 | + | if MyProc = nil then Exit; | |
| 156 | + | end; | |
| 161 | 157 | ``` | |
| 162 | 158 | ||
| 163 | - | ||
| 164 | - | ||
| 165 | - | ||
| 159 | + | Pseoudocode for using a function, taking parameters: | |
| 160 | + | ``` | |
| 166 | 161 | uses ...dynlibs... | |
| 167 | - | ||
| 168 | - | ||
| 169 | - | ||
| 170 | - | ||
| 171 | - | ||
| 172 | - | ||
| 173 | - | ||
| 174 | - | ||
| 175 | - | ||
| 176 | - | ||
| 177 | - | ||
| 178 | - | ||
| 179 | - | ||
| 180 | - | ||
| 181 | - | ||
| 162 | + | ||
| 163 | + | procedure UseDLL; | |
| 164 | + | type | |
| 165 | + | TMyFunc=function (aInt:Integer; aStr: string):String; StdCall; | |
| 166 | + | var | |
| 167 | + | MyLibC: TLibHandle= dynlibs.NilHandle; | |
| 168 | + | MyFunc: TMyFunc; | |
| 169 | + | FuncResult: string; | |
| 170 | + | begin | |
| 171 | + | MyLibC := LoadLibrary('libc.' + SharedSuffix); | |
| 172 | + | if MyLibC = dynlibs.NilHandle then Exit; //DLL was not loaded successfully | |
| 173 | + | MyFunc:= TMyFunc(GetProcedureAddress(MyLibC, 'MyFunc'); | |
| 174 | + | FuncResult:= MyFunc (5,'Test'); //Executes the function | |
| 175 | + | if MyLibC <> DynLibs.NilHandle then if FreeLibrary(MyLibC) then MyLibC:= DynLibs.NilHandle; //Unload the lib, if already loaded | |
| 176 | + | end; | |
| 182 | 177 | ``` | |
| 183 | 178 | ||
| 184 | - | ||
| 179 | + | ||
| 185 | 180 | ||
| 181 | + |  **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. | |
| 182 | + | ||
| 186 | 183 | ### Simplified overview of the system, when loading a shared library under Linux | |
| 187 | 184 | ||
| 188 | - | ||
| 189 | - | ||
| 185 | + | [](</File:lazarus_free_pascal_libraries_loading_under_linux.png> "Loading a shared library...") | |
| 186 | + | 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 | 187 | ||
| 191 | 188 | ## Creating a library | |
| 192 | 189 | ||
| 193 | 190 | See the Free Pascal Documentation: <http://www.freepascal.org/docs-html/prog/progse55.html> | |
| 194 | 191 | ||
| 195 | 192 | ## Initialization | |
| 196 | 193 | ||
| 197 | - | ||
| 194 | + | Every unit can contain an initialization section. The order of the initialization sections depend on the uses sections of each unit. | |
| 198 | 195 | ||
| 199 | - | ||
| 196 | + | 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 | 197 | ||
| 201 | 198 | ### Exception handling | |
| 202 | 199 | ||
| 203 | 200 | #### Windows | |
| 204 | 201 | ||
| 205 | - | ||
| 202 | + | 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 | 203 | ||
| 207 | - | ||
| 204 | + | 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 | 205 | ||
| 209 | 206 | #### UNIX and UNIX-like systems | |
| 210 | 207 | ||
| 211 | - | ||
| 208 | + | 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 | 209 | ||
| 213 | - | ||
| 210 | + | 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 | 211 | ||
| 215 | 212 | ### FPU mask | |
| 216 | 213 | ||
| 217 | - | ||
| 218 | - | ||
| 219 | - | ||
| 214 | + | 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. | |
| 220 | 215 | ||
| 221 | - | ||
| 216 | + | 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 | |
| 217 | + | ``` | |
| 222 | 218 | Set8087CW(Get8087CW or $3f); | |
| 223 | 219 | ``` | |
| 224 | 220 | ||
| 225 | - | ||
| 221 | + | 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 | 222 | ||
| 227 | - | ||
| 228 | - | ||
| 229 | - | ||
| 223 | + | * have a handler installed like mentioned above | |
| 224 | + | * temporarily unmask the FPU before the try | |
| 225 | + | * mask it again before you return to the host application | |
| 230 | 226 | ||
| 231 | 227 | ## Finalization | |
| 232 | 228 | ||
| 233 | - | ||
| 229 | + | Every unit can contain a finalization section. The order is the reverse order of the initialization sections. | |
| 234 | 230 | ||
| 235 | - | ||
| 231 | + | After all finalization sections are executed it will call the procedure that you have previously assigned to Dll_Process_Detach_Hook. | |
| 236 | 232 | ||
| 237 | - | ||
| 233 | + | Be very careful what you do in this procedure: | |
| 238 | 234 | ||
| 239 | - | ||
| 240 | - | ||
| 241 | - | ||
| 235 | + | * all other units will already be finalized | |
| 236 | + | * parts of the RTL might not work as expected anymore | |
| 237 | + | * creating and freeing objects on the heap or even using Pascal strings inside this procedure is a sure way to call for trouble. | |
| 242 | 238 | ||
| 243 | - | ||
| 239 | + | 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 | 240 | ||
| 245 | 241 | ## Versions, Distribution | |
| 246 | 242 | ||
| 247 | - | ||
| 243 | + | 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 | 244 | ||
| 249 | - | ||
| 245 | + | To do: explain how to set/use this version both on Windows and *nix | |
| 250 | 246 | ||
| 251 | - | ||
| 247 | + | 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 | 248 | ||
| 253 | - | ||
| 249 | + | To do: proposal how the IDE should create version numbers | |
| 254 | 250 | ||
| 255 | 251 | ## See also | |
| 256 | 252 | ||
| 257 | - | ||
| 258 | - | ||
| 259 | - | ||
| 260 | - | ||
| 261 | - | ||
| 262 | - | ||
| 253 | + | * [[macOS Programming Tips|macOS Programming Tips - Libraries]] | |
| 254 | + | * [[macOS Dynamic Libraries]] | |
| 255 | + | * [[macOS Static Libraries]] | |
| 256 | + | * FPC [[shared library]] | |
| 257 | + | * FPC [[packages]] | |
| 258 | + | * [[Translations / i18n / localizations for programs]] | |
| 263 | 259 | ||
| 264 | 260 | --- | |
| 265 | - | ||
| 261 | + | *From the Free Pascal wiki, page "Lazarus/FPC Libraries", as the Internet Archive kept it on 2025-04-24, last changed on 2024-12-30. 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).* |