12.2 Creating a library

Creation of libraries is supported in any mode of the Free Pascal compiler, but it may be that the arguments or return values differ if the library is compiled in 2 different modes. E.g. if your function expects an Integer argument, then the library will expect different integer sizes if you compile it in Delphi mode or in TP mode.

A library can be created just as a program, only it uses the library keyword, and it has an exports section. The following listing demonstrates a simple library:

Listing: progex/subs.pp


{
  Example library
}
library subs;

function SubStr(CString: PChar;FromPos,ToPos: Longint): PChar; cdecl;

var
  Length: Integer;

begin
  Length := StrLen(CString);
  SubStr := CString + Length;
  if (FromPos > 0) and (ToPos >= FromPos) then
  begin
    if Length >= FromPos then
      SubStr := CString + FromPos;
    if Length > ToPos then
    CString[ToPos+1] := #0;
  end;
end;

exports
  SubStr;

end.

The function SubStr does not have to be declared in the library file itself. It can also be declared in the interface section of a unit that is used by the library.

Compilation of this source will result in the creation of a library called libsubs.dylib on MacOS, libsubs.so on other unix systems, or subs.dll on Windows or os/2. The compiler will take care of any additional linking that is required to create a shared library.

The library exports one function: SubStr. The case is important. The case as it appears in the exports clause is used to export the function.

If you want your library to be called from programs compiled with other compilers, it is important to specify the correct calling convention for the exported functions. Since the generated programs by other compilers do not know about the Free Pascal calling conventions, your functions would be called incorrectly, resulting in a corrupted stack.

On Windows, most libraries use the stdcall convention, so it may be better to use that one if your library is to be used on Windows systems. On most unix systems, the C calling convention is used, therefore the cdecl modifier should be used in that case.