| 1 |
<!-- doc/src/sgml/dfunc.sgml --> |
| 2 |
|
| 3 |
<sect2 id="dfunc"> |
| 4 |
<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</primary></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</primary></indexterm> 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 |
— 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> |
| 60 |
<systemitem class="osname">FreeBSD</systemitem> |
| 61 |
<indexterm><primary>FreeBSD</primary><secondary>shared library</secondary></indexterm> |
| 62 |
</term> |
| 63 |
<listitem> |
| 64 |
<para> |
| 65 |
The compiler flag to create <acronym>PIC</acronym> is |
| 66 |
<option>-fPIC</option>. To create shared libraries the compiler |
| 67 |
flag is <option>-shared</option>. |
| 68 |
<programlisting> |
| 69 |
cc -fPIC -c foo.c |
| 70 |
cc -shared -o foo.so foo.o |
| 71 |
</programlisting> |
| 72 |
This is applicable as of version 13.0 of |
| 73 |
<systemitem class="osname">FreeBSD</systemitem>, older versions used |
| 74 |
the <filename>gcc</filename> compiler. |
| 75 |
</para> |
| 76 |
</listitem> |
| 77 |
</varlistentry> |
| 78 |
|
| 79 |
<varlistentry> |
| 80 |
<term> |
| 81 |
<systemitem class="osname">Linux</systemitem> |
| 82 |
<indexterm><primary>Linux</primary><secondary>shared library</secondary></indexterm> |
| 83 |
</term> |
| 84 |
<listitem> |
| 85 |
<para> |
| 86 |
The compiler flag to create <acronym>PIC</acronym> is |
| 87 |
<option>-fPIC</option>. |
| 88 |
The compiler flag to create a shared library is |
| 89 |
<option>-shared</option>. A complete example looks like this: |
| 90 |
<programlisting> |
| 91 |
cc -fPIC -c foo.c |
| 92 |
cc -shared -o foo.so foo.o |
| 93 |
</programlisting> |
| 94 |
</para> |
| 95 |
</listitem> |
| 96 |
</varlistentry> |
| 97 |
|
| 98 |
<varlistentry> |
| 99 |
<term> |
| 100 |
<systemitem class="osname">macOS</systemitem> |
| 101 |
<indexterm><primary>macOS</primary><secondary>shared library</secondary></indexterm> |
| 102 |
</term> |
| 103 |
<listitem> |
| 104 |
<para> |
| 105 |
Here is an example. It assumes the developer tools are installed. |
| 106 |
<programlisting> |
| 107 |
cc -c foo.c |
| 108 |
cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o |
| 109 |
</programlisting> |
| 110 |
</para> |
| 111 |
</listitem> |
| 112 |
</varlistentry> |
| 113 |
|
| 114 |
<varlistentry> |
| 115 |
<term> |
| 116 |
<systemitem class="osname">NetBSD</systemitem> |
| 117 |
<indexterm><primary>NetBSD</primary><secondary>shared library</secondary></indexterm> |
| 118 |
</term> |
| 119 |
<listitem> |
| 120 |
<para> |
| 121 |
The compiler flag to create <acronym>PIC</acronym> is |
| 122 |
<option>-fPIC</option>. For <acronym>ELF</acronym> systems, the |
| 123 |
compiler with the flag <option>-shared</option> is used to link |
| 124 |
shared libraries. On the older non-ELF systems, <literal>ld |
| 125 |
-Bshareable</literal> is used. |
| 126 |
<programlisting> |
| 127 |
gcc -fPIC -c foo.c |
| 128 |
gcc -shared -o foo.so foo.o |
| 129 |
</programlisting> |
| 130 |
</para> |
| 131 |
</listitem> |
| 132 |
</varlistentry> |
| 133 |
|
| 134 |
<varlistentry> |
| 135 |
<term> |
| 136 |
<systemitem class="osname">OpenBSD</systemitem> |
| 137 |
<indexterm><primary>OpenBSD</primary><secondary>shared library</secondary></indexterm> |
| 138 |
</term> |
| 139 |
<listitem> |
| 140 |
<para> |
| 141 |
The compiler flag to create <acronym>PIC</acronym> is |
| 142 |
<option>-fPIC</option>. <literal>ld -Bshareable</literal> is |
| 143 |
used to link shared libraries. |
| 144 |
<programlisting> |
| 145 |
gcc -fPIC -c foo.c |
| 146 |
ld -Bshareable -o foo.so foo.o |
| 147 |
</programlisting> |
| 148 |
</para> |
| 149 |
</listitem> |
| 150 |
</varlistentry> |
| 151 |
|
| 152 |
<varlistentry> |
| 153 |
<term> |
| 154 |
<systemitem class="osname">Solaris</systemitem> |
| 155 |
<indexterm><primary>Solaris</primary><secondary>shared library</secondary></indexterm> |
| 156 |
</term> |
| 157 |
<listitem> |
| 158 |
<para> |
| 159 |
The compiler flag to create <acronym>PIC</acronym> is |
| 160 |
<option>-KPIC</option> with the Sun compiler and |
| 161 |
<option>-fPIC</option> with <application>GCC</application>. To |
| 162 |
link shared libraries, the compiler option is |
| 163 |
<option>-G</option> with either compiler or alternatively |
| 164 |
<option>-shared</option> with <application>GCC</application>. |
| 165 |
<programlisting> |
| 166 |
cc -KPIC -c foo.c |
| 167 |
cc -G -o foo.so foo.o |
| 168 |
</programlisting> |
| 169 |
or |
| 170 |
<programlisting> |
| 171 |
gcc -fPIC -c foo.c |
| 172 |
gcc -G -o foo.so foo.o |
| 173 |
</programlisting> |
| 174 |
</para> |
| 175 |
</listitem> |
| 176 |
</varlistentry> |
| 177 |
|
| 178 |
</variablelist> |
| 179 |
|
| 180 |
<tip> |
| 181 |
<para> |
| 182 |
If this is too complicated for you, you should consider using |
| 183 |
<ulink url="https://www.gnu.org/software/libtool/"> |
| 184 |
<productname>GNU Libtool</productname></ulink>, |
| 185 |
which hides the platform differences behind a uniform interface. |
| 186 |
</para> |
| 187 |
</tip> |
| 188 |
|
| 189 |
<para> |
| 190 |
The resulting shared library file can then be loaded into |
| 191 |
<productname>PostgreSQL</productname>. When specifying the file name |
| 192 |
to the <command>CREATE FUNCTION</command> command, one must give it |
| 193 |
the name of the shared library file, not the intermediate object file. |
| 194 |
Note that the system's standard shared-library extension (usually |
| 195 |
<literal>.so</literal> or <literal>.sl</literal>) can be omitted from |
| 196 |
the <command>CREATE FUNCTION</command> command, and normally should |
| 197 |
be omitted for best portability. |
| 198 |
</para> |
| 199 |
|
| 200 |
<para> |
| 201 |
Refer back to <xref linkend="xfunc-c-dynload"/> about where the |
| 202 |
server expects to find the shared library files. |
| 203 |
</para> |
| 204 |
|
| 205 |
</sect2> |