granicus.if.org Git - postgresql/blob - doc/src/sgml/dfunc.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.21 2002/08/26 23:22:47 momjian Exp $
   3 -->
   4
   5 <sect2 id="dfunc">
   6  <title id="dfunc-title">Compiling and Linking Dynamically-Loaded Functions</title>
   7
   8  <para>
   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.
  14  </para>
  15
  16  <para>
  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.
  25  </para>
  26
  27  <para>
  28   <indexterm><primary>PIC</></>
  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>), 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.
  39  </para>
  40
  41  <para>
  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
  47   here.
  48  </para>
  49
  50  <para>
  51
  52 <!--
  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
  56   necessarily ideal.
  57 -->
  58
  59   <variablelist>
  60    <varlistentry>
  61     <term><productname>BSD/OS</productname></term>
  62     <indexterm><primary>BSD/OS</></>
  63     <listitem>
  64      <para>
  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>.
  68 <programlisting>
  69 gcc -fpic -c foo.c
  70 ld -shared -o foo.so foo.o
  71 </programlisting>
  72       This is applicable as of version 4.0 of
  73       <productname>BSD/OS</productname>.
  74      </para>
  75     </listitem>
  76    </varlistentry>
  77
  78    <varlistentry>
  79     <term><productname>FreeBSD</productname></term>
  80     <indexterm><primary>FreeBSD</></>
  81     <listitem>
  82      <para>
  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>.
  86 <programlisting>
  87 gcc -fpic -c foo.c
  88 gcc -shared -o foo.so foo.o
  89 </programlisting>
  90       This is applicable as of version 3.0 of
  91       <productname>FreeBSD</productname>.
  92      </para>
  93     </listitem>
  94    </varlistentry>
  95
  96    <varlistentry>
  97     <term><productname>HP-UX</productname></term>
  98     <indexterm><primary>HP-UX</></>
  99     <listitem>
 100      <para>
 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
 105 <programlisting>
 106 cc +z -c foo.c
 107 </programlisting>
 108       or
 109 <programlisting>
 110 gcc -fpic -c foo.c
 111 </programlisting>
 112       and then
 113 <programlisting>
 114 ld -b -o foo.sl foo.o
 115 </programlisting>
 116       <productname>HP-UX</productname> uses the extension
 117       <filename>.sl</filename> for shared libraries, unlike most other
 118       systems.
 119      </para>
 120     </listitem>
 121    </varlistentry>
 122
 123    <varlistentry>
 124     <term><productname>IRIX</productname></term>
 125     <indexterm><primary>IRIX</></>
 126     <listitem>
 127      <para>
 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>.
 131 <programlisting>
 132 cc -c foo.c
 133 ld -shared -o foo.so foo.o
 134 </programlisting>
 135      </para>
 136     </listitem>
 137    </varlistentry>
 138
 139    <varlistentry>
 140     <term><productname>Linux</productname></term>
 141     <indexterm><primary>Linux</></>
 142     <listitem>
 143      <para>
 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:
 150 <programlisting>
 151 cc -fpic -c foo.c
 152 cc -shared -o foo.so foo.o
 153 </programlisting>
 154      </para>
 155     </listitem>
 156    </varlistentry>
 157
 158    <varlistentry>
 159     <term><productname>NetBSD</productname></term>
 160     <indexterm><primary>NetBSD</></>
 161     <listitem>
 162      <para>
 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.
 168 <programlisting>
 169 gcc -fpic -c foo.c
 170 gcc -shared -o foo.so foo.o
 171 </programlisting>
 172      </para>
 173     </listitem>
 174    </varlistentry>
 175
 176    <varlistentry>
 177     <term><productname>OpenBSD</productname></term>
 178     <indexterm><primary>OpenBSD</></>
 179     <listitem>
 180      <para>
 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.
 184 <programlisting>
 185 gcc -fpic -c foo.c
 186 ld -Bshareable -o foo.so foo.o
 187 </programlisting>
 188      </para>
 189     </listitem>
 190    </varlistentry>
 191
 192    <varlistentry>
 193     <term><productname>OS X</productname></term>
 194     <indexterm><primary>OS X</></>
 195     <listitem>
 196      <para>
 197       Here is a sample.  It assumes the developer tools are installed.
 198 <programlisting>
 199 cc -c foo.c
 200 cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o
 201 </programlisting>
 202      </para>
 203     </listitem>
 204    </varlistentry>
 205
 206    <varlistentry>
 207     <term><productname>Solaris</productname></term>
 208     <indexterm><primary>Solaris</></>
 209     <listitem>
 210      <para>
 211       The compiler flag to create <acronym>PIC</acronym> is
 212       <option>-KPIC</option> with the Sun compiler and
 213       <option>-fpic</option> with <productname>GCC</productname>.  To
 214       link shared libraries, the compiler option is
 215       <option>-G</option> with either compiler or alternatively
 216       <option>-shared</option> with <productname>GCC</productname>.
 217 <programlisting>
 218 cc -KPIC -c foo.c
 219 cc -G -o foo.so foo.o
 220 </programlisting>
 221       or
 222 <programlisting>
 223 gcc -fpic -c foo.c
 224 gcc -G -o foo.so foo.o
 225 </programlisting>
 226      </para>
 227     </listitem>
 228    </varlistentry>
 229
 230    <varlistentry>
 231     <term>Tru64 UNIX</term>
 232     <indexterm><primary>Tru64 UNIX</></>
 233     <indexterm><primary>Digital UNIX</><see>Tru64 UNIX</></>
 234     <listitem>
 235      <para>
 236       <acronym>PIC</acronym> is the default, so the compilation command
 237       is the usual one.  <command>ld</command> with special options is
 238       used to do the linking:
 239 <programlisting>
 240 cc -c foo.c
 241 ld -shared -expect_unresolved '*' -o foo.so foo.o
 242 </programlisting>
 243       The same procedure is used with GCC instead of the system
 244       compiler; no special options are required.
 245      </para>
 246     </listitem>
 247    </varlistentry>
 248
 249    <varlistentry>
 250     <term><productname>UnixWare</productname></term>
 251     <indexterm><primary>UnixWare</></>
 252     <listitem>
 253      <para>
 254       The compiler flag to create <acronym>PIC</acronym> is <option>-K
 255       PIC</option> with the SCO compiler and <option>-fpic</option>
 256       with <productname>GCC</productname>.  To link shared libraries,
 257       the compiler option is <option>-G</option> with the SCO compiler
 258       and <option>-shared</option> with
 259       <productname>GCC</productname>.
 260 <programlisting>
 261 cc -K PIC -c foo.c
 262 cc -G -o foo.so foo.o
 263 </programlisting>
 264       or
 265 <programlisting>
 266 gcc -fpic -c foo.c
 267 gcc -shared -o foo.so foo.o
 268 </programlisting>
 269      </para>
 270     </listitem>
 271    </varlistentry>
 272
 273   </variablelist>
 274  </para>
 275
 276  <tip>
 277   <para>
 278    If you want to package your extension modules for wide distribution
 279    you should consider using <ulink
 280    url="http://www.gnu.org/software/libtool/"><productname>GNU
 281    Libtool</productname></ulink> for building shared libraries.  It
 282    encapsulates the platform differences into a general and powerful
 283    interface.  Serious packaging also requires considerations about
 284    library versioning, symbol resolution methods, and other issues.
 285   </para>
 286  </tip>
 287
 288  <para>
 289   The resulting shared library file can then be loaded into
 290   <productname>PostgreSQL</productname>.  When specifying the file name
 291   to the <command>CREATE FUNCTION</command> command, one must give it
 292   the name of the shared library file, not the intermediate object file.
 293   Note that the system's standard shared-library extension (usually
 294   <literal>.so</literal> or <literal>.sl</literal>) can be omitted from
 295   the <command>CREATE FUNCTION</command> command, and normally should
 296   be omitted for best portability.
 297  </para>
 298
 299  <para>
 300   Refer back to <xref linkend="xfunc-c-dynload"> about where the
 301   server expects to find the shared library files.
 302  </para>
 303
 304 <!--
 305 Under AIX, object files are compiled normally but building the shared
 306 library requires a couple of steps.  First, create the object file:
 307 .nf
 308 cc <other flags> -c foo.c
 309 .fi
 310 You must then create a symbol \*(lqexports\*(rq file for the object
 311 file:
 312 .nf
 313 mkldexport foo.o `pwd` > foo.exp
 314 .fi
 315 Finally, you can create the shared library:
 316 .nf
 317 ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
 318    -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
 319    -lm -lc 2>/dev/null
 320 .fi
 321 You should look at the <citetitle>PostgreSQL User's Manual</>
 322 for an explanation of this
 323 procedure.
 324
 325   -->
 326
 327 </sect2>
 328
 329 <!-- Keep this comment at the end of the file
 330 Local variables:
 331 mode:sgml
 332 sgml-omittag:nil
 333 sgml-shorttag:t
 334 sgml-minimize-attributes:nil
 335 sgml-always-quote-attributes:t
 336 sgml-indent-step:1
 337 sgml-indent-tabs-mode:nil
 338 sgml-indent-data:t
 339 sgml-parent-document:nil
 340 sgml-default-dtd-file:"./reference.ced"
 341 sgml-exposed-tags:nil
 342 sgml-local-catalogs:("/usr/share/sgml/catalog")
 343 sgml-local-ecat-files:nil
 344 End:
 345 -->