Next: 8 Memory issues Up: Free Pascal Programmers' manual Previous: 6 Code issues
However, there are times that linking to C libraries, or to external object files created by other compilers may be necessary. The Free Pascal compiler can generate calls to a C function, and can generate functions that can be called from C (exported functions).
In general, there are 3 things you must do to use a function that resides in an external library or object file:
The first step in using external code blocks is declaring the function you want to use. Free Pascal supports Delphi syntax, i.e. you must use the external directive. The external directive replaces, in effect, the code block of the function.
The external directive doesn't specify a calling convention; it just tells the compiler that the code for a procedure or function resides in an external code block. A calling convention modifier should be declared if the external code blocks does not have the same calling conventions as Free Pascal. For more information on the calling conventions section CallingConventions.
There exist four variants of the external directive:
Procedure ProcName (Args : TPRocArgs); external;The external directive tells the compiler that the function resides in an external block of code. You can use this together with the {$L} or {$LinkLib} directives to link to a function or procedure in a library or external object file. Object files are looked for in the object search path (set by -Fo) and libraries are searched for in the linker path (set by -Fl).
Procedure ProcName (Args : TPRocArgs); external 'Name';This tells the compiler that the procedure resides in a library with name 'Name'. This method is equivalent to the following:
Procedure ProcName (Args : TPRocArgs);external;
{$LinkLib 'Name'}
Procedure ProcName (Args : TPRocArgs); external 'Name'
name 'OtherProcName';
This has the same meaning as the previous declaration, only the compiler
will use the name 'OtherProcName' when linking to the library. This
can be used to give different names to procedures and functions in an
external library. The name of the routine is case-sensitive and should
match exactly the name of the routine in the object file.
This method is equivalent to the following code:
Procedure OtherProcName (Args : TProcArgs); external;
{$LinkLib 'Name'}
Procedure ProcName (Args : TPRocArgs);
begin
OtherProcName (Args);
end;
Procedure ProcName (Args : TPRocArgs); external 'Name' Index SomeIndex;This tells the compiler that the procedure ProcName resides in a dynamic link library, with index SomeIndex.
Remark: Note that this is ONLY available under WINDOWS and OS/2.
Some libaries or code blocks have variables which they export. You can access these variables much in the same way as external functions. To access an external variable, you declare it as follows:
Var MyVar : MyType; external name 'varname';The effect of this declaration is twofold:
A second possibility is the declaration:
Var varname : MyType; cvar; external;The effect of this declaration is twofold as in the previous case:
As an example, let's look at the following C file (in extvar.c):
/* Declare a variable, allocate storage */ int extvar = 12;And the following program (in extdemo.pp):
Program ExtDemo;
{$L extvar.o}
Var { Case sensitive declaration !! }
extvar : longint; cvar;external;
I : longint; external name 'extvar';
begin
{ Extvar can be used case insensitive !! }
Writeln ('Variable ''extvar'' has value: ',ExtVar);
Writeln ('Variable ''I'' has value: ',i);
end.
Compiling the C file, and the pascal program:
gcc -c -o extvar.o extvar.c ppc386 -Sv extdemoWill produce a program extdemo which will print
Variable 'extvar' has value: 12 Variable 'I' has value: 12on your screen.
To make sure that all parameters are correctly passed to the external routines, you should declare it with the correct calling convention modifier. When linking with code blocks compiled with standard C compilers (such as GCC), the cdecl modifier should be used so as to indicate that the external routine uses C type calling conventions. For more information on the supported calling conventions, section CallingConventions.
As might expected, external variable declarations do not require any calling convention modifier.
Having declared the external function or variable that resides in an object file, you can use it as if it was defined in your own program or unit. To produce an executable, you must still link the object file in. This can be done with the {$L file.o} directive.
This will cause the linker to link in the object file file.o. On most systems, this filename is case sensitive. The object file is first searched in the current directory, and then the directories specified by the -Fo command line.
You cannot specify libraries in this way, it is for object files only.
Here we present an example. Consider that you have some assembly routine which uses the C calling convention that calculates the nth Fibonacci number:
.text
.align 4
.globl Fibonacci
.type Fibonacci,@function
Fibonacci:
pushl %ebp
movl %esp,%ebp
movl 8(%ebp),%edx
xorl %ecx,%ecx
xorl %eax,%eax
movl $1,%ebx
incl %edx
loop:
decl %edx
je endloop
movl %ecx,%eax
addl %ebx,%eax
movl %ebx,%ecx
movl %eax,%ebx
jmp loop
endloop:
movl %ebp,%esp
popl %ebp
ret
Then you can call this function with the following Pascal Program:
Program FibonacciDemo;
var i : longint;
Function Fibonacci (L : longint):longint;cdecl;external;
{$L fib.o}
begin
For I:=1 to 40 do
writeln ('Fib(',i,') : ',Fibonacci (i));
end.
With just two commands, this can be made into a program:
as -o fib.o fib.s ppc386 fibo.ppThis example supposes that you have your assembler routine in fib.s, and your Pascal program in fibo.pp.
To link your program to a library, the procedure depends on how you declared the external procedure.
In case you used the following syntax to declare your procedure:
Procedure ProcName (Args : TPRocArgs); external 'Name';You don't need to take additional steps to link your file in, the compiler will do all that is needed for you. On WINDOWS it will link to name.dll, on LINUX and most UNIX'es your program will be linked to library libname, which can be a static or dynamic library.
In case you used
Procedure ProcName (Args : TPRocArgs); external;You still need to explicity link to the library. This can be done in 2 ways:
{$LinkLib 'gpm'}
This will link to the gpm library. On UNIX systems (such as LINUX),
you must not specify the extension or 'lib' prefix of the library. The compiler takes
care of that. On other systems (such as WINDOWS, you need to specify the full
name.
ppc386 -k'-lgpm' myprog.ppIs equivalent to the above method, and tells the linker to link to the gpm library.
As an example; consider the following program:
program printlength;
{$linklib c} { Case sensitive }
{ Declaration for the standard C function strlen }
Function strlen (P : pchar) : longint; cdecl;external;
begin
Writeln (strlen('Programming is easy !'));
end.
This program can be compiled with:
ppc386 prlen.ppSupposing, of course, that the program source resides in prlen.pp.
To use functions in C that have a variable number of arguments, you must compile your unit or program in objfpc mode or Delphi mode, and use the Array of const argument, as in the following example:
program testaocc;
{$mode objfpc}
Const
P : Pchar
= 'example';
F : Pchar
= 'This %s uses printf to print numbers (%d) and strings.'#10;
procedure printf(fm: pchar;args: array of const);cdecl;external 'c';
begin
printf(F,[P,123]);
end.
The output of this program looks like this:
This example uses printf to print numbers (123) and strings.
Free Pascal supports making shared or static libraries in a straightforward and easy manner. If you want to make static libraries for other Free Pascal programmers, you just need to provide a command line switch. To make shared libraries, refer to the chapter 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.
When exporting functions from a library, there are 2 things you must take in account:
The naming conventions can be controlled by 2 modifiers in the case of static libraries:
For more information on how these different modifiers change the name mangling of the routine section NameMangling.
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 these units too.
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;
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 (dynamic) library.
You can do this as follows, for a dynamic library:
ppc386 -CD myunitOn UNIX systems, such as LINUX, this will leave you with a file libmyunit.so. On WINDOWS and OS/2, this will leave you with myunit.dll. An easier way to create shared libraries is to use the library keyword. For more information on creating shared libraries, chapter libraries.
If you want a static library, you can do
ppc386 -CS myunitThis 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 most UNIX systems, 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.
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:
These two switches can be used in conjunction with the configuration file ppc386.cfg or ppc.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 #ENDIFWith such a configuration file, the compiler will look for it's units in different directories, depending on whether -XD or -XS is used.
You can compile your units using smart linking. When you use smartlinking, the compiler creates a series of code blocks that are as small as possible, i.e. a code block will contain only the code for one procedure or function.
When you compile a program that uses a smart-linked unit, the compiler will only link in the code that you actually need, and will leave out all other code. This will result in a smaller binary, which is loaded in memory faster, thus speeding up execution.
To enable smartlinking, one can give the smartlink option on the command line: -Cx, or one can put the {$SMARTLINK ON} directive in the unit file:
Unit Testunit
{SMARTLINK ON}
Interface
...
Smartlinking will slow down the compilation process, especially for large
units.
When a unit foo.pp is smartlinked, the name of the codefile is changed to libfoo.a.
Technically speaking, the compiler makes small assembler files for each procedure and function in the unit, as well as for all global defined variables (whether they're in the interface section or not). It then assembles all these small files, and uses ar to collect the resulting object files in one archive.
Smartlinking and the creation of shared (or dynamic) libraries are mutually exclusive, that is, if you turn on smartlinking, then the creation of shared libraries is turned of. The creation of static libraries is still possible. The reason for this is that it has little sense in making a smartlinked dynamical library. The whole shared library is loaded into memory anyway by the dynamic linker (or the operating system), so there would be no gain in size by making it smartlinked.