doc/src/sgml/dfunc.sgml

   1 <!-- $PostgreSQL$ -->
   2
   3 <sect2 id="dfunc">
   4  <title id="dfunc-title">Compiling and Linking Dynamically-Loaded Functions</title>
   5
   6  <para>
   7   Before you are able to use your
   8   <productname>PostgreSQL</productname> extension functions written in
   9   C, they must be compiled and linked in a special way to produce a
  10   file that can be dynamically loaded by the server.  To be precise, a
  11   <firstterm>shared library</firstterm> needs to be
  12   created.<indexterm><primary>shared library</></indexterm>
  13
  14  </para>
  15
  16  <para>
  17   For information beyond what is contained in this section
  18   you should read the documentation of your
  19   operating system, in particular the manual pages for the C compiler,
  20   <command>cc</command>, and the link editor, <command>ld</command>.
  21   In addition, the <productname>PostgreSQL</productname> source code
  22   contains several working examples in the
  23   <filename>contrib</filename> directory.  If you rely on these
  24   examples you will make your modules dependent on the availability
  25   of the <productname>PostgreSQL</productname> source code, however.
  26  </para>
  27
  28  <para>
  29   Creating shared libraries is generally analogous 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>),<indexterm><primary>PIC</></> which
  34   conceptually means that they can be placed at an arbitrary location
  35   in memory when they are loaded by the executable.  (Object files
  36   intended for executables are usually not compiled that way.)  The
  37   command to link a shared library contains special flags to
  38   distinguish it from linking an executable (at least in theory
  39   &mdash; on some systems the practice is much uglier).
  40  </para>
  41
  42  <para>
  43   In the following examples we assume that your source code is in a
  44   file <filename>foo.c</filename> and we will create a shared library
  45   <filename>foo.so</filename>.  The intermediate object file will be
  46   called <filename>foo.o</filename> unless otherwise noted.  A shared
  47   library can contain more than one object file, but we only use one
  48   here.
  49  </para>
  50
  51 <!--
  52   Note: Reading GNU Libtool sources is generally a good way of
  53   figuring out this information.  The methods used within PostgreSQL
  54   source code are not necessarily ideal.
  55 -->
  56
  57   <variablelist>
  58    <varlistentry>
  59     <term><systemitem class="osname">BSD/OS</></term>
  60     <indexterm><primary>BSD/OS</><secondary>shared library</></>
  61     <listitem>
  62      <para>
  63       The compiler flag to create <acronym>PIC</acronym> is
  64       <option>-fpic</option>.  The linker flag to create shared
  65       libraries is <option>-shared</option>.
  66 <programlisting>
  67 gcc -fpic -c foo.c
  68 ld -shared -o foo.so foo.o
  69 </programlisting>
  70       This is applicable as of version 4.0 of
  71       <systemitem class="osname">BSD/OS</>.
  72      </para>
  73     </listitem>
  74    </varlistentry>
  75
  76    <varlistentry>
  77     <term><systemitem class="osname">FreeBSD</></term>
  78     <indexterm><primary>FreeBSD</><secondary>shared library</></>
  79     <listitem>
  80      <para>
  81       The compiler flag to create <acronym>PIC</acronym> is
  82       <option>-fpic</option>.  To create shared libraries the compiler
  83       flag is <option>-shared</option>.
  84 <programlisting>
  85 gcc -fpic -c foo.c
  86 gcc -shared -o foo.so foo.o
  87 </programlisting>
  88       This is applicable as of version 3.0 of
  89       <systemitem class="osname">FreeBSD</>.
  90      </para>
  91     </listitem>
  92    </varlistentry>
  93
  94    <varlistentry>
  95     <term><systemitem class="osname">HP-UX</></term>
  96     <indexterm><primary>HP-UX</><secondary>shared library</></>
  97     <listitem>
  98      <para>
  99       The compiler flag of the system compiler to create
 100       <acronym>PIC</acronym> is <option>+z</option>.  When using
 101       <application>GCC</application> it's <option>-fpic</option>. The
 102       linker flag for shared libraries is <option>-b</option>.  So:
 103 <programlisting>
 104 cc +z -c foo.c
 105 </programlisting>
 106       or:
 107 <programlisting>
 108 gcc -fpic -c foo.c
 109 </programlisting>
 110       and then:
 111 <programlisting>
 112 ld -b -o foo.sl foo.o
 113 </programlisting>
 114       <systemitem class="osname">HP-UX</> uses the extension
 115       <filename>.sl</filename> for shared libraries, unlike most other
 116       systems.
 117      </para>
 118     </listitem>
 119    </varlistentry>
 120
 121    <varlistentry>
 122     <term><systemitem class="osname">IRIX</></term>
 123     <indexterm><primary>IRIX</><secondary>shared library</></>
 124     <listitem>
 125      <para>
 126       <acronym>PIC</acronym> is the default, no special compiler
 127       options are necessary.  The linker option to produce shared
 128       libraries is <option>-shared</option>.
 129 <programlisting>
 130 cc -c foo.c
 131 ld -shared -o foo.so foo.o
 132 </programlisting>
 133      </para>
 134     </listitem>
 135    </varlistentry>
 136
 137    <varlistentry>
 138     <term><systemitem class="osname">Linux</></term>
 139     <indexterm><primary>Linux</><secondary>shared library</></>
 140     <listitem>
 141      <para>
 142       The compiler flag to create <acronym>PIC</acronym> is
 143       <option>-fpic</option>.  On some platforms in some situations
 144       <option>-fPIC</option> must be used if <option>-fpic</option>
 145       does not work.  Refer to the GCC manual for more information.
 146       The compiler flag to create a shared library is
 147       <option>-shared</option>.  A complete example looks like this:
 148 <programlisting>
 149 cc -fpic -c foo.c
 150 cc -shared -o foo.so foo.o
 151 </programlisting>
 152      </para>
 153     </listitem>
 154    </varlistentry>
 155
 156    <varlistentry>
 157     <term><systemitem class="osname">MacOS X</></term>
 158     <indexterm><primary>MacOS X</><secondary>shared library</></>
 159     <listitem>
 160      <para>
 161       Here is an example.  It assumes the developer tools are installed.
 162 <programlisting>
 163 cc -c foo.c
 164 cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o
 165 </programlisting>
 166      </para>
 167     </listitem>
 168    </varlistentry>
 169
 170    <varlistentry>
 171     <term><systemitem class="osname">NetBSD</></term>
 172     <indexterm><primary>NetBSD</><secondary>shared library</></>
 173     <listitem>
 174      <para>
 175       The compiler flag to create <acronym>PIC</acronym> is
 176       <option>-fpic</option>.  For <acronym>ELF</acronym> systems, the
 177       compiler with the flag <option>-shared</option> is used to link
 178       shared libraries.  On the older non-ELF systems, <literal>ld
 179       -Bshareable</literal> is used.
 180 <programlisting>
 181 gcc -fpic -c foo.c
 182 gcc -shared -o foo.so foo.o
 183 </programlisting>
 184      </para>
 185     </listitem>
 186    </varlistentry>
 187
 188    <varlistentry>
 189     <term><systemitem class="osname">OpenBSD</></term>
 190     <indexterm><primary>OpenBSD</><secondary>shared library</></>
 191     <listitem>
 192      <para>
 193       The compiler flag to create <acronym>PIC</acronym> is
 194       <option>-fpic</option>.  <literal>ld -Bshareable</literal> is
 195       used to link shared libraries.
 196 <programlisting>
 197 gcc -fpic -c foo.c
 198 ld -Bshareable -o foo.so foo.o
 199 </programlisting>
 200      </para>
 201     </listitem>
 202    </varlistentry>
 203
 204    <varlistentry>
 205     <term><systemitem class="osname">Solaris</></term>
 206     <indexterm><primary>Solaris</><secondary>shared library</></>
 207     <listitem>
 208      <para>
 209       The compiler flag to create <acronym>PIC</acronym> is
 210       <option>-KPIC</option> with the Sun compiler and
 211       <option>-fpic</option> with <application>GCC</>.  To
 212       link shared libraries, the compiler option is
 213       <option>-G</option> with either compiler or alternatively
 214       <option>-shared</option> with <application>GCC</>.
 215 <programlisting>
 216 cc -KPIC -c foo.c
 217 cc -G -o foo.so foo.o
 218 </programlisting>
 219       or
 220 <programlisting>
 221 gcc -fpic -c foo.c
 222 gcc -G -o foo.so foo.o
 223 </programlisting>
 224      </para>
 225     </listitem>
 226    </varlistentry>
 227
 228    <varlistentry>
 229     <term><systemitem class="osname">Tru64 UNIX</></term>
 230     <indexterm><primary>Tru64 UNIX</><secondary>shared library</></>
 231     <indexterm><primary>Digital UNIX</><see>Tru64 UNIX</></>
 232     <listitem>
 233      <para>
 234       <acronym>PIC</acronym> is the default, so the compilation command
 235       is the usual one.  <command>ld</command> with special options is
 236       used to do the linking.
 237 <programlisting>
 238 cc -c foo.c
 239 ld -shared -expect_unresolved '*' -o foo.so foo.o
 240 </programlisting>
 241       The same procedure is used with GCC instead of the system
 242       compiler; no special options are required.
 243      </para>
 244     </listitem>
 245    </varlistentry>
 246
 247    <varlistentry>
 248     <term><systemitem class="osname">UnixWare</></term>
 249     <indexterm><primary>UnixWare</><secondary>shared library</></>
 250     <listitem>
 251      <para>
 252       The compiler flag to create <acronym>PIC</acronym> is <option>-K
 253       PIC</option> with the SCO compiler and <option>-fpic</option>
 254       with <productname>GCC</productname>.  To link shared libraries,
 255       the compiler option is <option>-G</option> with the SCO compiler
 256       and <option>-shared</option> with
 257       <productname>GCC</productname>.
 258 <programlisting>
 259 cc -K PIC -c foo.c
 260 cc -G -o foo.so foo.o
 261 </programlisting>
 262       or
 263 <programlisting>
 264 gcc -fpic -c foo.c
 265 gcc -shared -o foo.so foo.o
 266 </programlisting>
 267      </para>
 268     </listitem>
 269    </varlistentry>
 270
 271   </variablelist>
 272
 273  <tip>
 274   <para>
 275    If this is too complicated for you, you should consider using
 276    <ulink url="http://www.gnu.org/software/libtool/">
 277    <productname>GNU Libtool</productname></ulink>,
 278    which hides the platform differences behind a uniform interface.
 279   </para>
 280  </tip>
 281
 282  <para>
 283   The resulting shared library file can then be loaded into
 284   <productname>PostgreSQL</productname>.  When specifying the file name
 285   to the <command>CREATE FUNCTION</command> command, one must give it
 286   the name of the shared library file, not the intermediate object file.
 287   Note that the system's standard shared-library extension (usually
 288   <literal>.so</literal> or <literal>.sl</literal>) can be omitted from
 289   the <command>CREATE FUNCTION</command> command, and normally should
 290   be omitted for best portability.
 291  </para>
 292
 293  <para>
 294   Refer back to <xref linkend="xfunc-c-dynload"> about where the
 295   server expects to find the shared library files.
 296  </para>
 297
 298 <!--
 299 Under AIX, object files are compiled normally but building the shared
 300 library requires a couple of steps.  First, create the object file:
 301 .nf
 302 cc <other flags> -c foo.c
 303 .fi
 304 You must then create a symbol \*(lqexports\*(rq file for the object
 305 file:
 306 .nf
 307 mkldexport foo.o `pwd` &gt; foo.exp
 308 .fi
 309 Finally, you can create the shared library:
 310 .nf
 311 ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
 312    -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
 313    -lm -lc 2>/dev/null
 314 .fi
 315   -->
 316
 317 </sect2>