
        *****************************************************
        *           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

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 L</Usando inclusões>). As linhas que começam com ‘#MISSING:’ são comentários especiais que documentam símbolos que desapareceram.

=head2 Usando substituições de meta-variável

Em alguns casos em vez de codificar rigidamente algum texto variável, podemos usar meta-variáveis que irão ser substituídas ou quando se gere o ficheiro de símbolos empacotado com o pacote binário, ou durante a geração da dependência.

Ao contrário da meta-variável I<#MINVER#>, as seguintes meta-variáveis nunca irão aparecer num ficheiro de símbolos dentro de um pacote binário.

=head3 Usando a meta-variável #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 a meta-variável I<#PACKAGE#>. Será substituída pelo nome real do pacote durante a instalação dos ficheiros de símbolos.

=head3 Usado a meta-variável #CURVER#

Em alguns casos, um símbolo com uma ABI instável vai requerer uma dependência estrita na versão do pacote atual.  Para evitar uma codificação rígida da versão atual no ficheiro de símbolos, você pode usar a meta-variável I<#CURVER#>.  Irá ser substituída por uma versão de dependência limitada no formato de “(= I<binário-versão>)”, onde isto será geralmente usado em combinação com I<#PACKAGE#>.

Suportado desde dpkg 1.23.4.

=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 L</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 L<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 L<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>

These tags allow one to restrict the set of architectures where the symbol is supposed to exist.  When the symbols list is updated with the symbols discovered in the library, all arch-specific symbols which do not concern the current host architecture are treated as if they did not exist.  If an arch-specific symbol matching the current host architecture does not exist in the library, normal procedures for missing symbols apply and it may cause B<dpkg-gensymbols> to fail.  On the other hand, if the arch-specific symbol is found when it was not supposed to exist (because the current host architecture is not listed in the tag or does not match the endianness and bits), it is made arch neutral (i.e. the arch, arch-bits and arch-endian tags are dropped and the symbol will appear in the diff due to this change), but it is not considered as new.

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 arm64, any-amd64 e riscv64, o segundo apenas em arquitecturas de linux, enquanto o terceiro em todas excepto em armel.

  (arch=arm64 any-amd64 riscv64)arch_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

Support for tags B<arch-bits> and B<arch-endian> since dpkg 1.18.0.

=item B<allow-internal>

dpkg-gensymbols has a list of internal symbols that should not appear in symbols files as they are usually only side-effects of implementation details of the toolchain.  If for some reason, you really want one of those symbols to be included in the symbols file, you should tag the symbol with B<allow-internal>.  It can be necessary for some low level toolchain libraries like “libgcc”.

Suportado desde dpkg 1.20.1.

=item B<c++>

indica o padrão de símbolos I<c++> . Veja a sub-secção L</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 L</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 L</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.

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.  See the 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.  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++>

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 L<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

Note that while mangled name is unique in the library by definition, this is not necessarily true for demangled names.  A couple of distinct real symbols may have the same demangled name.  For example, that's the case with non-virtual thunk symbols in complex inheritance configurations or with most constructors and destructors (since g++ typically generates two real symbols for them).  However, as these collisions happen on the ABI level, they should not degrade quality of the symbol file.

=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.

Note that while old style wildcard patterns (denoted by "*@version" in the symbol name field) are still supported, they have been deprecated by new style syntax "(symver|optional)version".  For example, "*@GLIBC_2.0 2.0" should be written as "(symver|optional)GLIBC_2.0 2.0" if the same behavior is needed.

=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.

When multiple patterns match the same real symbol, aliases (first I<c++>, then I<symver>) are preferred over generic patterns.  Generic patterns are matched in the order they are found in the symbol file template until the first success.  Note, however, that manual reordering of template file entries is not recommended because B<dpkg-gensymbols> generates diffs based on the alphanumerical order of their names.

=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-bits=64)#include "package.symbols.64-bit"
 (arch-bits=32)#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>.
