diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-27 09:40:31 +0000 |
commit | b86570f63e533abcbcb97c2572e0e5732a96307b (patch) | |
tree | cabc83be691530ae685c45a8bc7620ccc0e1ebdf /man/pt/deb-src-symbols.pod | |
parent | Initial commit. (diff) | |
download | dpkg-upstream.tar.xz dpkg-upstream.zip |
Adding upstream version 1.20.13.upstream/1.20.13upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to '')
-rw-r--r-- | man/pt/deb-src-symbols.pod | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/man/pt/deb-src-symbols.pod b/man/pt/deb-src-symbols.pod new file mode 100644 index 0000000..cdcfb29 --- /dev/null +++ b/man/pt/deb-src-symbols.pod @@ -0,0 +1,406 @@ + + ***************************************************** + * 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 SINOPSE + +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 + +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 B<Usando inclusões>). As linhas que começam com +‘#MISSING:’ são comentários especiais que documentam símbolos que +desapareceram. + +=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 + +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 B<dpkg-gensymbols> e despoletam +manuseamento especial dos símbolos. Veja a sub-secção B<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 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. + +Como as etiquetas de símbolos são uma extensão do formato B<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 +B<dpkg-gensymbols> é chamado sem a opção B<-t>, irá escrever ficheiros de +símbolos compatíveis com o formato B<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 (B<-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. + +=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++> + +indica o padrão de símbolos I<c++> . Veja a sub-secção B<Usar padrões de +símbolos> em baixo. + +=item B<symver> + +Indica o padrão de símbolos I<symver> (versão de símbolo). Veja a sub-secção +B<Usar padrões de símbolos> em baixo. + +=item B<regex> + +Indica o padrão de símbolos I<regex>. Veja a sub-secção B<Usar padrões de +símbolos> em baixo. + +=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. + +Um padrão é considerado perdido se não corresponder a nenhum símbolo da +biblioteca. Por predefinição isto irá despoletar que B<dpkg-gensymbols> +falhe sob B<-c1> ou nível mais alto. No entanto, se a falha for indesejável, +o padrão pode ser marcado com a etiqueta I<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 I<arch>. Por favor consulte a sub.secção +B<Etiquetas símbolo standard> em cima para mais informação. + +Padrões são uma extensão do formato B<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 I<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, B<dpkg-gensymbols> suporta três tipos de padrão básicos: + +=over + +=item B<c++> + +Este padrão é denotado pela etiqueta I<c++>. Corresponde apenas a símbolos +C++ pelo seu nome desmutilado de símbolo (como emitido pelo utilitário +B<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 é I<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 I<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 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. + +=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 +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 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 +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 +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.64bit" + (arch=!amd64 !ia64 !alpha)#include "package.symbols.32bit" + 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 + +B<deb-symbols>(5), B<dpkg-shlibdeps>(1), B<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>. |