Making libraries

Free Pascalsupports making shared or static libraries in a straightforward and easy manner. If you want to make static libraries for other Free Pascalprogrammers, you just need to provide a command line switch. To make shared libraries, refer to the chapter Programming shared libraries. If you want C programmers to be able to use your code as well, you will need to adapt your code a little. This process is described first.

Exporting functions

When exporting functions from a library, there are 2 things you must take in account:

1. Calling conventions.

2. Naming scheme.

The calling conventions are controlled by the modifiers cdecl, popstack, pascal, safecall, stdcall and register. See section Code issues for more information on the different kinds of calling scheme.

The naming conventions can be controlled by 2 modifiers in the case of static libraries:

• cdecl

• alias

For more information on how these different modifiers change the name mangling of the routine section Code issues.

Exporting variables

Just as you can export functions, you can also export variables. When exporting variables, one should only consider the names of the variables. To declare a variable that should be used by a C program, one declares it with the cvar modifier:

Var MyVar : MyTpe; cvar;

This will tell the compiler that the assembler name of the variable (as used by C programs) should be exactly as specified in the declaration, i.e., case-sensitive.

It is not allowed to declare multiple variables as cvar in one statement, i.e. the following code will produce an error:

var Z1,Z2 : longint;cvar;

Compiling libraries

To create shared libraries one should use the library keyword in the main compilation file (the project file). For more information on creating shared libraries, chapter Programming shared libraries.

The .o object files that the compiler writes when it compiles a unit, are regular object files as they are produced by a C compiler. They can be combined using the ar and ranlib tools into a static library. However, for various reasons, this is a bad idea.

• The code will be full of references to compiler internal routines in the RTL. These routines are not present in a C library.

• The initialization sections will not be called by a C program.

• The thread vars will not be allocated (or initialized).

• Resource strings will not be initialized.

• Each library thus made will attempt to initialize the RTL.

To remedy these (and other) problems requires intimate knowledge of the inner workings of the compiler and RTL, and it is therefore a bad idea to attempt the use of static libraries with Free Pascal.

Unit searching strategy

When you compile a unit, the compiler will by default always look for unit files.

To be able to differentiate between units that have been compiled as static or dynamic libraries, there are 2 switches:

-XD: 

This will define the symbol FPC_LINK_DYNAMIC

-XS: 

This will define the symbol FPC_LINK_STATIC

Definition of one symbol will automatically undefine the other.

These two switches can be used in conjunction with the configuration file fpc.cfg. The existence of one of these symbols can be used to decide which unit search path to set. For example, on Linux:

# Set unit paths

#IFDEF FPC_LINK_STATIC
-Up/usr/lib/fpc/linuxunits/staticunits
#ENDIF
#IFDEF FPC_LINK_DYNAMIC
-Up/usr/lib/fpc/linuxunits/sharedunits
#ENDIF

With such a configuration file, the compiler will look for its units in different directories, depending on whether -XD or -XS is used.