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
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
|
*****************************************************
* 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
dpkg-gensymbols - gera ficheiros symbols (informação de dependência de
biblioteca partilhada)
=head1 SINOPSE
B<dpkg-gensymbols> [I<option>...]
=head1 DESCRIÇÃO
B<dpkg-gensymbols> sonda uma árvore de compilação temporária (debian/tmp por
predefinição) à procura de bibliotecas e gera um ficheiro I<symbols> a
descrevê-los. Este ficheiro, se não vazio, é depois instalado no
sub-directório DEBIAN da árvore de compilação para que seja incluído na
informação de controle do pacote.
Quando gera esses ficheiros, usa como entrada alguns ficheiros de símbolos
disponibilizados pelo maintainer. Procura os seguintes ficheiros (e usa o
primeiro que encontra):
=over
=item *
debian/I<package>.symbols.I<arch>
=item *
debian/symbols.I<arch>
=item *
debian/I<package>.symbols
=item *
debian/symbols
=back
O principal interesse desse ficheiros é disponibilizar a versão mínima
associada a cada símbolo fornecido pelas bibliotecas. Geralmente isso
corresponde à primeira versão do pacote que forneceu o símbolo, mas pode ser
incrementada pelo maintainer se o ABI do símbolo é extensível sem se quebrar
a compatibilidade com versões anteriores. É da responsabilidade do
maintainer manter esses ficheiros actualizados e precisos, mas o
B<dpkg-gensymbols> ajuda com isso.
Quando os ficheiros de símbolos gerados diferem daqueles fornecidos pelo
maintainer, B<dpkg-gensymbols> irá escrever um diff entre as duas
versões. Mais ainda, se a diferença for muito significante, irá mesmo falhar
(você pode personalizar quanta diferença pode ser tolerada, veja a opção
B<-c>).
=head1 MANTENDO FICHEIROS DE SÍMBOLOS
O formato de intercâmbio base do ficheiro de símbolos é descrito em
B<deb-symbols>(5), o qual é usado pelos ficheiros symbols incluídos em
pacotes binários. Estes são gerados a partir de ficheiros se símbolos modelo
com um formato baseado no anterior, descrito em B<deb-src-symbols>(5) e
incluído em pacotes fonte.
Os ficheiros de símbolos são apenas úteis se refletirem a evolução do pacote
entre vários lançamentos. Assim o maintainer tem de os actualizar todas as
vezes que é adicionado um novo símbolo para que a sua versão mínima
associada corresponda à realidade.
Os diffs contidos nos logs de compilação podem ser usados com ponto de
partida, mas o maintainer, adicionalmente, tem de certificar que o
comportamento desses símbolos não alterou num modo que faça com que tudo o
que usa esses símbolos e em link para a nova versão, deixem de funcionar com
a versão antiga.
Na maioria dos casos, o diff aplica-se directamente ao ficheiro
debian/I<package>.symbols. Dito isso, geralmente são necessários mais
ajustes: é recomendado, por exemplo, soltar a revisão Debian da versão
mínima para que backports com um número de versão inferior mas a mesma
versão de autor consigam ainda satisfazer as dependências geradas. Se uma
revisão Debian não pode ser largada porque o símbolo foi realmente
adicionado pela alteração específica de Debian, então deve-se acrescentar um
sufixo à versão com ‘B<~>’.
Antes de aplicar qualquer patch ao ficheiro symbols, o maintainer deve
re-verificar que esta é saudável. Não é suposto símbolos públicos
desaparecerem, assim a patch deve idealmente apenas adicionar novas linhas.
Note que você pode meter comentários em ficheiros de símbolos.
Não se esqueça de verificar se versões antigas de símbolos precisam de ser
aumentadas. Não há maneira de B<dpkg-gensymbols> poder avisar sobre
isto. Aplica o diff às cegas ou assumir que não há nada para mudar se não
existir um diff, sem verificar por tais mudanças, pode levar a pacotes com
dependências soltas, que afirmam poder trabalhar com pacotes mais antigos
com que já não podem trabalhar. Isto irá introduzir dificuldades de
encontrar bugs com actualizações (parciais).
=head2 Boa gestão de biblioteca
Uma biblioteca bem mantida tem as seguintes características:
=over
=item *
A sua API é estável (símbolos públicos nunca são largados, apenas símbolos
públicos novos são adicionados) e alterações em modos incompatíveis sempre
apenas quando o SONAME muda;
=item *
idealmente, usa a identificação da versão do símbolo para obter estabilidade
da ABI apesar de alterações internas e extensão API;
=item *
não exporta símbolos privados (tais símbolos podem ser etiquetados de
opcionais como meio de contornar).
=back
Enquanto se mantém o ficheiro symbols, é fácil percebermos o aparecimento e
desaparecimento de símbolos. Mas é mais difícil apanhar alterações de API e
ABI incompatíveis. Assim o maintainer deve ler com atenção o registo de
alterações do autor procurando casos onde as regras da boa gestão de
bibliotecas foram quebradas. Se forem descobertos potenciais problemas, o
autor original deve ser notificado pois uma correcção no autor é sempre
melhor que um contorno especifico em Debian.
=head1 OPÇÕES
=over
=item B<-P>I<package-build-dir>
Sonda I<package-build-dir> em vez de debian/tmp.
=item B<-p>I<package>
Define o nome do pacote. Requerido se mais do que um pacote binário estiver
listado em debian/control (ou se não existir o ficheiro debian/control).
=item B<-v>I<version>
Define a versão do pacote. Usa por predefinição a versão extraída de
debian/changelog. Requerido se chamado fora de uma árvore de pacote fonte.
=item B<-e>I<library-file>
Apenas analisa bibliotecas explicitas em vez de procurar todas as
bibliotecas públicas. Você pode usar padrões de shell usadas para expansões
de nome de caminho (veja o manual B<File::Glob>(3perl) para detalhes) em
I<library-file> para corresponder a múltiplas bibliotecas com um único
argumento (caso contrário você precisa de múltiplos B<-e>).
=item B<-l>I<directory>
Precede I<directory> à lista de directórios a pesquisar por bibliotecas
partilhadas privadas (desde dpkg 1.19.1). Esta opção pode ser usada várias
vezes.
B<Nota:> Use esta opção em vez de definir B<LD_LIBRARY_PATH>, pois essa
variável de ambiente é usado para controlar o vinculador de
tempo-de-execução e abusar dela para definir caminhos de bibliotecas
partilhadas durante a compilação pode ser problemático quando, por exemplo,
se faz compilações cruzadas.
=item B<-I>I<filename>
Usa I<nome-ficheiro> como ficheiro de referência para gerar o ficheiro de
símbolos que é integrado no próprio pacote.
=item B<-O>[I<filename>]
Escreve o ficheiro de símbolos gerado na saída standard ou em I<filename> se
especificado, em vez de B<debian/tmp/DEBIAN/symbols> (ou
I<package-build-dir>B</DEBIAN/symbols> se B<-P> foi usado). Se I<filename> é
pré-existente, o seu conteúdo é usado como base para o ficheiro de símbolos
gerado. Você pode usar esta funcionalidade para actualizar um ficheiro de
símbolos para que corresponda à nova versão do autor da sua biblioteca.
=item B<-t>
Escreve o ficheiro de símbolos em modo de modelo em vez do formato
compatível com B<deb-symbols>(5). A principal diferença é que em modo de
modelo os nomes dos símbolos e as etiquetas são escritos na sua forma
original ao contrário dos nomes de símbolos pós-processados com as etiquetas
despidas do modo de compatibilidade. Mais ainda, alguns símbolos podem ser
omitidos quando se escreve um ficheiro B<deb-symbols>(5) standard (de acordo
com as regras de processamento de etiquetas) enquanto que todos os símbolos
são sempre escritos no ficheiro modelo de símbolos.
=item B<-c>I<[0-4]>
Define as verificações a fazer quando se compara o ficheiro de símbolos
gerado com o ficheiro modelo usado como ponto de partida. Por predefinição o
nível é 1. Aumentar os níveis faz mais verificações e inclui todas as
verificações de baixo nível. O nível 0 nunca falha. Nível 1 falha se alguns
símbolos tiverem desaparecido. Nível 2 falha se foram introduzidos alguns
símbolos novos. Nível 3 falha se algumas bibliotecas tiverem
desaparecido. Nível 4 falha se algumas bibliotecas foram introduzidas.
Este valor pode ser sobreposto pela variável de ambiente
B<DPKG_GENSYMBOLS_CHECK_LEVEL>.
=item B<-q>
Mantêm-se calado e nunca gera um diff entre o ficheiro de símbolos gerados e
o ficheiro modelo usando como ponto de arranque nem mostra nenhuns avisos
sobre bibliotecas novas/perdidas nem símbolos novos/perdidos. Esta opção
apenas desactiva os resultados informativos mas não os próprios testes
(veja a opção B<-c>).
=item B<-a>I<arch>
Assume I<arch> como arquitectura anfitriã quando processa ficheiros de
símbolos. Use esta opção para gerar um ficheiro de símbolos ou a diferença
para qualquer arquitectura desde que os seus binários já estejam
disponíveis.
=item B<-d>
Activa o modo de depuração. São mostradas numerosas mensagens para explicar
o que o B<dpkg-gensymbols> faz.
=item B<-V>
Activa modo detalhado. O ficheiro de símbolos gerado contém símbolos
abandonados como comentários. Mais ainda, em modo de modelo, os símbolos de
padrões são seguidos de comentários que listam símbolos reais que
corresponderam ao padrão.
=item B<-?>, B<--help>
Mostra a mensagem de utilização e termina.
=item B<--version>
Mostra a versão e termina.
=back
=head1 AMBIENTE
=over
=item B<DPKG_GENSYMBOLS_CHECK_LEVEL>
Sobrepõe o nível de verificação do comando, mesmo se o argumento B<-c> de
linha de comandos tenha sido dado (note que isto vai contra a convenção
comum de argumentos de linha de comandos a ter a precedência sobre as
variáveis de ambiente).
=item B<DPKG_COLORS>
Define o modo de cor (desde dpkg 1.18.5). Os valores actualmente aceites
são: B<auto> (predefinido), B<always> e B<never>.
=item B<DPKG_NLS>
Se definida, será usada para decidir se deve activar o Suporte a Linguagem
Nativa. Também como conhecido como suporte de internacionalização (ou i18n)
(desde dpkg 1.19.0). Os valores aceites são B<0> e B<1> (predefinição).
=back
=head1 VEJA TAMBÉM
L<https://people.redhat.com/drepper/symbol-versioning>,
L<https://people.redhat.com/drepper/goodpractice.pdf>,
L<https://people.redhat.com/drepper/dsohowto.pdf>, B<deb-src-symbol>(5),
B<deb-symbols>(5), B<dpkg-shlibdeps>(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>.
|
