Making libraries

 

Free Pascal supports making shared or static libraries in a straightforward and easy manner. If you want to make libraries for other Free Pascal programmers, you just need to provide a command line switch. 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, stdcall. See section (3.3) for more information on the different kinds of calling scheme.

The naming conventions can be controlled by 3 modifiers:

cdecl:

A function that has a cdecl modifier, will used with C calling conventions, that is, the caller clears the stack. Also the mangled name will be the name exactly as in the declaration. cdecl is part of the function declaration, and hence must be present both in the interface and implementation section of a unit.

export:

A function that has an export modifier, uses also the exact declaration name as its mangled name. Under WINDOWSNT and OS/2, this modifier signals a function that is exported from a DLL. The calling conventions used by a export procedure depend on the OS. this keyword can be used only in the implementation section.

Alias:

The alias modifier can be used to give a supplementary assembler name to your function. This doesn't modify the calling conventions of the function.

If you want to make your procedures and functions available to C programmers, you can do this very easily. All you need to do is declare the functions and procedures that you want to make available as export, as follows:

Procedure ExportedProcedure; export;

Remark : You can only declare a function as exported in the Implementation section of a unit. This function may not appear in the interface part of a unit. This is logical, since a Pascal routine cannot call an exported function, anyway.

However, the generated object file will not contain the name of the function as you declared it. The Free Pascal compiler ''mangles'' the name you give your function. It makes the name all-uppercase, and adds the types of all parameters to it. There are cases when you want to provide a mangled name without changing the calling convention. In such cases, you can use the Alias modifier.

The Alias modifier allows you to specify another name (a nickname) for your function or procedure.

The prototype for an aliased function or procedure is as follows :

Procedure AliasedProc; [ Alias : 'AliasName'];

The procedure AliasedProc will also be known as AliasName. Take care, the name you specify is case sensitive (as C is).

Remark: If you use in your unit functions that are in other units, or system functions, then the C program will need to link in the object files from the units too.

Exporting variables

Similarly as when you export functions, you can export variables. when exportig 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 (the one which is 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

Once you have your (adapted) code, with exported and other functions, you can compile your unit, and tell the compiler to make it into a library. The compiler will simply compile your unit, and perform the necessary steps to transform it into a static or shared (dynamical) library.

You can do this as follows, for a dynamical library:

ppc386 -CD myunit

On LINUX this will leave you with a file libmyunit.so. On WINDOWS and OS/2, this will leave you with myunit.dll.

If you want a static library, you can do

ppc386 -CS myunit

This will leave you with libmyunit.a and a file myunit.ppu. The myunit.ppu is the unit file needed by the Free Pascal compiler.

The resulting files are then libraries. To make static libraries, you need the ranlib or ar program on your system. It is standard on any LINUX system, and is provided with the GCC compiler under DOS. For the dos distribution, a copy of ar is included in the file gnuutils.zip.

BEWARE: This command doesn't include anything but the current unit in the library. Other units are left out, so if you use code from other units, you must deploy them together with your library.

Moving units into a library

You can put multiple units into a library with the ppumove command, as follows:

ppumove -e ppl -o name unit1 unit2 unit3

This will move 3 units in 1 library (called libname.so on linux, name.dll on WINDOWS) and it will create 3 files unit1.ppl, unit2.ppl and file3.ppl, which are unit files, but which tell the compiler to look in library name when linking your executable.

The ppumove program has options to create statical or dynammical libraries. It is provided with the compiler.

Unit searching strategy

When you compile a program or unit, the compiler will by default always look for .ppl files. If it doesn't find one, it will look for a .ppu file.

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 ppc386.cfg. The existence of one of these symbols can be used to decide which unit search path to set. For example:

# 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 it's units in different directories, depending on whether -XD or -XS is used.