Provided by: dpkg-dev_1.22.18ubuntu3_all 
NOME
deb-src-symbols - ficheiro modelo de biblioteca partilhada extensiva de Debian
RESUMO
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.
The format of architecture-list is the same as the one used in the Build-Depends field of
debian/control (except the enclosing square brackets []). For example, the first symbol from the
list below will be considered only on arm64, any-amd64 and riscv64 architectures, the second only on
linux architectures, while the third one anywhere except on armel.
(arch=arm64 any-amd64 riscv64)arch_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-bits=64)#include "package.symbols.64-bit"
(arch-bits=32)#include "package.symbols.32-bit"
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.22.18 2025-04-28 deb-src-symbols(5)