deb-src-symbols(5) dpkg suite deb-src-symbols(5)
NOME
deb-src-symbols - ficheiro modelo de biblioteca partilhada extensiva de
Debian
SINOPSE
debian/package.symbols.arch, debian/symbols.arch,
debian/package.symbols, debian/symbols
DESCRIÇÃO
Os modelos de ficheiros symbol são enviados em pacotes fonte Debian, e
o seu formato é um superconjunto dos ficheiros symbols enviados em
pacotes binários, veja deb-symbols(5).
Comentários
Comentários são suportados em modelos de ficheiros de símbolos:
Qualquer linha com um ‘#’ no primeiro caractere é um comentário excepto
se começar com ‘#include’ (veja secção Usando inclusões). As linhas que
começam com ‘#MISSING:’ são comentários especiais que documentam
símbolos que desapareceram.
Usando substituição de #PACKAGE#
Em alguns casos raros, o nome da biblioteca varia entre arquitecturas.
Para evitar dificultar o nome do pacote no ficheiro de símbolos, você
pode usar o marcador #PACKAGE#. Será substituído pelo nome real do
pacote durante a instalação dos ficheiros de símbolos. Contrariamente
ao marcador #MINVER#, #PACKAGE# nunca irá aparecer num ficheiro de
símbolos dentro de um pacote binário.
Usar etiquetas símbolo
Etiquetagem de símbolos é útil para marcar símbolos que são especiais
em algum modo. Qualquer símbolo pode ter um número arbitrário de
etiquetas associadas com ele. Enquanto todas as etiquetas são
analisadas e guardadas, apenas algumas delas são compreendidas pelo
dpkg-gensymbols e despoletam manuseamento especial dos símbolos. Veja a
sub-secção Etiquetas símbolo standard para referência a estas
etiquetas.
A especificação de etiqueta vem logo antes do nome do símbolo (não é
permitido nenhum espaço em branco entre eles). Começa sempre com um
abre-parêntesis (, termina com um fecha-parêntesis ) e tem de conter
pelo menos uma etiqueta. Múltiplas etiquetas são separadas pelo
caractere |. Cada etiqueta pode opcionalmente ter um valor que é
separado do nome da etiqueta com um caractere =. Os nomes de etiquetas
e valores podem ser strings arbitrárias excepto que não podem conter
nenhum dos caracteres especiais ) | =. Nomes de símbolos que seguem a
especificação das etiquetas podem opcionalmente ser citados com os
caracteres ' ou " para permitir espaços em brando neles. No entanto, se
não existirem etiquetas especificadas para o símbolo, as citações são
tratadas como parte do nome do símbolo o qual continua até ao primeiro
espaço.
(tag1=i am marked|tag name with space)"tagged quoted symbol"@Base 1.0
(optional)tagged_unquoted_symbol@Base 1.0 1
untagged_symbol@Base 1.0
O primeiro símbolo no exemplo é chamado tagged quoted symbol e tem duas
etiquetas: tag1 com valor i am marked e tag name with space que não tem
nenhum valor. O segundo símbolo chamado tagged_unquoted_symbol é apenas
etiquetado com a etiqueta chamada optional. O último símbolo é um
exemplo do símbolo normal não etiquetado.
Como as etiquetas de símbolos são uma extensão do formato deb-
symbols(5), elas apenas fazer parte dos ficheiros de símbolos usados em
pacotes fonte (esses ficheiros devem depois ser vistos como modelos
usados para compilar os ficheiros de símbolos que são embebidos em
pacotes binários. Quando dpkg-gensymbols é chamado sem a opção -t, irá
escrever ficheiros de símbolos compatíveis com o formato deb-
symbols(5): processa totalmente os símbolos de acordo com os
requerimentos das suas etiquetas standard e remove todas as etiquetas
do resultado. Pelo contrário, em modo de modelo (-t) todos os símbolos
e suas etiquetas (tanto standard como desconhecidas) são mantidas no
resultado e são escritas no seu formato original como foram carregadas.
Etiquetas símbolo standard
optional
Um símbolo marcado como opcional pode desaparecer da biblioteca a
qualquer altura e isso nunca fará o dpkg-gensymbols falhar. No
entanto, símbolos opcionais desaparecidos irão continuamente
aparecer como MISSING no diff em cada nova revisão do pacote. Este
comportamento serve como lembrete para o maintainer que tal símbolo
precisa de ser removido do ficheiro de símbolos ou re-adicionado à
biblioteca. Quando o símbolo opcional, que foi anteriormente
declarado como MISSING, subitamente reaparece na próxima revisão,
será actualizado de volta para o estado de "existente" com a sua
versão mínima inalterada.
Esta etiqueta é útil para símbolos que são privados e para o seu
desaparecimento não causar a rutura da ABI. Por exemplo, a maioria
das instalações de modelos C++ caiem nesta categoria. Como qualquer
outra etiqueta, esta também pode ter uma valor arbitrário: isso
podia ser usado para indicar porquê o símbolo é considerado
opcional.
arch=architecture-list
arch-bits=architecture-bits
arch-endian=architecture-endianness
Estas bandeiras permitem-nos restringir o conjunto de arquitecturas
onde o símbolo é suposto existir. As bandeiras arch-bits e arch-
endian são suportadas desde dpkg 1.18.0. Quando a lista de símbolos
é actualizada com os símbolos descobertos na biblioteca, todos os
símbolos específicos de arquitectura que não dizem respeito à
arquitectura da máquina actual são tratados como se não existissem.
Se um símbolo específico-de-arquitectura que corresponda à
arquitectura da máquina anfitriã atual não existir na biblioteca,
aplica-se os procedimentos normais para símbolos em falta e isso
pode causar que dpkg-gensymbols falhe. Por outro lado, se o símbolo
específico-de arquitectura for encontrado onde não era suporto
existir (porque a arquitectura da máquina actual não está listada
na etiqueta ou porque não corresponde ao endianness e bits), é
tornado neutro em arquitectura (isto é, as etiquetas arch, arch-
bits e arch-endian são largadas e o símbolo irá aparecer no diff
devido a esta alteração), mas não é considerado como novo.
Quando opera no modo predefinido não-modelo, entre os símbolos
específicos de arquitectura, apenas aqueles que correspondem à
arquitectura da máquina anfitriã actual são escritos no ficheiro de
símbolos. Pelo contrário, quando se opera em modo de modelo, todos
os símbolos específicos-de-arquitectura (incluindo aqueles de
arquitecturas alienígenas) são sempre escritos no ficheiro de
símbolos.
O formato de architecture-list é o mesmo que o usado no campo
Build-Depends de debian/control (excepto nos parêntesis rectos []).
Por exemplo, o primeiro símbolo da lista em baixo será considerado
apenas nas arquitecturas alpha, any-amd64 e ia64, o segundo apenas
em arquitecturas de linux, enquanto o terceiro em todas excepto em
armel.
(arch=alpha any-amd64 ia64)64bit_specific_symbol@Base 1.0
(arch=linux-any)linux_specific_symbol@Base 1.0
(arch=!armel)symbol_armel_does_not_have@Base 1.0
O architecture-bits ou é 32 ou é 64.
(arch-bits=32)32bit_specific_symbol@Base 1.0
(arch-bits=64)64bit_specific_symbol@Base 1.0
A arquitectura-classe-endian é ou little ou big.
(arch-endian=little)little_endian_specific_symbol@Base 1.0
(arch-endian=big)big_endian_specific_symbol@Base 1.0
Múltiplas restrições podem ser ligadas em corrente.
(arch-bits=32|arch-endian=little)32bit_le_symbol@Base 1.0
allow-internal
O dpkg-gensymbols tem uma lista interna de símbolos que não devem
aparecer em ficheiros de símbolos pois eles são geralmente apenas
efeitos secundários de detalhes de implementação da ferramenta-
cadeia (desde dpkg 1.20.1). Se por alguma razão, você querer
realmente que um desses símbolos seja incluído no ficheiro de
símbolos, você deve etiquetar o símbolo com allow-internal. Pode
ser necessário para algumas ferramentas-cadeia de baixo nível como
“libgcc”.
ignore-blacklist
Um alias descontinuado para allow-internal (desde dpkg 1.20.1,
suportado desde dpkg 1.15.3).
c++ indica o padrão de símbolos c++ . Veja a sub-secção Usar padrões de
símbolos em baixo.
symver
Indica o padrão de símbolos symver (versão de símbolo). Veja a
sub-secção Usar padrões de símbolos em baixo.
regex
Indica o padrão de símbolos regex. Veja a sub-secção Usar padrões
de símbolos em baixo.
Usar padrões de símbolos
Ao contrário de uma especificação de símbolo standard, um padrão pode
cobrir vários símbolos reais da biblioteca. dpkg-gensymbols irá tentar
corresponder cada padrão com cada símbolo real que não tem uma
contrapartida de símbolo específica definida no ficheiro de símbolos.
Sempre que o primeiro padrão de correspondência é encontrado, todas as
suas etiquetas e propriedades serão usadas como a especificação base do
símbolo. Se nenhum dos padrões corresponder, o símbolo irá ser
considerado como novo.
Um padrão é considerado perdido se não corresponder a nenhum símbolo da
biblioteca. Por predefinição isto irá despoletar que dpkg-gensymbols
falhe sob -c1 ou nível mais alto. No entanto, se a falha for
indesejável, o padrão pode ser marcado com a etiqueta optional. Então
se o padrão não corresponder a nada, irá apenas aparecer no diff como
MISSING. Além disso, como qualquer símbolo, o padrão pode ser limitado
a arquitecturas específicas com a etiqueta arch. Por favor consulte a
sub.secção Etiquetas símbolo standard em cima para mais informação.
Padrões são uma extensão do formato deb-symbols(5) por isso eles são
apenas válidos em modelos de ficheiros de símbolos. A sintaxe de
especificação de padrões não é em nada diferente daquela de um símbolo
específico. No entanto, a parte da especificação com o nome do símbolo
serve como uma expressão para ser correspondida contra name@version do
símbolo real. De modo a se distinguir entre tipos diferentes de
padrões, um padrão será tipicamente etiquetado com uma etiqueta
especial.
Até ao momento, dpkg-gensymbols suporta três tipos de padrão básicos:
c++ Este padrão é denotado pela etiqueta c++. Corresponde apenas a
símbolos C++ pelo seu nome desmutilado de símbolo (como emitido
pelo utilitário c++filt(1)). Este padrão é muito jeitoso para
corresponder a símbolos cujos nomes mutilados podem variar por
entre diferentes arquitecturas enquanto que os seus nomes
desmutilados permanecem iguais. Um grupo de tais símbolos é non-
virtual thunks que têm embebidos desvios específicos de
arquitectura nos seus nomes mutilados. Uma instância comum deste
caso é um destruidor virtual que sob herança diamante precisa de um
símbolo thunk não-virtual. Por exemplo, mesmo que
_ZThn8_N3NSB6ClassDD1Ev@Base em arquitecturas de 32bit
provavelmente seja _ZThn16_N3NSB6ClassDD1Ev@Base em 64bit, pode
ser correspondido com um único padrão c++:
libdummy.so.1 libdummy1 #MINVER#
[...]
(c++)"non-virtual thunk to NSB::ClassD::~ClassD()@Base" 1.0
[...]
O nome desmembrado em cima pode ser obtido ao executar o seguinte
comando:
$ echo '_ZThn8_N3NSB6ClassDD1Ev@Base' | c++filt
Por favor note que enquanto o nome mutilado é único na biblioteca
por definição, isto não é necessariamente verdade para nomes
não-mutilados. Um par de símbolos reais distintos podem ter o mesmo
nome mutilado. Por exemplo, esse é o caso com símbolos thunk
não.virtuais em configurações de herança complexa ou com a maioria
dos construtores e destruidores (pois o g++ tipicamente gera dois
símbolos reais para eles). No entanto, como estas colisões
acontecem no nível de ABI, não devem degradar a qualidade do
ficheiro de símbolos.
symver
Este padrão é denotado pela etiqueta symver. Bibliotecas bem
mantidas têm os símbolos organizados pela versão, onde cada versão
corresponde à versão do autor de onde o símbolo foi obtido. Se for
esse o caso, você pode usar um padrão symver para corresponder a
qualquer símbolo associado à versão específica. Por exemplo:
libc.so.6 libc6 #MINVER#
(symver)GLIBC_2.0 2.0
[...]
(symver)GLIBC_2.7 2.7
access@GLIBC_2.0 2.2
Todos os símbolos associados com versões GLIBC_2.0 e GLIBC_2.7 irão
para versões mínimas de 2.0 e 2.7 respetivamente com a excepção do
símbolo access@GLIBC_2.0. O último irá tornar-se uma dependência
mínima em libc6 versão 2.2 apenas de estar no escopo do padrão
"(symver)GLIBC_2.0" porque símbolos específicos tomam precedência
sobre padrões.
Por favor note que apesar de os padrões de wildcard ao estilo
antigo (denotados por "*@version" no campo do nome do símbolo)
ainda serem suportados, estes foram descontinuados pela nova
sintaxe "(symver|optional)version". Por exemplo, "*@GLIBC_2.0 2.0"
deve ser escrito como "(symver|optional)GLIBC_2.0 2.0" se for
necessário o mesmo comportamento.
regex
Padrões de expressões regulares são denotadas pela etiqueta regex.
Eles correspondem pelas expressões regulares perl especificadas no
campo do nome do símbolo. Uma expressão regular corresponde tal
como está, assim não se esqueça de a arrancar com o caractere ^ ou
poderá corresponder a qualquer parte da string name@version do
símbolo real. Por exemplo:
libdummy.so.1 libdummy1 #MINVER#
(regex)"^mystack_.*@Base$" 1.0
(regex|optional)"private" 1.0
Símbolos como "mystack_new@Base", "mystack_push@Base",
"mystack_pop@Base" etc, irão corresponder ao primeiro padrão,
enquanto "ng_mystack_new@Base" não o fará. O segundo padrão irá
corresponder a todos os símbolos que tenham a string "private" nos
seus nomes e as correspondências irão herdar a etiqueta optional a
partir do padrão.
Os padrões básicos listados em cima podem ser combinados onde isso
fizer sentido, nesse caso, eles são processados pela ordem em que as
etiquetas estão especificadas. Por exemplo, ambos:
(c++|regex)"^NSA::ClassA::Private::privmethod\d\(int\)@Base" 1.0
(regex|c++)N3NSA6ClassA7Private11privmethod\dEi@Base 1.0
irá corresponder aos símbolos
"_ZN3NSA6ClassA7Private11privmethod1Ei@Base" e
"_ZN3NSA6ClassA7Private11privmethod2Ei@Base". Quando coincide o
primeiro padrão, o símbolo cru é primeiro desmutilado como símbolo C++,
depois o nome desmutilado é coincidido com a expressão regular. Por
outro lado, quando coincide o segundo padrão, a expressão regular é
coincidida com o nome cru do símbolo, depois os símbolo é testado se é
um C++ ao tentar desmutila-lo. Uma falha de qualquer padrão básico irá
resultar na falha de todo o padrão. Por isso, por exemplo,
"__N3NSA6ClassA7Private11privmethod\dEi@Base" não irá corresponder a
nenhum dos padrões porque não é um símbolo C++ válido.
Em geral, todos os padrões são divididos em dois grupos: aliases (basic
c++ e symver) e padrões genéricos (regex, todas as combinações de
múltiplos padrões básicos). A correspondência de padrões básicos
baseados-em-alias é rápida (O(1)) enquanto que padrões genéricos são
O(N) (N - contagem de padrão genérico) para cada símbolo. Assim, é
recomendado não sobre-utilizar padrões genéricos.
Quando múltiplos padrões correspondem ao mesmo símbolo real, os aliases
(primeiro c++, depois symver) são preferidos sobre padrões genéricos.
Padrões genéricos são correspondidos pela ordem que são encontrados no
modelo de ficheiro de símbolos até ao primeiro sucesso. Por favor note,
no entanto, esse reordenar manual das entradas no ficheiro modelo não é
recomendado porque dpkg-gensymbols gera diffs baseados na ordem
alfanumérica dos seus nomes.
Usando inclusões
Quando o conjunto de símbolos exportados difere entre arquitecturas,
pode tornar-se ineficiente usar um único ficheiro de símbolos. Nesses
casos, uma directiva de inclusão pode provar ser útil de várias
maneiras:
• Você pode factorizar a parte comum em algum ficheiro externo e
incluir esse ficheiro no seu ficheiro package.symbols.arch ao usar
uma directiva de inclusão como esta:
#include "I<packages>.symbols.common"
• A directiva de inclusão pode também ser etiquetada como qualquer
símbolo:
(tag|...|tagN)#include "file-to-include"
Como resultado, todos os símbolos incluídos de file-to-include
serão considerados para serem etiquetados com tag ... tagN por
predefinição. Você pode usar esta funcionalidade para criar um
ficheiro package.symbols comum que inclui ficheiros de símbolos
específicos de arquitectura:
common_symbol1@Base 1.0
(arch=amd64 ia64 alpha)#include "package.symbols.64bit"
(arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit"
common_symbol2@Base 1.0
Os ficheiros de símbolos são lidos linha a linha, e as directivas de
inclusão são processadas assim que são encontradas. Isto significa que
o conteúdo do ficheiro incluído pode sobrepor qualquer conteúdo que
apareceu antes da directiva de inclusão e que qualquer conteúdo após a
directiva pode sobrepor qualquer coisa contida no ficheiro incluído.
Qualquer símbolo (ou mesmo outra directiva #include) no ficheiro
incluído pode especificar etiquetas adicionais ou sobrepor valores das
etiquetas herdadas e a sua especificação de etiqueta. Contudo, não
existe maneira do símbolo remover qualquer das etiquetas herdadas.
Um ficheiro incluído pode repetir a linha de cabeçalho que contém o
SONAME da biblioteca. Nesse caso, sobrepõe qualquer linha de cabeçalho
lida anteriormente. No entanto, geralmente é melhor duplicar as linhas
de cabeçalho. Um modo de fazer isto é o seguinte:
#include "libsomething1.symbols.common"
arch_specific_symbol@Base 1.0
VEJA TAMBÉM
deb-symbols(5), dpkg-shlibdeps(1), dpkg-gensymbols(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>.
1.21.22 2023-05-11 deb-src-symbols(5)
Generated by dwww version 1.15 on Mon Jul 1 05:23:10 CEST 2024.