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.
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.
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
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:
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.
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.
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.
#include "I<packages>.symbols.common"
(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
Se encontrar algum erro na tradução deste documento, por favor comunique para Américo Monteiro <a_monteiro@gmx.com>.