1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
|
*****************************************************
* GENERATED FILE, DO NOT EDIT *
* THIS IS NO SOURCE FILE, BUT RESULT OF COMPILATION *
*****************************************************
This file was generated by po4a(7). Do not store it (in VCS, for example),
but store the PO file used as source file by po4a-translate.
In fact, consider this as a binary, and the PO file as a regular .c file:
If the PO get lost, keeping this translation up-to-date will be harder.
=encoding UTF-8
=head1 NOME
deb-src-symbols - ficheiro modelo de biblioteca partilhada extensiva de Debian
=head1 RESUMO
B<debian/>I<package>B<.symbols.>I<arch>, B<debian/symbols.>I<arch>, B<debian/>I<package>B<.symbols>, B<debian/symbols>
=head1 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 L<deb-symbols(5)>.
=head2 Comentários
Comments are supported in template symbol files. Any line with ‘#’ as the first character is a comment except if it starts with ‘#include’ (see section L</Using includes>). Lines starting with ‘#MISSING:’ are special comments documenting symbols that have disappeared.
=head2 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 I<#PACKAGE#>. Será substituído pelo nome real do pacote durante a instalação dos ficheiros de símbolos. Contrariamente ao marcador I<#MINVER#>, I<#PACKAGE#> nunca irá aparecer num ficheiro de símbolos dentro de um pacote binário.
=head2 Usar etiquetas símbolo
Symbol tagging is useful for marking symbols that are special in some way. Any symbol can have an arbitrary number of tags associated with it. While all tags are parsed and stored, only some of them are understood by B<dpkg-gensymbols> and trigger special handling of the symbols. See subsection L</Standard symbol tags> for reference of these tags.
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 B<(>, termina com um fecha-parêntesis B<)> e tem de conter pelo menos uma etiqueta. Múltiplas etiquetas são separadas pelo caractere B<|>. Cada etiqueta pode opcionalmente ter um valor que é separado do nome da etiqueta com um caractere B<=>. Os nomes de etiquetas e valores podem ser strings arbitrárias excepto que não podem conter nenhum dos caracteres especiais B<)> B<|> B<=>. Nomes de símbolos que seguem a especificação das etiquetas podem opcionalmente ser citados com os caracteres B<'> ou B<"> 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 I<tagged quoted symbol> e tem duas etiquetas: I<tag1> com valor I<i am marked> e I<tag name with space> que não tem nenhum valor. O segundo símbolo chamado I<tagged_unquoted_symbol> é apenas etiquetado com a etiqueta chamada I<optional>. O último símbolo é um exemplo do símbolo normal não etiquetado.
Since symbol tags are an extension of the L<deb-symbols(5)> format, they can only be part of the symbols files used in source packages (those files should then be seen as templates used to build the symbols files that are embedded in binary packages). When B<dpkg-gensymbols> is called without the B<-t> option, it will output symbols files compatible to the L<deb-symbols(5)> format: it fully processes symbols according to the requirements of their standard tags and strips all tags from the output. On the contrary, in template mode (B<-t>) all symbols and their tags (both standard and unknown ones) are kept in the output and are written in their original form as they were loaded.
=head2 Etiquetas símbolo standard
=over
=item B<optional>
Um símbolo marcado como opcional pode desaparecer da biblioteca a qualquer altura e isso nunca fará o B<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.
=item B<arch=>I<architecture-list>
=item B<arch-bits=>I<architecture-bits>
=item B<arch-endian=>I<architecture-endianness>
Estas bandeiras permitem-nos restringir o conjunto de arquitecturas onde o símbolo é suposto existir. As bandeiras B<arch-bits> e B<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 B<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 I<architecture-list> é o mesmo que o usado no campo B<Build-Depends> de I<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 I<architecture-bits> ou é B<32> ou é B<64>.
(arch-bits=32)32bit_specific_symbol@Base 1.0
(arch-bits=64)64bit_specific_symbol@Base 1.0
A I<arquitectura-classe-endian> é ou B<little> ou B<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
=item B<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 B<allow-internal>. Pode ser necessário para algumas ferramentas-cadeia de baixo nível como “libgcc”.
=item B<ignore-blacklist>
Um alias descontinuado para B<allow-internal> (desde dpkg 1.20.1, suportado desde dpkg 1.15.3).
=item B<c++>
Denotes I<c++> symbol pattern. See L</Using symbol patterns> subsection below.
=item B<symver>
Denotes I<symver> (symbol version) symbol pattern. See L</Using symbol patterns> subsection below.
=item B<regex>
Denotes I<regex> symbol pattern. See L</Using symbol patterns> subsection below.
=back
=head2 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. B<dpkg-gensymbols> irá tentar corresponder cada padrão com cada símbolo real que I<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.
A pattern is considered lost if it does not match any symbol in the library. By default this will trigger a B<dpkg-gensymbols> failure under B<-c1> or higher level. However, if the failure is undesired, the pattern may be marked with the I<optional> tag. Then if the pattern does not match anything, it will only appear in the diff as MISSING. Moreover, like any symbol, the pattern may be limited to the specific architectures with the I<arch> tag. Please refer to L</Standard symbol tags> subsection above for more information.
Patterns are an extension of the L<deb-symbols(5)> format hence they are only valid in symbol file templates. Pattern specification syntax is not any different from the one of a specific symbol. However, symbol name part of the specification serves as an expression to be matched against I<name@version> of the real symbol. In order to distinguish among different pattern types, a pattern will typically be tagged with a special tag.
Até ao momento, B<dpkg-gensymbols> suporta três tipos de padrão básicos:
=over
=item B<c++>
This pattern is denoted by the I<c++> tag. It matches only C++ symbols by their demangled symbol name (as emitted by L<c++filt(1)> utility). This pattern is very handy for matching symbols which mangled names might vary across different architectures while their demangled names remain the same. One group of such symbols is I<non-virtual thunks> which have architecture specific offsets embedded in their mangled names. A common instance of this case is a virtual destructor which under diamond inheritance needs a non-virtual thunk symbol. For example, even if _ZThn8_N3NSB6ClassDD1Ev@Base on 32-bit architectures will probably be _ZThn16_N3NSB6ClassDD1Ev@Base on 64-bit ones, it can be matched with a single I<c++> pattern:
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.
=item B<symver>
Este padrão é denotado pela etiqueta I<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 I<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.
=item B<regex>
Padrões de expressões regulares são denotadas pela etiqueta I<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 I<^> ou poderá corresponder a qualquer parte da string I<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 I<optional> a partir do padrão.
=back
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 I<c++> e I<symver>) e padrões genéricos (I<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 I<c++>, depois I<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 B<dpkg-gensymbols> gera diffs baseados na ordem alfanumérica dos seus nomes.
=head2 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:
=over
=item *
Você pode factorizar a parte comum em algum ficheiro externo e incluir esse ficheiro no seu ficheiro I<package>.symbols.I<arch> ao usar uma directiva de inclusão como esta:
#include "I<packages>.symbols.common"
=item *
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 I<file-to-include> serão considerados para serem etiquetados com I<tag> ... I<tagN> por predefinição. Você pode usar esta funcionalidade para criar um ficheiro I<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.64-bit"
(arch=!amd64 !ia64 !alpha)#include "package.symbols.32-bit"
common_symbol2@Base 1.0
=back
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
=head1 VEJA TAMBÉM
L<deb-symbols(5)>, L<dpkg-shlibdeps(1)>, L<dpkg-gensymbols(1)>.
=head1 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>.
|
