Provided by: dpkg-dev_1.21.9ubuntu1_all 
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 destrutores (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 ex. "ng_mystack_new@Base" não o farão. 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
desmutilá-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>.