NOME

       dpkg-gensymbols - gera ficheiros symbols (informação de dependência de biblioteca
       partilhada)

RESUMO

       dpkg-gensymbols [option...]

DESCRIÇÃO

       dpkg-gensymbols sonda uma árvore de compilação temporária (debian/tmp por predefinição) à
       procura de bibliotecas e gera um ficheiro symbols a descreve-los. Este ficheiro, se não
       vazio, é depois instalado no sub-directório DEBIAN da árvore de compilação para que seja
       incluído na informação de controle do pacote.

       Quando gera esses ficheiros, usa como entrada alguns ficheiros de símbolos
       disponibilizados pelo maintainer. Procura os seguintes ficheiros (e usa o primeiro que
       encontra):

       •   debian/package.symbols.arch

       •   debian/symbols.arch

       •   debian/package.symbols

       •   debian/symbols

       O principal interesse desse ficheiros é disponibilizar a versão mínima associada a cada
       símbolo fornecido pelas bibliotecas. Geralmente isso corresponde à primeira versão do
       pacote que forneceu o símbolo, mas pode ser incrementada pelo maintainer se o ABI do
       símbolo é extensível sem se quebrar a compatibilidade com versões anteriores. É da
       responsabilidade do maintainer manter esses ficheiros actualizados e precisos, mas o dpkg-
       gensymbols ajuda com isso.

       Quando os ficheiros de símbolos gerados diferem daqueles fornecidos pelo maintainer, dpkg-
       gensymbols irá escrever um diff entre as duas versões. Mais ainda, se a diferença for
       muito significante, irá mesmo falhar (você pode personalizar quanta diferença pode ser
       tolerada, veja a opção -c).

       Este programa foi introduzido no dpkg 1.14.8.

MANTENDO FICHEIROS DE SÍMBOLOS

       O formato de intercâmbio base do ficheiro de símbolos é descrito em deb-symbols(5), o qual
       é usado pelos ficheiros symbols incluídos em pacotes binários. Estes são gerados a partir
       de ficheiros se símbolos modelo com um formato baseado no anterior, descrito em
       deb-src-symbols(5) e incluído em pacotes fonte.

       Os ficheiros de símbolos são apenas úteis se refletirem a evolução do pacote entre vários
       lançamentos. Assim o maintainer tem de os actualizar todas as vezes que é adicionado um
       novo símbolo para que a sua versão mínima associada corresponda à realidade.

       Os diffs contidos nos logs de compilação podem ser usados com ponto de partida, mas o
       maintainer, adicionalmente, tem de certificar que o comportamento desses símbolos não
       alterou num modo que faça com que tudo o que usa esses símbolos e em link para a nova
       versão, deixem de funcionar com a versão antiga.

       Na maioria dos casos, o diff aplica-se directamente ao ficheiro debian/package.symbols.
       Dito isso, geralmente são necessários mais ajustes: é recomendado, por exemplo, soltar a
       revisão Debian da versão mínima para que backports com um número de versão inferior mas a
       mesma versão de autor consigam ainda satisfazer as dependências geradas. Se uma revisão
       Debian não pode ser largada porque o símbolo foi realmente adicionado pela alteração
       específica de Debian, então deve-se acrescentar um sufixo à versão com ‘~’.

       Antes de aplicar qualquer patch ao ficheiro symbols, o maintainer deve re-verificar que
       esta é saudável. Não é suposto símbolos públicos desaparecerem, assim a patch deve
       idealmente apenas adicionar novas linhas.

       Note que você pode meter comentários em ficheiros de símbolos.

       Não se esqueça de verificar se versões antigas de símbolos precisam de ser aumentadas. Não
       há maneira de dpkg-gensymbols poder avisar sobre isto. Aplica o diff às cegas ou assumir
       que não há nada para mudar se não existir um diff, sem verificar por tais mudanças, pode
       levar a pacotes com dependências soltas, que afirmam poder trabalhar com pacotes mais
       antigos com que já não podem trabalhar. Isto irá introduzir dificuldades de encontrar bugs
       com actualizações (parciais).

   Boa gestão de biblioteca
       Uma biblioteca bem mantida tem as seguintes características:

       •   A sua API é estável (símbolos públicos nunca são largados, apenas símbolos públicos
           novos são adicionados) e alterações em modos incompatíveis sempre apenas quando o
           SONAME muda;

       •   idealmente, usa a identificação da versão do símbolo para obter estabilidade da ABI
           apesar de alterações internas e extensão API;

       •   não exporta símbolos privados (tais símbolos podem ser etiquetados de opcionais como
           meio de contornar).

       Enquanto se mantém o ficheiro symbols, é fácil percebermos o aparecimento e
       desaparecimento de símbolos. Mas é  mais difícil apanhar alterações de API e ABI
       incompatíveis. Assim o maintainer deve ler com atenção o registo de alterações do autor
       procurando casos onde as regras da boa gestão de bibliotecas foram quebradas. Se forem
       descobertos potenciais problemas, o autor original deve ser notificado pois uma correcção
       no autor é sempre melhor que um contorno especifico em Debian.

OPÇÕES

       -Ppackage-build-dir
           Sonda package-build-dir em vez de debian/tmp.

       -ppackage
           Define o nome do pacote. Requerido se mais do que um pacote binário estiver listado em
           debian/control (ou se não existir o ficheiro debian/control).

       -vversion
           Define a versão do pacote. Usa por predefinição a versão extraída de debian/changelog.
           Requerido se chamado fora de uma árvore de pacote fonte.

       -elibrary-file
           Apenas analisa bibliotecas explicitas em vez de procurar todas as bibliotecas
           públicas. Você pode usar padrões de shell usadas para expansões de nome de caminho
           (veja o manual File::Glob para detalhes) em library-file para corresponder a múltiplas
           bibliotecas com um único argumento (caso contrário você precisa de múltiplos -e).

       -ldirectory
           Precede directory à lista de directórios a pesquisar por bibliotecas partilhadas
           privadas (desde dpkg 1.19.1). Esta opção pode ser usada várias vezes.

           Nota: Use esta opção em vez de definir LD_LIBRARY_PATH, pois essa variável de ambiente
           é usado para controlar o vinculador de tempo-de-execução e abusar dela para definir
           caminhos de bibliotecas partilhadas durante a compilação pode ser problemático quando,
           por exemplo, se faz compilações cruzadas.

       -Ifilename
           Usa nome-ficheiro como ficheiro de referência para gerar o ficheiro de símbolos que é
           integrado no próprio pacote.

       -O[filename]
           Escreve o ficheiro de símbolos gerado na saída standard ou em filename se
           especificado, em vez de debian/tmp/DEBIAN/symbols (ou package-build-dir/DEBIAN/symbols
           se -P foi usado). Se filename é pré-existente, o seu conteúdo é usado como base para o
           ficheiro de símbolos gerado. Você pode usar esta funcionalidade para actualizar um
           ficheiro de símbolos para que corresponda à nova versão do autor da sua biblioteca.

       -t  Escreve o ficheiro de símbolos em modo de modelo em vez do formato compatível com
           deb-symbols(5). A principal diferença é que em modo de modelo os nomes dos símbolos e
           as etiquetas são escritos na sua forma original ao contrário dos nomes de símbolos
           pós-processados com as etiquetas despidas do modo de compatibilidade. Mais ainda,
           alguns símbolos podem ser omitidos quando se escreve um ficheiro deb-symbols(5)
           standard (de acordo com as regras de processamento de etiquetas) enquanto que todos os
           símbolos são sempre escritos no ficheiro modelo de símbolos.

       -c[0-4]
           Define as verificações a fazer quando se compara o ficheiro de símbolos gerado com o
           ficheiro modelo usado como ponto de partida. Por predefinição o nível é 1. Aumentar os
           níveis faz mais verificações e inclui todas as verificações de baixo nível.

           Nível 0
               Nunca falha.

           Nível 1
               Falha se alguns símbolos tiverem desaparecido.

           Nível 2
               Falha se alguns novo símbolos tiverem sido introduzidos.

           Nível 3
               Falha se algumas bibliotecas tiverem desaparecido.

           Nível 4
               Falha se algumas bibliotecas tiverem sido introduzidos.

           Este valor pode ser sobreposto pela variável de ambiente DPKG_GENSYMBOLS_CHECK_LEVEL.

       -q  Mantêm-se calado e nunca gera um diff entre o ficheiro de símbolos gerados e o
           ficheiro modelo usando como ponto de arranque nem mostra nenhuns avisos sobre
           bibliotecas novas/perdidas nem símbolos novos/perdidos. Esta opção apenas desactiva os
           resultados informativos mas não os próprios  testes (veja a opção -c).

       -aarch
           Assume arch como arquitectura anfitriã quando processa ficheiros de símbolos. Use esta
           opção para gerar um ficheiro de símbolos ou a diferença para qualquer arquitectura
           desde que os seus binários já estejam disponíveis.

       -d  Activa o modo de depuração. São mostradas numerosas mensagens para explicar o que o
           dpkg-gensymbols faz.

       -V  Activa modo detalhado. O ficheiro de símbolos gerado contém símbolos abandonados como
           comentários. Mais ainda, em modo de modelo, os símbolos de padrões são seguidos de
           comentários que listam símbolos reais que corresponderam ao padrão.

       -?, --help
           Mostra a mensagem de utilização e termina.

       --version
           Mostra a versão e termina.

AMBIENTE

       DPKG_GENSYMBOLS_CHECK_LEVEL
           Sobrepõe o nível de verificação do comando, mesmo se o argumento -c de linha de
           comandos tenha sido dado (note que isto vai contra a convenção comum de argumentos de
           linha de comandos a ter a precedência sobre as variáveis de ambiente).

       DPKG_COLORS
           Define o modo de cor (desde dpkg 1.18.5). Os valores actualmente aceites são: auto
           (predefinido), always e never.

       DPKG_NLS
           Se definida, será usada para decidir se deve activar o Suporte a Linguagem Nativa.
           Também como conhecido como suporte de internacionalização (ou i18n) (desde dpkg
           1.19.0). Os valores aceites são 0 e 1 (predefinição).

VEJA TAMBÉM

       <https://people.redhat.com/drepper/symbol-versioning>,
       <https://people.redhat.com/drepper/goodpractice.pdf>,
       <https://people.redhat.com/drepper/dsohowto.pdf>, deb-src-symbol(5), deb-symbols(5),
       dpkg-shlibdeps(1).

TRADUÇÃO

       Américo Monteiro

       Se encontrar algum erro na tradução deste documento, por favor comunique para Américo
       Monteiro <a_monteiro@gmx.com>.