-<!--
-$Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.15 2001/10/26 19:58:12 tgl Exp $
--->
+<!-- doc/src/sgml/dfunc.sgml -->
<sect2 id="dfunc">
- <title id="dfunc-title">Compiling and Linking Dynamically-Loaded Functions</title>
+ <title>Compiling and Linking Dynamically-loaded Functions</title>
<para>
Before you are able to use your
<productname>PostgreSQL</productname> 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 <firstterm>shared library</firstterm> needs to be created.
+ 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
+ <firstterm>shared library</firstterm> needs to be
+ created.<indexterm><primary>shared library</></indexterm>
+
</para>
<para>
- For more information you should read the documentation of your
+ For information beyond what is contained in this section
+ you should read the documentation of your
operating system, in particular the manual pages for the C compiler,
<command>cc</command>, and the link editor, <command>ld</command>.
In addition, the <productname>PostgreSQL</productname> source code
</para>
<para>
- Creating shared libraries is generally analoguous to linking
- executables: first the source files are compiled into object files,
+ Creating shared libraries is generally analogous 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 <firstterm>position-independent code</firstterm>
- (<acronym>PIC</acronym>), 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.
+ (<acronym>PIC</acronym>),<indexterm><primary>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 in theory
+ — on some systems the practice is much uglier).
</para>
<para>
In the following examples we assume that your source code is in a
- file <filename>foo.c</filename> and we will create an shared library
+ file <filename>foo.c</filename> and we will create a shared library
<filename>foo.so</filename>. The intermediate object file will be
called <filename>foo.o</filename> unless otherwise noted. A shared
library can contain more than one object file, but we only use one
here.
</para>
- <para>
-
<!--
- Note: Reading GNU Libtool sources is generally a good way of figuring out
- this information. The methods used within PostgreSQL source code are not
- necessarily ideal.
+ Note: Reading GNU Libtool sources is generally a good way of
+ figuring out this information. The methods used within PostgreSQL
+ source code are not necessarily ideal.
-->
<variablelist>
<varlistentry>
- <term><productname>BSD/OS</productname></term>
- <listitem>
- <para>
- The compiler flag to create <acronym>PIC</acronym> is
- <option>-fpic</option>. The linker flag to create shared
- libraries is <option>-shared</option>.
-<programlisting>
-gcc -fpic -c foo.c
-ld -shared -o foo.so foo.o
-</programlisting>
- This is applicable as of version 4.0 of
- <productname>BSD/OS</productname>.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><productname>FreeBSD</productname></term>
+ <term>
+ <systemitem class="osname">FreeBSD</>
+ <indexterm><primary>FreeBSD</><secondary>shared library</></>
+ </term>
<listitem>
<para>
The compiler flag to create <acronym>PIC</acronym> is
gcc -shared -o foo.so foo.o
</programlisting>
This is applicable as of version 3.0 of
- <productname>FreeBSD</productname>.
+ <systemitem class="osname">FreeBSD</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><productname>HP-UX</productname></term>
+ <term>
+ <systemitem class="osname">HP-UX</>
+ <indexterm><primary>HP-UX</><secondary>shared library</></>
+ </term>
<listitem>
<para>
The compiler flag of the system compiler to create
<acronym>PIC</acronym> is <option>+z</option>. When using
- <productname>GCC</productname> it's <option>-fpic</option>. The
- linker flag for shared libraries is <option>-b</option>. So
+ <application>GCC</application> it's <option>-fpic</option>. The
+ linker flag for shared libraries is <option>-b</option>. So:
<programlisting>
cc +z -c foo.c
</programlisting>
- or
+ or:
<programlisting>
gcc -fpic -c foo.c
</programlisting>
- and then
+ and then:
<programlisting>
ld -b -o foo.sl foo.o
</programlisting>
- <productname>HP-UX</productname> uses the extension
+ <systemitem class="osname">HP-UX</> uses the extension
<filename>.sl</filename> for shared libraries, unlike most other
systems.
</para>
</varlistentry>
<varlistentry>
- <term><productname>Irix</productname></term>
+ <term>
+ <systemitem class="osname">Linux</>
+ <indexterm><primary>Linux</><secondary>shared library</></>
+ </term>
<listitem>
<para>
- <acronym>PIC</acronym> is the default, no special compiler
- options are necessary. The linker option to produce shared
- libraries is <option>-shared</option>.
+ The compiler flag to create <acronym>PIC</acronym> is
+ <option>-fpic</option>. On some platforms in some situations
+ <option>-fPIC</option> must be used if <option>-fpic</option>
+ does not work. Refer to the GCC manual for more information.
+ The compiler flag to create a shared library is
+ <option>-shared</option>. A complete example looks like this:
<programlisting>
-cc -c foo.c
-ld -shared -o foo.so foo.o
+cc -fpic -c foo.c
+cc -shared -o foo.so foo.o
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><productname>Linux</productname></term>
+ <term>
+ <systemitem class="osname">Mac OS X</>
+ <indexterm><primary>Mac OS X</><secondary>shared library</></>
+ </term>
<listitem>
<para>
- The compiler flag to create <acronym>PIC</acronym> is
- <option>-fpic</option>. On some platforms in some situations
- <option>-fPIC</option> must be used if <option>-fpic</option>
- does not work. Refer to the GCC manual for more information.
- The compiler flag to create a shared library is
- <option>-shared</option>. A complete example looks like this:
+ Here is an example. It assumes the developer tools are installed.
<programlisting>
-cc -fpic -c foo.c
-cc -shared -o foo.so foo.o
+cc -c foo.c
+cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o
</programlisting>
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><productname>NetBSD</productname></term>
+ <term>
+ <systemitem class="osname">NetBSD</>
+ <indexterm><primary>NetBSD</><secondary>shared library</></>
+ </term>
<listitem>
<para>
The compiler flag to create <acronym>PIC</acronym> is
</varlistentry>
<varlistentry>
- <term><productname>OpenBSD</productname></term>
+ <term>
+ <systemitem class="osname">OpenBSD</>
+ <indexterm><primary>OpenBSD</><secondary>shared library</></>
+ </term>
<listitem>
<para>
The compiler flag to create <acronym>PIC</acronym> is
</varlistentry>
<varlistentry>
- <term>Digital Unix/Tru64 UNIX</term>
-
- <listitem>
- <para>
- <acronym>PIC</acronym> is the default, so the compilation command
- is the usual one. <command>ld</command> with special options is
- used to do the linking:
-<programlisting>
-cc -c foo.c
-ld -shared -expect_unresolved '*' -o foo.so foo.o
-</programlisting>
- The same procedure is used with GCC instead of the system
- compiler; no special options are required.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><productname>Solaris</productname></term>
+ <term>
+ <systemitem class="osname">Solaris</>
+ <indexterm><primary>Solaris</><secondary>shared library</></>
+ </term>
<listitem>
<para>
The compiler flag to create <acronym>PIC</acronym> is
<option>-KPIC</option> with the Sun compiler and
- <option>-fpic</option> with <productname>GCC</productname>. To
+ <option>-fpic</option> with <application>GCC</>. To
link shared libraries, the compiler option is
<option>-G</option> with either compiler or alternatively
- <option>-shared</option> with <productname>GCC</productname>.
+ <option>-shared</option> with <application>GCC</>.
<programlisting>
cc -KPIC -c foo.c
cc -G -o foo.so foo.o
</varlistentry>
<varlistentry>
- <term><productname>Unixware</productname></term>
+ <term>
+ <systemitem class="osname">UnixWare</>
+ <indexterm><primary>UnixWare</><secondary>shared library</></>
+ </term>
<listitem>
<para>
The compiler flag to create <acronym>PIC</acronym> is <option>-K
</varlistentry>
</variablelist>
- </para>
<tip>
<para>
- If you want to package your extension modules for wide distribution
- you should consider using <ulink
- url="http://www.gnu.org/software/libtool/"><productname>GNU
- Libtool</productname></ulink> 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.
+ If this is too complicated for you, you should consider using
+ <ulink url="http://www.gnu.org/software/libtool/">
+ <productname>GNU Libtool</productname></ulink>,
+ which hides the platform differences behind a uniform interface.
</para>
</tip>
<para>
The resulting shared library file can then be loaded into
- <productname>Postgres</productname>. When specifying the file name
+ <productname>PostgreSQL</productname>. When specifying the file name
to the <command>CREATE FUNCTION</command> 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
You must then create a symbol \*(lqexports\*(rq file for the object
file:
.nf
-mkldexport foo.o `pwd` > foo.exp
+mkldexport foo.o `pwd` > foo.exp
.fi
Finally, you can create the shared library:
.nf
-bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
-lm -lc 2>/dev/null
.fi
-You should look at the Postgres User's Manual for an explanation of this
-procedure.
-
-->
</sect2>
-
-<!-- Keep this comment at the end of the file
-Local variables:
-mode:sgml
-sgml-omittag:nil
-sgml-shorttag:t
-sgml-minimize-attributes:nil
-sgml-always-quote-attributes:t
-sgml-indent-step:1
-sgml-indent-data:t
-sgml-parent-document:nil
-sgml-default-dtd-file:"./reference.ced"
-sgml-exposed-tags:nil
-sgml-local-catalogs:("/usr/lib/sgml/catalog")
-sgml-local-ecat-files:nil
-End:
--->
projects / postgresql / blobdiff