2 $Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.19 2002/01/09 00:52:37 petere Exp $
6 <title id="dfunc-title">Compiling and Linking Dynamically-Loaded Functions</title>
9 Before you are able to use your
10 <productname>PostgreSQL</productname> extension functions written in
11 C, they must be compiled and linked in a special way to produce a file
12 that can be dynamically loaded by the server. To be
13 precise, a <firstterm>shared library</firstterm> needs to be created.
17 For more information you should read the documentation of your
18 operating system, in particular the manual pages for the C compiler,
19 <command>cc</command>, and the link editor, <command>ld</command>.
20 In addition, the <productname>PostgreSQL</productname> source code
21 contains several working examples in the
22 <filename>contrib</filename> directory. If you rely on these
23 examples you will make your modules dependent on the availability
24 of the <productname>PostgreSQL</productname> source code, however.
28 <indexterm><primary>PIC</></>
29 Creating shared libraries is generally analoguous to linking
30 executables: first the source files are compiled into object files,
31 then the object files are linked together. The object files need to
32 be created as <firstterm>position-independent code</firstterm>
33 (<acronym>PIC</acronym>), which conceptually means that they can be
34 placed at an arbitrary location in memory when they are loaded by the
35 executable. (Object files intended for executables are usually not compiled
36 that way.) The command to link a shared library contains special
37 flags to distinguish it from linking an executable. --- At least
38 this is the theory. On some systems the practice is much uglier.
42 In the following examples we assume that your source code is in a
43 file <filename>foo.c</filename> and we will create a shared library
44 <filename>foo.so</filename>. The intermediate object file will be
45 called <filename>foo.o</filename> unless otherwise noted. A shared
46 library can contain more than one object file, but we only use one
53 Note: Reading GNU Libtool sources is generally a good way of figuring out
54 this information. The methods used within
55 <productname>PostgreSQL</> source code are not
61 <term><productname>BSD/OS</productname></term>
62 <indexterm><primary>BSD/OS</></>
65 The compiler flag to create <acronym>PIC</acronym> is
66 <option>-fpic</option>. The linker flag to create shared
67 libraries is <option>-shared</option>.
70 ld -shared -o foo.so foo.o
72 This is applicable as of version 4.0 of
73 <productname>BSD/OS</productname>.
79 <term><productname>FreeBSD</productname></term>
80 <indexterm><primary>FreeBSD</></>
83 The compiler flag to create <acronym>PIC</acronym> is
84 <option>-fpic</option>. To create shared libraries the compiler
85 flag is <option>-shared</option>.
88 gcc -shared -o foo.so foo.o
90 This is applicable as of version 3.0 of
91 <productname>FreeBSD</productname>.
97 <term><productname>HP-UX</productname></term>
98 <indexterm><primary>HP-UX</></>
101 The compiler flag of the system compiler to create
102 <acronym>PIC</acronym> is <option>+z</option>. When using
103 <productname>GCC</productname> it's <option>-fpic</option>. The
104 linker flag for shared libraries is <option>-b</option>. So
114 ld -b -o foo.sl foo.o
116 <productname>HP-UX</productname> uses the extension
117 <filename>.sl</filename> for shared libraries, unlike most other
124 <term><productname>IRIX</productname></term>
125 <indexterm><primary>IRIX</></>
128 <acronym>PIC</acronym> is the default, no special compiler
129 options are necessary. The linker option to produce shared
130 libraries is <option>-shared</option>.
133 ld -shared -o foo.so foo.o
140 <term><productname>Linux</productname></term>
141 <indexterm><primary>Linux</></>
144 The compiler flag to create <acronym>PIC</acronym> is
145 <option>-fpic</option>. On some platforms in some situations
146 <option>-fPIC</option> must be used if <option>-fpic</option>
147 does not work. Refer to the GCC manual for more information.
148 The compiler flag to create a shared library is
149 <option>-shared</option>. A complete example looks like this:
152 cc -shared -o foo.so foo.o
159 <term><productname>NetBSD</productname></term>
160 <indexterm><primary>NetBSD</></>
163 The compiler flag to create <acronym>PIC</acronym> is
164 <option>-fpic</option>. For <acronym>ELF</acronym> systems, the
165 compiler with the flag <option>-shared</option> is used to link
166 shared libraries. On the older non-ELF systems, <literal>ld
167 -Bshareable</literal> is used.
170 gcc -shared -o foo.so foo.o
177 <term><productname>OpenBSD</productname></term>
178 <indexterm><primary>OpenBSD</></>
181 The compiler flag to create <acronym>PIC</acronym> is
182 <option>-fpic</option>. <literal>ld -Bshareable</literal> is
183 used to link shared libraries.
186 ld -Bshareable -o foo.so foo.o
193 <term><productname>Solaris</productname></term>
194 <indexterm><primary>Solaris</></>
197 The compiler flag to create <acronym>PIC</acronym> is
198 <option>-KPIC</option> with the Sun compiler and
199 <option>-fpic</option> with <productname>GCC</productname>. To
200 link shared libraries, the compiler option is
201 <option>-G</option> with either compiler or alternatively
202 <option>-shared</option> with <productname>GCC</productname>.
205 cc -G -o foo.so foo.o
210 gcc -G -o foo.so foo.o
217 <term>Tru64 UNIX</term>
218 <indexterm><primary>Tru64 UNIX</></>
219 <indexterm><primary>Digital UNIX</><see>Tru64 UNIX</></>
222 <acronym>PIC</acronym> is the default, so the compilation command
223 is the usual one. <command>ld</command> with special options is
224 used to do the linking:
227 ld -shared -expect_unresolved '*' -o foo.so foo.o
229 The same procedure is used with GCC instead of the system
230 compiler; no special options are required.
236 <term><productname>UnixWare</productname></term>
237 <indexterm><primary>UnixWare</></>
240 The compiler flag to create <acronym>PIC</acronym> is <option>-K
241 PIC</option> with the SCO compiler and <option>-fpic</option>
242 with <productname>GCC</productname>. To link shared libraries,
243 the compiler option is <option>-G</option> with the SCO compiler
244 and <option>-shared</option> with
245 <productname>GCC</productname>.
248 cc -G -o foo.so foo.o
253 gcc -shared -o foo.so foo.o
264 If you want to package your extension modules for wide distribution
265 you should consider using <ulink
266 url="http://www.gnu.org/software/libtool/"><productname>GNU
267 Libtool</productname></ulink> for building shared libraries. It
268 encapsulates the platform differences into a general and powerful
269 interface. Serious packaging also requires considerations about
270 library versioning, symbol resolution methods, and other issues.
275 The resulting shared library file can then be loaded into
276 <productname>PostgreSQL</productname>. When specifying the file name
277 to the <command>CREATE FUNCTION</command> command, one must give it
278 the name of the shared library file, not the intermediate object file.
279 Note that the system's standard shared-library extension (usually
280 <literal>.so</literal> or <literal>.sl</literal>) can be omitted from
281 the <command>CREATE FUNCTION</command> command, and normally should
282 be omitted for best portability.
286 Refer back to <xref linkend="xfunc-c-dynload"> about where the
287 server expects to find the shared library files.
291 Under AIX, object files are compiled normally but building the shared
292 library requires a couple of steps. First, create the object file:
294 cc <other flags> -c foo.c
296 You must then create a symbol \*(lqexports\*(rq file for the object
299 mkldexport foo.o `pwd` > foo.exp
301 Finally, you can create the shared library:
303 ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
304 -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
307 You should look at the <citetitle>PostgreSQL User's Manual</>
308 for an explanation of this
315 <!-- Keep this comment at the end of the file
320 sgml-minimize-attributes:nil
321 sgml-always-quote-attributes:t
323 sgml-indent-tabs-mode:nil
325 sgml-parent-document:nil
326 sgml-default-dtd-file:"./reference.ced"
327 sgml-exposed-tags:nil
328 sgml-local-catalogs:("/usr/share/sgml/catalog")
329 sgml-local-ecat-files:nil