path: root/man/pt/dpkg-maintscript-helper.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

dpkg-maintscript-helper - contorna limitações conhecidas do dpkg em scripts
de maintainer.

=head1 SINOPSE

B<dpkg-maintscript-helper> I<command> [I<parameter>...] B<-->
I<maint-script-parameter>...

=head1 COMANDOS E PARÂMETROS

=over 

=item B<supports> I<command>

=item B<rm_conffile> I<conffile> [I<prior-version> [I<package>]]

=item B<mv_conffile> I<old-conffile> I<new-conffile> [I<prior-version>
[I<package>]]

=item B<symlink_to_dir> I<pathname> I<old-target> [I<prior-version> [I<package>]]

=item B<dir_to_symlink> I<pathname> I<new-target> [I<prior-version> [I<package>]]

=back

=head1 DESCRIÇÃO

Este programa destina-se a ser corrido dentro de scripts de maintainer para
conseguir algumas tarefas que o B<dpkg> (ainda) não pode lidar nativamente
seja por limitações de desenho ou devido a limitações actuais,

Muitas destas tarefas requerem acções coordenadas dos vários scripts de
maintainer (B<preinst>, B<postinst>, B<prerm>, B<postrm>). Para evitar
enganos a mesma chamada precisa simplesmente de englobar todos os scripts e
o programa irá automaticamente adaptar o seu comportamento baseado na
variável de ambiente B<DPKG_MAINTSCRIPT_NAME> e nos argumentos dos scripts
do maintainer que você tem de reencaminhar após um duplo hífen.

=head1 PARÂMETROS COMUNS

=over 

=item I<prior-version>

Define a versão mais recente do pacote cuja actualização deverá despoletar a
operação. É importante calcular I<prior-version> correctamente para que as
operações sejam correctamente executadas mesmo que o utilizador recompile o
pacote com uma versão local. Se I<prior-version> estiver vazio ou omitido,
então a operação é tentada a cada actualização (nora: é mais seguro fornecer
a versão e ter a operação tentada apenas uma vez).

Se o conffile não tem sido enviado por várias versões, e você está agora a
modificar os scripts do maintainer para limpar o ficheiro obsoleto,
I<prior-version> deve ser baseado na versão do pacote que está agora a
preparar, e não a primeira versão do pacote onde faltou o conffile. Isto
aplica-se a todas as outras acções do mesmo modo.

Por exemplo, para um conffile removido na versão B<2.0-1> de um pacote,
I<prior-version> deve ser definido para B<2.0-1~>. Isto irá fazer com que o
conffile seja removido mesmo que o utilizador recompile a versão anterior
B<1.0-1> como B<1.0-1local1>. Ou um pacote que mude um caminho de um link
simbólico (enviado na versão  B<1.0-1>) para um directório (enviado na
versão B<2.0-1>), mas apenas executando a mudança real nos scripts do
maintainer na versão B<3.0-1>, deve definir I<prior-version> para B<3.0-1~>.

=item I<package>

O nome do pacote que possui os nome(s) de caminho(s). Quando o pacote é
“Multi-Arch: same” este parâmetros tem de incluir o qualificador de
arquitectura, caso contrário B<não> deverá geralmente incluir o qualificador
de arquitectura ((pois iria desautorizar cruzamento de graduação, ou comutar
de ser específico de arquitectura para arquitectura B<all> ou vice
versa). Se o parâmetro estiver vazio ou omitido, as variáveis de ambiente
B<DPKG_MAINTSCRIPT_PACKAGE> e B<DPKG_MAINTSCRIPT_ARCH> (definidas pelo
B<dpkg> ao correr os scripts do maintainer) serão usadas para gerar um nome
de pacote com qualificação de arquitectura.

=item B<-->

Todos os parâmetros dos scripts do maintainer têm de ser encaminhados ao
programa após B<-->.

=back

=head1 TAREFAS RELACIONADAS COM FICHEIROS DE CONFIGURAÇÃO

Ao actualizar um pacote, o B<dpkg> não irá automaticamente remover um
conffile (um ficheiro de configuração para o qual B<dpkg> deve preservar as
alterações do utilizador) se este não estiver presente na versão mais
recente. Existem duas razões principais para isto: a primeira é que o
conffile poderia ser abandonado por acidente e a próxima versão poderia
restaurá-lo., e os utilizadores não querem que as suas alterações sejam
deitadas fora. A segunda é para permitir aos pacotes transitarem ficheiros
de um conffile mantido pelo dpkg para um ficheiro mantido pelos scripts do
maintainer do pacote, geralmente com uma ferramenta como debconf ou ucf.

Isto significa que se um pacote se destina a renomear ou remover um
conffile, deve explicitamente fazê-lo e B<dpkg-maintscript-helper> pode ser
usado para implementar o apagar e mover elegante de conffiles dentro dos
scripts do maintainer.

=head2 Remover um ficheiro de configuração

Nota: Isto pode ser substituído na maioria dos casos pela bandeira
C<remove-on-upgrade> em F<DEBIAN/conffiles> (desde dpkg 1.20.6), veja
L<deb-conffiles(5)>.

Se um conffile for completamente removido, deve ser removido do disco, a
menos que o utilizador o tenha modificado. Se existirem modificações locais,
estas devem ser preservadas. Se a actualização do pacote abortar, o conffile
obsoleto mais recente não deve desaparecer.

tudo isto é implementado ao colocar o seguinte fragmento de shell nos
scripts de maintainer B<preinst>, B<postinst> e B<postrm>:

=over 

Z<>
 dpkg-maintscript-helper rm_conffile \
    I<conffile> I<prior-version> I<package> -- "$@"

=back

I<conffile> é o nome de ficheiro do conffile a remover.

Implementação actual: no B<preinst>, verifica se o conffile foi modificado e
renomeia-o ou para I<conffile>B<.dpkg-remove> (se não modificado) ou para
I<conffile>B<.dpkg-backup> (se modificado). No B<postinst>, o último
ficheiro é renomeado para I<conffile>B<.dpkg-bak> e mantido para referência
pois contem modificações do utilizador mas o antigo será removido. Se a
actualização ao pacote abortar, o B<postrm> reinstala o conffile
original. Durante a purga, o B<postrm> irá também apagar o ficheiro
B<.dpkg-bak> mantido até à data.

=head2 Renomear um conffile

Se um conffile for movido de uma localização para outra, você precisa de
certificar que se move por quaisquer alterações que o utilizador tenha
feito. Isto pode parecer uma mudança simples para o script B<preinst> no
inicio, no entanto isso vai resultar no utilizador a ser questionado pelo
B<dpkg> para aprovar as edições no conffile mesmo este não sendo o
responsável por elas.

O renomear elegante pode ser implementado ao colocar o seguinte fragmente do
shell nos scripts de maintainer B<preinst>, B<postinst> e B<postrm>:

=over 

Z<>
 dpkg-maintscript-helper mv_conffile \
    I<old-conffile> I<new-conffile> I<prior-version> I<package> -- "$@"

=back

I<old-conffile> e I<new-conffile> sãos os nomes antigo e novo do conffile a
renomear.

Implementação actual: o B<preinst> verifica se o conffile foi modificado. Se
sim, é deixado no lugar, caso contrário é renomeado para
I<old-conffile>B<.dpkg-remove>. Durante a configuração, o B<postinst> remove
I<old-conffile>B<.dpkg-remove> e renomeia I<old-conffile> para
I<new-conffile> se I<old-conffile> ainda estiver disponível. No
abortar-actualização/abortar-instalação, o B<postrm> renomeia
I<old-conffile>B<.dpkg-remove> de volta a I<old-conffile> se necessário.

=head1 LINKS SIMBÓLICOS E SWITCHES DE DIRECTÓRIO

Ao actualiza um pacote, o B<dpkg> não irá mudar automaticamente de um link
simbólico para um directório ou vice-versa. Downgrades (descidas de versão)
não são suportados e o caminho irá ser deixado como está.

=head2 Alternar um link simbólico para directório

Se um link simbólico for mudado para um directório real, você precisa de
certificar que o link simbólico é removido antes de desempacotar. Isto pode
parecer uma mudança simples para o script B<preinst> no inicio, no entanto
isso irá resultar em alguns problemas no caso de personalização local
administrativa do link simbólico ou quando se retrocede na versão do pacote
(downgrade).

O renomear elegante pode ser implementado ao colocar o seguinte fragmente do
shell nos scripts de maintainer B<preinst>, B<postinst> e B<postrm>:

=over 

Z<>
 dpkg-maintscript-helper symlink_to_dir \
    I<pathname> I<old-target> I<prior-version> I<package> -- "$@"

=back

I<pathname> é o nome absoluto do link simbólico antigo (o caminho será um
directório no final da instalação) e I<old-target> é o nome do alvo do link
simbólico anterior em I<pathname>. Pode ser ou absoluto ou relativo ao
directório que contem I<pathname>.

Implementação actual: o B<preinst> verifica se o link simbólico existe e
aponta para I<old-target>, se não então deixa-o como estiver, caso contrário
é renomeado para I<pathname>B<.dpkg-backup>. Na configuração, o B<postinst>
remove I<pathname>B<.dpkg-backup> se I<pathname>B<.dpkg-backup> for ainda um
link simbólico. Ao aborta actualização/instalação. o B<postrm> renomeia
<pathname>B<.dpkg-backup> de volta para I<pathname> se necessário.

=head2 Alternar um directório para link simbólico

Se um directório é comutado para um link simbólico, você precisa de
certificar-se antes de desempacotar que o directório foi removido. Isto pode
parecer no início uma alteração simples ao script B<preinst>, no entanto
isso vai resultar em alguns problemas se o directório conter conffiles,
nomes de caminhos possuídos por outros pacotes, nomes de caminhos criados
localmente, ou quando instala uma versão anterior do pacote (downgrade).

Mudança elegante pode ser implementada ao colocar o seguinte fragmento de
shell nos scripts B<preinst>, B<postinst> e B<postrm> do maintainer:

=over 

Z<>
 dpkg-maintscript-helper dir_to_symlink \
    I<pathname> I<new-target> I<prior-version> I<package> -- "$@"

=back

I<pathname> é o nome absoluto do directório antigo (o caminho será um link
simbólico no final da instalação) e I<new-target> é o alvo do novo link
simbólico em I<pathname>. Pode ser ou absoluto ou relativo ao directório que
contem I<pathname>.

Implementação actual: o B<preinst> verifica se o directório existe, não
contém conffiles, nomes de caminhos possuídos por outros pacotes, ou nomes
de caminhos criados localmente, se não então é deixa-do como está, caso
contrário é renomeado para I<pathname>B<.dpkg-backup>, e é criado um
directório vazio estagiário chamado I<pathname>, marcado com um ficheiro
para que o dpkg o possa acompanhar. Na configuração, o B<postinst> termina a
comutação se I<pathname>B<.dpkg-backup> for ainda um directório e se
I<pathname> é o directório de estagiário; remove o ficheiro marcador do
directório estagiário, move os ficheiros acabados de criar dentro do
directório estagiário para o link simbólico alvo I<new-target>/, substitui o
agora vazio directório estagiário I<pathname> com um link simbólico para
I<new-target>, e remove I<pathname>B<.dpkg-backup>. Ao abortar
actualização/instalação, o B<postrm> renomeia I<pathname>B<.dpkg-backup> de
volta para I<pathname> se necessário.

=head1 INTEGRAÇÃO EM PACOTES

Quando usar um ajudante de empacotamento, por favor verifique se ele tem
integração com B<dpkg-maintscript-helper> nativa, o que pode tornar a sua
vida mais fácil. Veja por exemplo B<dh_installdeb>(1).

Dado que B<dpkg-maintscript-helper> é usado no B<preinst>, usá-lo
incondicionalmente requer uma pré-dependência para assegurar que a versão
requerida do B<dpkg> já foi desempacotada antes. A versão requerida depende
do comando usado, para B<rm_conffile> e B<mv_conffile> é 1.15.7.2, para
B<symlink_to_dir> e B<dir_to_symlink> é 1.17.14:

=over 

 Pre-Depends: dpkg (>= 1.17.14)

=back

Mas em muitos casos a operação feita pelo programa não é crítica para o
pacote, e em vez de usar uma pré-dependência nós podemos chamar o programa
apenas quando sabemos que o comando requerido é suportado pelo B<dpkg>
presentemente instalado:

=over 

Z<>
 if dpkg-maintscript-helper supports I<command>; then
    dpkg-maintscript-helper I<command> ...
 fi

=back

O comando B<supports> irá retornar 0 em sucesso, 1 caso contrário. O comando
B<supports> irá verificar se as variáveis de ambiente estão presentes como
definidas pelo dpkg e requeridas pelo script, e irá considerar um fracasso
no caso do ambiente não ser suficiente.

=head1 AMBIENTE

=over 

=item B<DPKG_ROOT>

Se definido, será usado como o directório raiz do sistema de ficheiros.

=item B<DPKG_ADMINDIR>

Se definido, será usado como o directório de dados do B<dpkg>.

=item B<DPKG_COLORS>

Define o modo de cor (desde dpkg 1.19.1). Os valores presentemente aceites
são: B<auto> (predefinição), B<always> e B<never>.

=back

=head1 VEJA TAMBÉM

B<dh_installdeb>(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>.