Compiling and Linking Dynamically-Loaded Functions
Before you are able to use your
PostgreSQL extension functions written in
C, they must be compiled and linked in a special way to produce a file
that can be dynamically loaded by the server. To be
precise, a shared library needs to be created.
For more information you should read the documentation of your
operating system, in particular the manual pages for the C compiler,
cc, and the link editor, ld.
In addition, the PostgreSQL source code
contains several working examples in the
contrib directory. If you rely on these
examples you will make your modules dependent on the availability
of the PostgreSQL source code, however.
Creating shared libraries is generally analoguous to linking
executables: first the source files are compiled into object files,
then the object files are linked together. The object files need to
be created as position-independent code
(PIC), which conceptually means that they can be
placed at an arbitrary location in memory when they are loaded by the
executable. (Object files intended for executables are usually not compiled
that way.) The command to link a shared library contains special
flags to distinguish it from linking an executable. --- At least
this is the theory. On some systems the practice is much uglier.
In the following examples we assume that your source code is in a
file foo.c and we will create an shared library
foo.so. The intermediate object file will be
called foo.o unless otherwise noted. A shared
library can contain more than one object file, but we only use one
here.
BSD/OS
The compiler flag to create PIC is
. The linker flag to create shared
libraries is .
gcc -fpic -c foo.c
ld -shared -o foo.so foo.o
This is applicable as of version 4.0 of
BSD/OS.
FreeBSD
The compiler flag to create PIC is
. To create shared libraries the compiler
flag is .
gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o
This is applicable as of version 3.0 of
FreeBSD.
HP-UX
The compiler flag of the system compiler to create
PIC is . When using
GCC it's . The
linker flag for shared libraries is . So
cc +z -c foo.c
or
gcc -fpic -c foo.c
and then
ld -b -o foo.sl foo.o
HP-UX uses the extension
.sl for shared libraries, unlike most other
systems.
Irix
PIC is the default, no special compiler
options are necessary. The linker option to produce shared
libraries is .
cc -c foo.c
ld -shared -o foo.so foo.o
Linux
The compiler flag to create PIC is
. On some platforms in some situations
must be used if
does not work. Refer to the GCC manual for more information.
The compiler flag to create a shared library is
. A complete example looks like this:
cc -fpic -c foo.c
cc -shared -o foo.so foo.o
NetBSD
The compiler flag to create PIC is
. For ELF systems, the
compiler with the flag is used to link
shared libraries. On the older non-ELF systems, ld
-Bshareable is used.
gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o
OpenBSD
The compiler flag to create PIC is
. ld -Bshareable is
used to link shared libraries.
gcc -fpic -c foo.c
ld -Bshareable -o foo.so foo.o
Digital Unix/Tru64 UNIX
PIC is the default, so the compilation command
is the usual one. ld with special options is
used to do the linking:
cc -c foo.c
ld -shared -expect_unresolved '*' -o foo.so foo.o
The same procedure is used with GCC instead of the system
compiler; no special options are required.
Solaris
The compiler flag to create PIC is
with the Sun compiler and
with GCC. To
link shared libraries, the compiler option is
with either compiler or alternatively
with GCC.
cc -KPIC -c foo.c
cc -G -o foo.so foo.o
or
gcc -fpic -c foo.c
gcc -G -o foo.so foo.o
Unixware
The compiler flag to create PIC is with the SCO compiler and
with GCC. To link shared libraries,
the compiler option is with the SCO compiler
and with
GCC.
cc -K PIC -c foo.c
cc -G -o foo.so foo.o
or
gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o
If you want to package your extension modules for wide distribution
you should consider using GNU
Libtool for building shared libraries. It
encapsulates the platform differences into a general and powerful
interface. Serious packaging also requires considerations about
library versioning, symbol resolution methods, and other issues.
The resulting shared library file can then be loaded into
Postgres. When specifying the file name
to the CREATE FUNCTION command, one must give it
the name of the shared library file, not the intermediate object file.
Note that the system's standard shared-library extension (usually
.so or .sl) can be omitted from
the CREATE FUNCTION command, and normally should
be omitted for best portability.
Refer back to about where the
server expects to find the shared library files.