dpkg-gensymbols - gera ficheiros symbols (informação de
dependência de biblioteca partilhada)
dpkg-gensymbols [
option...]
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).
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).
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.
-
-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(3perl) 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.
- 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).
<
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).
Américo Monteiro
Se encontrar algum erro na tradução deste documento, por favor
comunique para Américo Monteiro <
[email protected]>.