deb-src-symbols - ficheiro modelo de biblioteca partilhada extensiva de Debian
debian/package.symbols.arch,
debian/symbols.arch,
debian/package.symbols,
debian/symbols
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 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.
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.
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.
- 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.
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.
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
deb-symbols(5),
dpkg-shlibdeps(1),
dpkg-gensymbols(1).
Américo Monteiro
Se encontrar algum erro na tradução deste documento, por favor
comunique para Américo Monteiro <
[email protected]>.