.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "dpkg-gensymbols 1" .TH dpkg-gensymbols 1 2024-03-10 1.22.6 "dpkg suite" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NOME .IX Header "NOME" dpkg-gensymbols \- gera ficheiros symbols (informa\(,c\(~ao de depend\(^encia de biblioteca partilhada) .SH RESUMO .IX Header "RESUMO" \&\fBdpkg-gensymbols\fR [\fIoption\fR...] .SH DESCRI\(,C\(~AO .IX Header "DESCRI\(,C\(~AO" \&\fBdpkg-gensymbols\fR sonda uma \('arvore de compila\(,c\(~ao tempor\('aria (debian/tmp por predefini\(,c\(~ao) \(`a procura de bibliotecas e gera um ficheiro \fIsymbols\fR a descreve-los. Este ficheiro, se n\(~ao vazio, \('e depois instalado no sub\-direct\('orio DEBIAN da \('arvore de compila\(,c\(~ao para que seja inclu\('ido na informa\(,c\(~ao de controle do pacote. .PP Quando gera esses ficheiros, usa como entrada alguns ficheiros de s\('imbolos disponibilizados pelo maintainer. Procura os seguintes ficheiros (e usa o primeiro que encontra): .IP \(bu 4 debian/\fIpackage\fR.symbols.\fIarch\fR .IP \(bu 4 debian/symbols.\fIarch\fR .IP \(bu 4 debian/\fIpackage\fR.symbols .IP \(bu 4 debian/symbols .PP O principal interesse desse ficheiros \('e disponibilizar a vers\(~ao m\('inima associada a cada s\('imbolo fornecido pelas bibliotecas. Geralmente isso corresponde \(`a primeira vers\(~ao do pacote que forneceu o s\('imbolo, mas pode ser incrementada pelo maintainer se o ABI do s\('imbolo \('e extens\('ivel sem se quebrar a compatibilidade com vers\(~oes anteriores. \('E da responsabilidade do maintainer manter esses ficheiros actualizados e precisos, mas o \fBdpkg-gensymbols\fR ajuda com isso. .PP Quando os ficheiros de s\('imbolos gerados diferem daqueles fornecidos pelo maintainer, \fBdpkg-gensymbols\fR ir\('a escrever um diff entre as duas vers\(~oes. Mais ainda, se a diferen\(,ca for muito significante, ir\('a mesmo falhar (voc\(^e pode personalizar quanta diferen\(,ca pode ser tolerada, veja a op\(,c\(~ao \fB\-c\fR). .PP Este programa foi introduzido no dpkg 1.14.8. .SH "MANTENDO FICHEIROS DE S\('IMBOLOS" .IX Header "MANTENDO FICHEIROS DE S\('IMBOLOS" O formato de interc\(^ambio base do ficheiro de s\('imbolos \('e descrito em \fBdeb\-symbols\fR\|(5), o qual \('e usado pelos ficheiros symbols inclu\('idos em pacotes bin\('arios. Estes s\(~ao gerados a partir de ficheiros se s\('imbolos modelo com um formato baseado no anterior, descrito em \fBdeb\-src\-symbols\fR\|(5) e inclu\('ido em pacotes fonte. .PP Os ficheiros de s\('imbolos s\(~ao apenas \('uteis se refletirem a evolu\(,c\(~ao do pacote entre v\('arios lan\(,camentos. Assim o maintainer tem de os actualizar todas as vezes que \('e adicionado um novo s\('imbolo para que a sua vers\(~ao m\('inima associada corresponda \(`a realidade. .PP Os diffs contidos nos logs de compila\(,c\(~ao podem ser usados com ponto de partida, mas o maintainer, adicionalmente, tem de certificar que o comportamento desses s\('imbolos n\(~ao alterou num modo que fa\(,ca com que tudo o que usa esses s\('imbolos e em link para a nova vers\(~ao, deixem de funcionar com a vers\(~ao antiga. .PP Na maioria dos casos, o diff aplica-se directamente ao ficheiro debian/\fIpackage\fR.symbols. Dito isso, geralmente s\(~ao necess\('arios mais ajustes: \('e recomendado, por exemplo, soltar a revis\(~ao Debian da vers\(~ao m\('inima para que backports com um n\('umero de vers\(~ao inferior mas a mesma vers\(~ao de autor consigam ainda satisfazer as depend\(^encias geradas. Se uma revis\(~ao Debian n\(~ao pode ser largada porque o s\('imbolo foi realmente adicionado pela altera\(,c\(~ao espec\('ifica de Debian, ent\(~ao deve-se acrescentar um sufixo \(`a vers\(~ao com \(oq\fB~\fR\(cq. .PP Antes de aplicar qualquer patch ao ficheiro symbols, o maintainer deve re-verificar que esta \('e saud\('avel. N\(~ao \('e suposto s\('imbolos p\('ublicos desaparecerem, assim a patch deve idealmente apenas adicionar novas linhas. .PP Note que voc\(^e pode meter coment\('arios em ficheiros de s\('imbolos. .PP N\(~ao se esque\(,ca de verificar se vers\(~oes antigas de s\('imbolos precisam de ser aumentadas. N\(~ao h\('a maneira de \fBdpkg-gensymbols\fR poder avisar sobre isto. Aplica o diff \(`as cegas ou assumir que n\(~ao h\('a nada para mudar se n\(~ao existir um diff, sem verificar por tais mudan\(,cas, pode levar a pacotes com depend\(^encias soltas, que afirmam poder trabalhar com pacotes mais antigos com que j\('a n\(~ao podem trabalhar. Isto ir\('a introduzir dificuldades de encontrar bugs com actualiza\(,c\(~oes (parciais). .SS "Boa gest\(~ao de biblioteca" .IX Subsection "Boa gest\(~ao de biblioteca" Uma biblioteca bem mantida tem as seguintes caracter\('isticas: .IP \(bu 4 A sua API \('e est\('avel (s\('imbolos p\('ublicos nunca s\(~ao largados, apenas s\('imbolos p\('ublicos novos s\(~ao adicionados) e altera\(,c\(~oes em modos incompat\('iveis sempre apenas quando o SONAME muda; .IP \(bu 4 idealmente, usa a identifica\(,c\(~ao da vers\(~ao do s\('imbolo para obter estabilidade da ABI apesar de altera\(,c\(~oes internas e extens\(~ao API; .IP \(bu 4 n\(~ao exporta s\('imbolos privados (tais s\('imbolos podem ser etiquetados de opcionais como meio de contornar). .PP Enquanto se mant\('em o ficheiro symbols, \('e f\('acil percebermos o aparecimento e desaparecimento de s\('imbolos. Mas \('e mais dif\('icil apanhar altera\(,c\(~oes de API e ABI incompat\('iveis. Assim o maintainer deve ler com aten\(,c\(~ao o registo de altera\(,c\(~oes do autor procurando casos onde as regras da boa gest\(~ao de bibliotecas foram quebradas. Se forem descobertos potenciais problemas, o autor original deve ser notificado pois uma correc\(,c\(~ao no autor \('e sempre melhor que um contorno especifico em Debian. .SH OP\(,C\(~OES .IX Header "OP\(,C\(~OES" .IP \fB\-P\fR\fIpackage-build-dir\fR 4 .IX Item "-Ppackage-build-dir" Sonda \fIpackage-build-dir\fR em vez de debian/tmp. .IP \fB\-p\fR\fIpackage\fR 4 .IX Item "-ppackage" Define o nome do pacote. Requerido se mais do que um pacote bin\('ario estiver listado em debian/control (ou se n\(~ao existir o ficheiro debian/control). .IP \fB\-v\fR\fIversion\fR 4 .IX Item "-vversion" Define a vers\(~ao do pacote. Usa por predefini\(,c\(~ao a vers\(~ao extra\('ida de debian/changelog. Requerido se chamado fora de uma \('arvore de pacote fonte. .IP \fB\-e\fR\fIlibrary-file\fR 4 .IX Item "-elibrary-file" Apenas analisa bibliotecas explicitas em vez de procurar todas as bibliotecas p\('ublicas. Voc\(^e pode usar padr\(~oes de shell usadas para expans\(~oes de nome de caminho (veja o manual File::Glob para detalhes) em \fIlibrary-file\fR para corresponder a m\('ultiplas bibliotecas com um \('unico argumento (caso contr\('ario voc\(^e precisa de m\('ultiplos \fB\-e\fR). .IP \fB\-l\fR\fIdirectory\fR 4 .IX Item "-ldirectory" Precede \fIdirectory\fR \(`a lista de direct\('orios a pesquisar por bibliotecas partilhadas privadas (desde dpkg 1.19.1). Esta op\(,c\(~ao pode ser usada v\('arias vezes. .Sp \&\fBNota\fR: Use esta op\(,c\(~ao em vez de definir \fBLD_LIBRARY_PATH\fR, pois essa vari\('avel de ambiente \('e usado para controlar o vinculador de tempo\-de\-execu\(,c\(~ao e abusar dela para definir caminhos de bibliotecas partilhadas durante a compila\(,c\(~ao pode ser problem\('atico quando, por exemplo, se faz compila\(,c\(~oes cruzadas. .IP \fB\-I\fR\fIfilename\fR 4 .IX Item "-Ifilename" Usa \fInome-ficheiro\fR como ficheiro de refer\(^encia para gerar o ficheiro de s\('imbolos que \('e integrado no pr\('oprio pacote. .IP \fB\-O\fR[\fIfilename\fR] 4 .IX Item "-O[filename]" Escreve o ficheiro de s\('imbolos gerado na sa\('ida standard ou em \fIfilename\fR se especificado, em vez de \fBdebian/tmp/DEBIAN/symbols\fR (ou \fIpackage-build-dir\fR\fB/DEBIAN/symbols\fR se \fB\-P\fR foi usado). Se \fIfilename\fR \('e pr\('e\-existente, o seu conte\('udo \('e usado como base para o ficheiro de s\('imbolos gerado. Voc\(^e pode usar esta funcionalidade para actualizar um ficheiro de s\('imbolos para que corresponda \(`a nova vers\(~ao do autor da sua biblioteca. .IP \fB\-t\fR 4 .IX Item "-t" Escreve o ficheiro de s\('imbolos em modo de modelo em vez do formato compat\('ivel com \fBdeb\-symbols\fR\|(5). A principal diferen\(,ca \('e que em modo de modelo os nomes dos s\('imbolos e as etiquetas s\(~ao escritos na sua forma original ao contr\('ario dos nomes de s\('imbolos p\('os\-processados com as etiquetas despidas do modo de compatibilidade. Mais ainda, alguns s\('imbolos podem ser omitidos quando se escreve um ficheiro \fBdeb\-symbols\fR\|(5) standard (de acordo com as regras de processamento de etiquetas) enquanto que todos os s\('imbolos s\(~ao sempre escritos no ficheiro modelo de s\('imbolos. .IP \fB\-c\fR\fI[0\-4]\fR 4 .IX Item "-c[0-4]" Define as verifica\(,c\(~oes a fazer quando se compara o ficheiro de s\('imbolos gerado com o ficheiro modelo usado como ponto de partida. Por predefini\(,c\(~ao o n\('ivel \('e 1. Aumentar os n\('iveis faz mais verifica\(,c\(~oes e inclui todas as verifica\(,c\(~oes de baixo n\('ivel. .RS 4 .IP "N\('ivel 0" 4 .IX Item "N\('ivel 0" Nunca falha. .IP "N\('ivel 1" 4 .IX Item "N\('ivel 1" Falha se alguns s\('imbolos tiverem desaparecido. .IP "N\('ivel 2" 4 .IX Item "N\('ivel 2" Falha se alguns novo s\('imbolos tiverem sido introduzidos. .IP "N\('ivel 3" 4 .IX Item "N\('ivel 3" Falha se algumas bibliotecas tiverem desaparecido. .IP "N\('ivel 4" 4 .IX Item "N\('ivel 4" Falha se algumas bibliotecas tiverem sido introduzidos. .RE .RS 4 .Sp Este valor pode ser sobreposto pela vari\('avel de ambiente \fBDPKG_GENSYMBOLS_CHECK_LEVEL\fR. .RE .IP \fB\-q\fR 4 .IX Item "-q" Mant\(^em\-se calado e nunca gera um diff entre o ficheiro de s\('imbolos gerados e o ficheiro modelo usando como ponto de arranque nem mostra nenhuns avisos sobre bibliotecas novas/perdidas nem s\('imbolos novos/perdidos. Esta op\(,c\(~ao apenas desactiva os resultados informativos mas n\(~ao os pr\('oprios testes (veja a op\(,c\(~ao \fB\-c\fR). .IP \fB\-a\fR\fIarch\fR 4 .IX Item "-aarch" Assume \fIarch\fR como arquitectura anfitri\(~a quando processa ficheiros de s\('imbolos. Use esta op\(,c\(~ao para gerar um ficheiro de s\('imbolos ou a diferen\(,ca para qualquer arquitectura desde que os seus bin\('arios j\('a estejam dispon\('iveis. .IP \fB\-d\fR 4 .IX Item "-d" Activa o modo de depura\(,c\(~ao. S\(~ao mostradas numerosas mensagens para explicar o que o \fBdpkg-gensymbols\fR faz. .IP \fB\-V\fR 4 .IX Item "-V" Activa modo detalhado. O ficheiro de s\('imbolos gerado cont\('em s\('imbolos abandonados como coment\('arios. Mais ainda, em modo de modelo, os s\('imbolos de padr\(~oes s\(~ao seguidos de coment\('arios que listam s\('imbolos reais que corresponderam ao padr\(~ao. .IP "\fB\-?\fR, \fB\-\-help\fR" 4 .IX Item "-?, --help" Mostra a mensagem de utiliza\(,c\(~ao e termina. .IP \fB\-\-version\fR 4 .IX Item "--version" Mostra a vers\(~ao e termina. .SH AMBIENTE .IX Header "AMBIENTE" .IP \fBDPKG_GENSYMBOLS_CHECK_LEVEL\fR 4 .IX Item "DPKG_GENSYMBOLS_CHECK_LEVEL" Sobrep\(~oe o n\('ivel de verifica\(,c\(~ao do comando, mesmo se o argumento \fB\-c\fR de linha de comandos tenha sido dado (note que isto vai contra a conven\(,c\(~ao comum de argumentos de linha de comandos a ter a preced\(^encia sobre as vari\('aveis de ambiente). .IP \fBDPKG_COLORS\fR 4 .IX Item "DPKG_COLORS" Define o modo de cor (desde dpkg 1.18.5). Os valores actualmente aceites s\(~ao: \fBauto\fR (predefinido), \fBalways\fR e \fBnever\fR. .IP \fBDPKG_NLS\fR 4 .IX Item "DPKG_NLS" Se definida, ser\('a usada para decidir se deve activar o Suporte a Linguagem Nativa. Tamb\('em como conhecido como suporte de internacionaliza\(,c\(~ao (ou i18n) (desde dpkg 1.19.0). Os valores aceites s\(~ao \fB0\fR e \fB1\fR (predefini\(,c\(~ao). .SH "VEJA TAMB\('EM" .IX Header "VEJA TAMB\('EM" , , , \fBdeb\-src\-symbol\fR\|(5), \fBdeb\-symbols\fR\|(5), \fBdpkg\-shlibdeps\fR\|(1). .SH TRADU\(,C\(~AO .IX Header "TRADU\(,C\(~AO" Am\('erico Monteiro .PP Se encontrar algum erro na tradu\(,c\(~ao deste documento, por favor comunique para Am\('erico Monteiro .