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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/dfunc.sgml,v 1.13 2001/01/20 20:59:28 petere 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 function written in
  11   C they need to be compiled and linked in a special way in order to
  12   allow it to be dynamically loaded as needed 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   Creating shared libraries is generally analoguous to linking
  29   executables:  first the source files are compiled into object files,
  30   then the object files are linked together.  The object files need to
  31   be created as <firstterm>position-independent code</firstterm>
  32   (<acronym>PIC</acronym>), which conceptually means that they can be
  33   placed at an arbitrary location in memory when they are loaded by the
  34   executable.  (Object files intended for executables are not compiled
  35   that way.)  The command to link a shared library contains special
  36   flags to distinguish it from linking an executable. --- At least
  37   this is the theory.  On some systems the practice is much uglier.
  38  </para>
  39
  40  <para>
  41   In the following examples we assume that your source code is in a
  42   file <filename>foo.c</filename> and we will create an shared library
  43   <filename>foo.so</filename>.  The intermediate object file will be
  44   called <filename>foo.o</filename> unless otherwise noted.  A shared
  45   library can contain more than one object file, but we only use one
  46   here.
  47  </para>
  48
  49  <para>
  50
  51 <!--
  52   Note:  Reading GNU Libtool sources is generally a good way of figuring out
  53   this information.  The methods used within PostgreSQL source code are not
  54   necessarily ideal.
  55 -->
  56
  57   <variablelist>
  58    <varlistentry>
  59     <term><productname>BSD/OS</productname></term>
  60     <listitem>
  61      <para>
  62       The compiler flag to create <acronym>PIC</acronym> is
  63       <option>-fpic</option>.  The linker flag to create shared
  64       libraries is <option>-shared</option>.
  65 <programlisting>
  66 gcc -fpic -c foo.c
  67 ld -shared -o foo.so foo.o
  68 </programlisting>
  69       This is applicable as of version 4.0 of
  70       <productname>BSD/OS</productname>.
  71      </para>
  72     </listitem>
  73    </varlistentry>
  74
  75    <varlistentry>
  76     <term><productname>FreeBSD</productname></term>
  77     <listitem>
  78      <para>
  79       The compiler flag to create <acronym>PIC</acronym> is
  80       <option>-fpic</option>.  To create shared libraries the compiler
  81       flag is <option>-shared</option>.
  82 <programlisting>
  83 gcc -fpic -c foo.c
  84 gcc -shared -o foo.so foo.o
  85 </programlisting>
  86       This is applicable as of version 3.0 of
  87       <productname>FreeBSD</productname>.
  88      </para>
  89     </listitem>
  90    </varlistentry>
  91
  92    <varlistentry>
  93     <term><productname>HP-UX</productname></term>
  94     <listitem>
  95      <para>
  96       The compiler flag of the system compiler to create
  97       <acronym>PIC</acronym> is <option>+z</option>.  When using
  98       <productname>GCC</productname> it's <option>-fpic</option>. The
  99       linker flag for shared libraries is <option>-b</option>.  So
 100 <programlisting>
 101 cc +z -c foo.c
 102 </programlisting>
 103       or
 104 <programlisting>
 105 gcc -fpic -c foo.c
 106 </programlisting>
 107       and then
 108 <programlisting>
 109 ld -b -o foo.sl foo.o
 110 </programlisting>
 111       <productname>HP-UX</productname> uses the extension
 112       <filename>.sl</filename> for shared libraries, unlike most other
 113       systems.
 114      </para>
 115     </listitem>
 116    </varlistentry>
 117
 118    <varlistentry>
 119     <term><productname>Irix</productname></term>
 120     <listitem>
 121      <para>
 122       <acronym>PIC</acronym> is the default, no special compiler
 123       options are necessary.  The linker option to produce shared
 124       libraries is <option>-shared</option>.
 125 <programlisting>
 126 cc -c foo.c
 127 ld -shared -o foo.so foo.o
 128 </programlisting>
 129      </para>
 130     </listitem>
 131    </varlistentry>
 132
 133    <varlistentry>
 134     <term><productname>Linux</productname></term>
 135     <listitem>
 136      <para>
 137       The compiler flag to create <acronym>PIC</acronym> is
 138       <option>-fpic</option>.  On some platforms in some situations
 139       <option>-fPIC</option> must be used if <option>-fpic</option>
 140       does not work.  Refer to the GCC manual for more information.
 141       The compiler flag to create a shared library is
 142       <option>-shared</option>.  A complete example looks like this:
 143 <programlisting>
 144 cc -fpic -c foo.c
 145 cc -shared -o foo.so foo.o
 146 </programlisting>
 147      </para>
 148     </listitem>
 149    </varlistentry>
 150
 151    <varlistentry>
 152     <term><productname>NetBSD</productname></term>
 153     <listitem>
 154      <para>
 155       The compiler flag to create <acronym>PIC</acronym> is
 156       <option>-fpic</option>.  For <acronym>ELF</acronym> systems, the
 157       compiler with the flag <option>-shared</option> is used to link
 158       shared libraries.  On the older non-ELF systems, <literal>ld
 159       -Bshareable</literal> is used.
 160 <programlisting>
 161 gcc -fpic -c foo.c
 162 gcc -shared -o foo.so foo.o
 163 </programlisting>
 164      </para>
 165     </listitem>
 166    </varlistentry>
 167
 168    <varlistentry>
 169     <term><productname>OpenBSD</productname></term>
 170     <listitem>
 171      <para>
 172       The compiler flag to create <acronym>PIC</acronym> is
 173       <option>-fpic</option>.  <literal>ld -Bshareable</literal> is
 174       used to link shared libraries.
 175 <programlisting>
 176 gcc -fpic -c foo.c
 177 ld -Bshareable -o foo.so foo.o
 178 </programlisting>
 179      </para>
 180     </listitem>
 181    </varlistentry>
 182
 183    <varlistentry>
 184     <term>Digital Unix/Tru64 UNIX</term>
 185
 186     <listitem>
 187      <para>
 188       <acronym>PIC</acronym> is the default, so the compilation command
 189       is the usual one.  <command>ld</command> with special options is
 190       used to do the linking:
 191 <programlisting>
 192 cc -c foo.c
 193 ld -shared -expect_unresolved '*' -o foo.so foo.o
 194 </programlisting>
 195       The same procedure is used with GCC instead of the system
 196       compiler; no special options are required.
 197      </para>
 198     </listitem>
 199    </varlistentry>
 200
 201    <varlistentry>
 202     <term><productname>Solaris</productname></term>
 203     <listitem>
 204      <para>
 205       The compiler flag to create <acronym>PIC</acronym> is
 206       <option>-KPIC</option> with the Sun compiler and
 207       <option>-fpic</option> with <productname>GCC</productname>.  To
 208       link shared libraries, the compiler option is
 209       <option>-G</option> with either compiler or alternatively
 210       <option>-shared</option> with <productname>GCC</productname>.
 211 <programlisting>
 212 cc -KPIC -c foo.c
 213 cc -G -o foo.so foo.o
 214 </programlisting>
 215       or
 216 <programlisting>
 217 gcc -fpic -c foo.c
 218 gcc -G -o foo.so foo.o
 219 </programlisting>
 220      </para>
 221     </listitem>
 222    </varlistentry>
 223
 224    <varlistentry>
 225     <term><productname>Unixware</productname></term>
 226     <listitem>
 227      <para>
 228       The compiler flag to create <acronym>PIC</acronym> is <option>-K
 229       PIC</option> with the SCO compiler and <option>-fpic</option>
 230       with <productname>GCC</productname>.  To link shared libraries,
 231       the compiler option is <option>-G</option> with the SCO compiler
 232       and <option>-shared</option> with
 233       <productname>GCC</productname>.
 234 <programlisting>
 235 cc -K PIC -c foo.c
 236 cc -G -o foo.so foo.o
 237 </programlisting>
 238       or
 239 <programlisting>
 240 gcc -fpic -c foo.c
 241 gcc -shared -o foo.so foo.o
 242 </programlisting>
 243      </para>
 244     </listitem>
 245    </varlistentry>
 246
 247   </variablelist>
 248  </para>
 249
 250  <tip>
 251   <para>
 252    If you want to package your extension modules for wide distribution
 253    you should consider using <ulink
 254    url="http://www.gnu.org/software/libtool/"><productname>GNU
 255    Libtool</productname></ulink> for building shared libraries.  It
 256    encapsulates the platform differences into a general and powerful
 257    interface.  Serious packaging also requires considerations about
 258    library versioning, symbol resolution methods, and other issues.
 259   </para>
 260  </tip>
 261
 262  <para>
 263   The resulting shared library file can then be loaded into
 264   <productname>Postgres</productname>.  When specifying the file name
 265   to the <command>CREATE FUNCTION</command> command, one must give it
 266   the name of the shared library file (ending in
 267   <filename>.so</filename>) rather than the simple object file.
 268
 269   <note>
 270    <para>
 271     Actually, <productname>Postgres</productname> does not care what
 272     you name the file as long as it is a shared library file.
 273    </para>
 274   </note>
 275
 276   Paths given to the <command>CREATE FUNCTION</command> command must
 277   be absolute paths (i.e., start with <literal>/</literal>) that refer
 278   to directories visible on the machine on which the
 279   <productname>Postgres</productname> server is running.  Relative
 280   paths do in fact work, but are relative to the directory where the
 281   database resides (which is generally invisible to the frontend
 282   application).  Obviously, it makes no sense to make the path
 283   relative to the directory in which the user started the frontend
 284   application, since the server could be running on a completely
 285   different machine!  The user id the
 286   <productname>Postgres</productname> server runs as must be able to
 287   traverse the path given to the <command>CREATE FUNCTION</command>
 288   command and be able to read the shared library file.  (Making the
 289   file or a higher-level directory not readable and/or not executable
 290   by the <quote>postgres</quote> user is a common mistake.)
 291  </para>
 292
 293 <!--
 294 Under AIX, object files are compiled normally but building the shared
 295 library requires a couple of steps.  First, create the object file:
 296 .nf
 297 cc <other flags> -c foo.c
 298 .fi
 299 You must then create a symbol \*(lqexports\*(rq file for the object
 300 file:
 301 .nf
 302 mkldexport foo.o `pwd` > foo.exp
 303 .fi
 304 Finally, you can create the shared library:
 305 .nf
 306 ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
 307    -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
 308    -lm -lc 2>/dev/null
 309 .fi
 310 You should look at the Postgres User's Manual for an explanation of this
 311 procedure.
 312
 313   -->
 314
 315 </sect2>
 316
 317 <!-- Keep this comment at the end of the file
 318 Local variables:
 319 mode:sgml
 320 sgml-omittag:nil
 321 sgml-shorttag:t
 322 sgml-minimize-attributes:nil
 323 sgml-always-quote-attributes:t
 324 sgml-indent-step:1
 325 sgml-indent-data:t
 326 sgml-parent-document:nil
 327 sgml-default-dtd-file:"./reference.ced"
 328 sgml-exposed-tags:nil
 329 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 330 sgml-local-ecat-files:nil
 331 End:
 332 -->