dfunc.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/dfunc.sgml,v 1.28 2004/11/15 06:32:13 neilc Exp $
-->

<sect2 id="dfunc">
 <title id="dfunc-title">Compilar e ligar as funções carregadas dinamicamente</title>

 <para>
  Antes que as funções escritas em C para estender o
  <productname>PostgreSQL</productname> possam ser utilizadas, estas funções
  precisam ser compiladas e ligadas de uma forma especial para produzir um
  arquivo que possa ser carregado dinamicamente pelo servidor. Para ser exato,
  precisa ser criada uma <firstterm>biblioteca compartilhada</firstterm>.
  <indexterm><primary>biblioteca compartilhada</primary></indexterm>

 </para>

 <para>
  Para obter informações além das contidas nesta seção deve ser lida a
  documentação do sistema operacional, em particular as páginas do manual do
  compilador C, <command>gcc</command>, e do editor de ligação,
  <command>ld</command>.
  Além disso, o código fonte do <productname>PostgreSQL</productname> contém
  vários exemplos funcionais no diretório
  <filename class="directory">contrib</filename>. Entretanto, a dependência
  destes exemplos torna os módulos dependentes da disponibilidade do código
  fonte do <productname>PostgreSQL</productname>.
 </para>

 <para>
  <indexterm><primary>PIC</primary></indexterm>
  Criar bibliotecas compartilhadas geralmente é análogo a ligar executáveis:
  primeiro os arquivos fonte são compilados em arquivos objetos e, depois, os
  arquivos objeto são ligados. Os arquivos objeto precisam ser criados como
  <firstterm>código independente de posição</firstterm>
  (<acronym>PIC</acronym>), o que significa conceitualmente que podem ser
  colocados em uma posição de memória arbitrária ao serem carregados pelo
  executável (Os arquivos objeto destinados a executáveis geralmente não são
  compilados deste modo). O comando para ligar uma biblioteca compartilhada
  contém sinalizadores especiais para distinguir da ligação de um executável
  (ao menos em teoria &mdash; em alguns sistemas a prática é muito mais feia).
 </para>

 <para>
  Nos exemplos a seguir é assumido que o código fonte está no arquivo
  <filename>foo.c</filename>, e que é criada a biblioteca compartilhada
  <filename>foo.so</filename>. O arquivo objeto intermediário se chama
  <filename>foo.o</filename>, a não ser que seja dito o contrário. A biblioteca
  compartilhada pode conter mais de um arquivo objeto, mas aqui é utilizado
  apenas um arquivo.
 </para>

<!--
  Note: Reading GNU Libtool sources is generally a good way of
  figuring out this information.  The methods used within PostgreSQL
  source code are not necessarily ideal.
-->

  <variablelist>
   <varlistentry>
    <term><systemitem class="osname">BSD/OS</></term>
    <indexterm><primary>BSD/OS</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador para criar <acronym>PIC</acronym> é
      <option>-fpic</option>. O sinalizador do ligador para criar biblioteca
      compartilhada é <option>-shared</option>.
<programlisting>
gcc -fpic -c foo.c
ld -shared -o foo.so foo.o
</programlisting>
      Isto se aplica a partir da versão 4.0 do
      <systemitem class="osname">BSD/OS</>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">FreeBSD</></term>
    <indexterm><primary>FreeBSD</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador para criar <acronym>PIC</acronym> é
      <option>-fpic</option>.  Para criar bibliotecas compartilhadas o
      sinalizador do compilador é <option>-shared</option>.
<programlisting>
gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o
</programlisting>
      Isto se aplica a partir a versão 3.0 do
      <systemitem class="osname">FreeBSD</>.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">HP-UX</></term>
    <indexterm><primary>HP-UX</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador do sistema para criar <acronym>PIC</acronym>
      é <option>+z</option>. Quando se utiliza o <application>GCC</application>
      é <option>-fpic</option>. O sinalizador do ligador para criar bibliotecas
      compartilhadas é <option>-b</option>. Portanto
<programlisting>
cc +z -c foo.c
</programlisting>
      ou
<programlisting>
gcc -fpic -c foo.c
</programlisting>
      e depois
<programlisting>
ld -b -o foo.sl foo.o
</programlisting>
      O <systemitem class="osname">HP-UX</systemitem> utiliza a extensão
      <filename>.sl</filename> para bibliotecas compartilhadas, diferentemente
      da maioria dos outros sistemas.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">IRIX</></term>
    <indexterm><primary>IRIX</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      <acronym>PIC</acronym> é o padrão, não é necessário nenhum sinalizador
      especial do compilador. A opção do ligador para criar bibliotecas
      compartilhadas é <option>-shared</option>.
<programlisting>
cc -c foo.c
ld -shared -o foo.so foo.o
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">Linux</></term>
    <indexterm><primary>Linux</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador para criar <acronym>PIC</acronym> é
      <option>-fpic</option>. Em certas situações em algumas plataformas deve
      ser utilizado <option>-fPIC</option> se <option>-fpic</option> não
      funcionar. Deve ser consultado o manual do GCC para obter mais
      informações. O sinalizador do compilador para criar a biblioteca
      compartilhada é <option>-shared</option>. Um exemplo completo se parece
      com:
<programlisting>
cc -fpic -c foo.c
cc -shared -o foo.so foo.o
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">MacOS X</></term>
    <indexterm><primary>MacOS X</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      Abaixo segue um exemplo. É assumido que as ferramentas de desenvolvimento
      estão instaladas.
<programlisting>
cc -c foo.c
cc -bundle -flat_namespace -undefined suppress -o foo.so foo.o
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">NetBSD</></term>
    <indexterm><primary>NetBSD</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador para criar <acronym>PIC</acronym> é
      <option>-fpic</option>. Nos sistemas <acronym>ELF</acronym>, é utilizado
      o compilador com o sinalizador <option>-shared</option> para ligar as
      bibliotecas compartilhadas. Nos sistemas antigos, não-ELF, é utilizado
      <literal>ld -Bshareable</literal>.
<programlisting>
gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">OpenBSD</></term>
    <indexterm><primary>OpenBSD</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador para criar <acronym>PIC</acronym> é
      <option>-fpic</option>. É utilizado <literal>ld -Bshareable</literal>
      para ligar bibliotecas compartilhadas.
<programlisting>
gcc -fpic -c foo.c
ld -Bshareable -o foo.so foo.o
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">Solaris</></term>
    <indexterm><primary>Solaris</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador para criar <acronym>PIC</acronym> é
      <option>-KPIC</option> quando é utilizado o compilador da Sun, e
      <option>-fpic</option> quando é utilizado o
      <application>GCC</application>. Para ligar bibliotecas compartilhadas a
      opção do compilador é <option>-G</option> para os dois compiladores ou,
      como alternativa, <option>-shared</option> quando é utilizado o
      <application>GCC</application>.
<programlisting>
cc -KPIC -c foo.c
cc -G -o foo.so foo.o
</programlisting>
      ou
<programlisting>
gcc -fpic -c foo.c
gcc -G -o foo.so foo.o
</programlisting>
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">Tru64 UNIX</></term>
    <indexterm><primary>Tru64 UNIX</><secondary>biblioteca compartilhada</secondary></>
    <indexterm><primary>Digital UNIX</><see>Tru64 UNIX</></>
    <listitem>
     <para>
      <acronym>PIC</acronym> é o padrão e, portanto, o comando para compilar é o
      usual. É utilizado <command>ld</command> com opções especiais para ligar:
<programlisting>
cc -c foo.c
ld -shared -expect_unresolved '*' -o foo.so foo.o
</programlisting>
      O mesmo procedimento é empregado quando GCC é utilizado no lugar
      do compilador do sistema; nenhuma opção especial é necessária.
     </para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term><systemitem class="osname">UnixWare</></term>
    <indexterm><primary>UnixWare</><secondary>biblioteca compartilhada</secondary></>
    <listitem>
     <para>
      O sinalizador do compilador para criar <acronym>PIC</acronym> é
      <option>-K PIC</option> quando é utilizado o compilador da SCO, e
      <option>-fpic</option> no <productname>GCC</productname>. Para ligar
      bibliotecas compartilhadas a opção do compilador é <option>-G</option>
      quando é utilizado o compilador da SCO e <option>-shared</option> quando
      é utilizado o <productname>GCC</productname>.
<programlisting>
cc -K PIC -c foo.c
cc -G -o foo.so foo.o
</programlisting>
      or
<programlisting>
gcc -fpic -c foo.c
gcc -shared -o foo.so foo.o
</programlisting>
     </para>
    </listitem>
   </varlistentry>

  </variablelist>

 <tip>
  <para>
   Caso julgue muito complicado, poderá ser levado em consideração a utilização
   da <ulink url="http://www.gnu.org/software/libtool/"><productname>GNU
   Libtool</productname></ulink>, que esconde as diferenças entre as plataformas
   atrás de uma interface uniforme.
  </para>
 </tip>

 <para>
  O arquivo de biblioteca compartilhada produzido pode então ser carregado no
  <productname>PostgreSQL</productname>. Ao se especificar o nome do arquivo
  no comando <command>CREATE FUNCTION</command>, deve ser especificado o nome
  do arquivo da biblioteca compartilhada, e não do arquivo objeto intermediário.
  Deve ser observado que a extensão padrão do sistema para biblioteca
  compartilhada (geralmente <literal>.so</literal> ou <literal>.sl</literal>)
  pode ser omitida no comando <command>CREATE FUNCTION</command>, e normalmente
  deve ser omitida para uma melhor portabilidade.
 </para>

 <para>
  Veja na <xref linkend="xfunc-c-dynload"> onde o servidor espera encontrar os
  arquivos de biblioteca compartilhada.
 </para>

<!--
Under AIX, object files are compiled normally but building the shared
library requires a couple of steps.  First, create the object file:
.nf
cc <other flags> -c foo.c
.fi
You must then create a symbol \*(lqexports\*(rq file for the object
file:
.nf
mkldexport foo.o `pwd` > foo.exp
.fi
Finally, you can create the shared library:
.nf
ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
   -bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
   -lm -lc 2>/dev/null
.fi
  -->

</sect2>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-tabs-mode:nil
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/share/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->