path: root/man/pt/deb-src-symbols.pod

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