← Back to branch summary

~vcs-imports/mammoth-replicator/trunk

« back to all changes in this revision

Viewing changes to doc/src/sgml/dfunc.sgml

  • Committer: alvherre
  • Date: 2005-12-16 21:24:52 UTC
  • Revision ID: svn-v4:db760fc0-0f08-0410-9d63-cc6633f64896:trunk:1
Initial import of the REL8_0_3 sources from the Pgsql CVS repository.

Show diffs side-by-side

added added

removed removed

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