Initial Commit

database/perl/vendor/lib/POD2/PT_BR/local/lib.pod

@@ -0,0 +1,468 @@
+=encoding utf8
+
+=head1 NAME
+
+local::lib~[pt_br] - crie e use um diretório lib/ local para módulos perl com PERL5LIB
+
+=head1 SINOPSE
+
+No código -
+
+  use local::lib; # configura um lib local em ~/perl5
+
+  use local::lib '~/foo'; # idem, mas ~/foo
+
+  # Ou...
+  use FindBin;
+  use local::lib "$FindBin::Bin/../suporte";  # bibliotecas de suporte locais à aplicação
+
+Pela linha de comando (shell) -
+
+  # Instala o LWP e suas dependências não encontradas no diretório '~/perl5'
+  perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
+
+  # Apenas exibe alguns comandos úteis para a shell
+  $ perl -Mlocal::lib
+  export PERL_MB_OPT='--install_base /home/username/perl5'
+  export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
+  export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
+  export PATH="/home/username/perl5/bin:$PATH"
+
+=head2 A técnica de 'bootstrapping'
+
+Uma forma comum de instalar o local::lib é usando o que é conhecido como
+técnica de "bootstrapping". É uma boa abordagem caso seu administrador de
+sistemas não tenha instalado o local::lib. Nesse caso, você precisará
+instalar o local::lib em seu diretório de usuário.
+
+Caso você tenha privilégios de administrador, ainda assim deverá
+configurar suas variáveis de ambiente, como discutido no passo 4, abaixo.
+Sem elas, você ainda instalará módulos no CPAN do sistema e seus scripts
+Perl não utilizarão o caminho para o lib/ que você definiu com o local::lib.
+
+Por padrão, o local::lib instala os módulos do CPAN e a si próprio em ~/perl5.
+
+Usuários do Windows devem ler L</Diferenças ao usar esse módulo em Win32>.
+
+1. Baixe e descompacte o local::lib do CPAN (procure por "Download" na página
+do CPAN sobre o local::lib). Faça isso como um usuário comum, não como root
+ou administrador. Descompacte o arquivo em seu diretório de usuário ou em
+qualquer outro local conveniente.
+
+2. Execute isso:
+
+  perl Makefile.PL --bootstrap
+
+Caso o sistema pergunte se deve configurar tudo que puder automaticamente,
+você provavelmente deve responder que sim (yes).
+
+Para instalar o local::lib em um diretório que não o padrão, você precisará
+especificá-lo ao chamar o bootstrap, da seguinte forma:
+
+  perl Makefile.PL --bootstrap=~/foo
+
+3. Execute isso: (local::lib assume que você possui o comando 'make'
+instalado em seu sistema)
+
+  make test && make install
+
+4. Agora precisamos configurar as variáveis de ambiente apropriadas para
+que o Perl use nosso recém-criado diretório lib/. Caso esteja usando bash
+ou outra shell Bourne, você pode fazer isso adicionando a seguinte linha
+em seu script de inicialização da shell:
+
+  echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
+
+Caso esteja usando a shell C, pode fazer da seguinte forma:
+
+  /bin/csh
+  echo $SHELL
+  /bin/csh
+  perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
+
+Caso tenha passado para o bootstrap um diretório que não o padrão, você
+precisará indicá-lo na chamada ao local::lib, dessa forma:
+
+  echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
+
+Após atualizar seu arquivo de configuração da shell, certifique-se de
+processá-lo novamente para obter as modificações em sua shell atual.
+Shells Bourne usam C<. ~/.bashrc> para isso, enquanto shells C
+usam C<source ~/.cshrc>.
+
+Se estiver em uma máquina lenta ou operando com grandes limitações de
+espaço em disco, você pode desativar a geração automática de manpages a
+partir do POD ao instalar módulos. Para isso, basta passar o argumento
+C<--no-manpages> durante o bootstrap:
+
+  perl Makefile.PL --bootstrap --no-manpages
+
+Para evitar ter que fazer vários bootstraps para vários ambientes de
+módulos Perl na mesma conta de usuário - por exemplo se você usa o
+local::lib para desenvolver diferentes aplicativos independentes -
+você pode utilizar uma única instalação bootstrap do local::lib para
+instalar módulos em diretórios diferentes da seguinte forma:
+
+  cd ~/meudir1
+  perl -Mlocal::lib=./
+  eval $(perl -Mlocal::lib=./)  ### Para configurar o ambiente apenas nessa shell
+  printenv                      ### Veja que o ~/meudir1 está na PERL5LIB
+  perl -MCPAN -e install ...    ### Os módulos que quiser
+  cd ../meudir2
+  ... REPITA ...
+
+Para múltiplos ambientes destinados a múltiplos aplicativos, você pode
+precisar incluir uma versão modificada das instruções de C<< use FindBin >>
+no exemplo "No código" acima. Caso tenha feito algo como o que foi descrito
+acima, terá um conjunto de módulos Perl em C<< ~/meudir1/lib >>. Caso
+tenha um script em C<< ~/meudir1/scripts/meuscript.pl >>, você precisará
+indicar a ele onde encontrar os módulos que instalou para ele
+em C<< ~/meudir1/lib >>.
+
+Em C<< ~/meudir1/scripts/meuscript.pl >>:
+
+  use strict;
+  use warnings;
+  use local::lib "$FindBin::Bin/..";  ### aponta para ~/meudir1 e o local::lib acha o lib/
+  use lib "$FindBin::Bin/../lib";     ### aponta para ~/meudir1/lib
+
+Coloque isso antes de qualquer bloco BEGIN { ... } que precise dos módulos instalados.
+
+=head2 Diferenças ao usar esse módulo em Win32
+
+Para configurar as variáveis de ambiente apropriadas para sua sessão atual
+do C<CMD.exe>, você pode fazer assim:
+
+  C:\>perl -Mlocal::lib
+  set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
+  set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
+  set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
+  set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
+
+  ### Para configurar o ambiente apenas dessa shell
+  C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
+  ### em vez de $(perl -Mlocal::lib=./)
+
+Caso queira que as configurações do ambiente persistam, você precisará
+adicioná-las em Painel de Controle -> Sistema, ou usar o L<App::local::lib::Win32Helper>.
+
+O "~" é transformado no diretório do perfil do usuário (o diretório com o
+nome do usuário dentro de "Documents and Settings" (Windows XP ou anterior)
+ou "Usuários" (Windows Vista e mais recentes)) a menos que $ENV{HOME} exista.
+Após isso, o nome do diretório é encurtado e os subdiretórios são criados
+(o que significa que o diretório deve existir).
+
+=head1 MOTIVAÇÃO
+
+A versão de um pacote Perl na sua máquina nem sempre é a que você precisa.
+Obviamente, a melhor coisa a fazer seria atualizá-la para a versão desejada.
+No entanto, você pode estar em uma situação que o impede de fazer isso.
+Talvez você não tenha privilégios de administrador do sistema; ou talvez
+esteja usando um sistema de gerenciamento de pacotes como o do Debian,
+e ainda não exista um pacote disponível na versão desejada.
+
+local::lib resolve esse problema possibilitando a criação de seu próprio
+diretório de pacotes Perl obtidos do CPAN (em sistemas multi-usuário, isso
+normalmente fica dentro do diretório de seu usuário). A instalação do Perl
+no sistema permanece inalterada; você simplesmente chama o Perl com opções
+especiais para que ele use os pacotes em seu diretório local em vez dos
+pacotes do sistema. O local::lib organiza as coisas para que versões dos
+pacotes Perl instalados localmente tenham precedência sobre as do sistema.
+
+Caso esteja usando um sistema de gerenciamento de pacote (como em sistemas
+Debian), não precisará se preocupar com conflitos entre o Debian e o CPAN.
+Sua versão local dos pacotes será instalada em um diretório completamente
+diferente das versões instaladas pelo gerenciador de pacotes do sistema.
+
+=head1 DESCRIÇÃO
+
+Este módulo oferece uma forma rápida e conveniente para criar um repositório
+de módulos locais ao usuário, dentro do diretório do mesmo. Ele também monta
+e exibe para o usuário uma lista de variáveis de ambiente utilizando a
+sintaxe da shell atual do usuário (conforme especificado pela variável
+de ambiente C<SHELL>), pronta para ser adicionada diretamente no arquivo
+de configuração da shell.
+
+Generalizando, o local::lib permite a criação e uso de um diretório contendo
+módulos Perl fora do C<@INC> do Perl. Isso facilita a produção de aplicações
+com uma versão específica de determinado módulo, ou coleção de módulos.
+Também é útil quando o mantenedor de um módulo não aplicou determinado patch
+que você precisa para seu aplicativo.
+
+Durante o C<import>, o local::lib define valores apropriados para as
+seguintes variáveis de ambiente:
+
+=over 4
+
+=item PERL_MB_OPT
+
+=item PERL_MM_OPT
+
+=item PERL5LIB
+
+=item PATH
+
+valores serão anexados ao PATH, em vez de substituí-lo.
+
+=back
+
+Esses valores são então disponibilizados para referência por qualquer
+outro código após o C<import>.
+
+=head1 CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS
+
+Veja L<lib::core::only|lib::core::only> para uma maneira de fazer isso - mas
+note que há uma série de ressalvas na abordagem, e a melhor forma é sempre
+fazer o 'build' contra uma versão limpa do perl (i.e. com 'site' e 'vendor'
+o mais vazios possível).
+
+=head1 MÉTODOS
+
+=head2 ensure_dir_structure_for
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: Nenhum
+
+=back
+
+Tenta criar o caminho fornecido, e todos os diretórios superiores necessários. Gera uma exceção em caso de falha.
+
+=head2 print_environment_vars_for
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: Nenhum
+
+=back
+
+Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas
+para utilizar o caminho fornecido como diretório base.
+
+=head2 build_environment_vars_for
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio, $interpolar
+
+=item Valor de Retorno: %variaveis_de_ambiente
+
+=back
+
+Retorna hash contendo as variáveis de ambiente listadas acima, devidamente
+ajustadas para utilizar o caminho fornecido como diretório base.
+
+=head2 setup_env_hash_for
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: Nenhum
+
+=back
+
+Constrói as chaves no C<%ENV> para o caminho fornecido, chamando
+C<build_environment_vars_for>.
+
+=head2 install_base_perl_path
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: $caminho_base_de_instalacao
+
+=back
+
+Retorna um caminho de diretório indicando onde instalar os módulos Perl
+para essa instalação local de bibliotecas. Adiciona os diretórios C<lib>
+e C<perl5> ao final do caminho fornecido.
+
+=head2 install_base_arch_path
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: $caminho_base_de_instalacao_arch
+
+=back
+
+Retorna um caminho de diretório indicando onde instalar os módulos Perl
+de arquiteturas específicas para essa instalação local de bibliotecas.
+Baseia-se no valor de retorno do método L</install_base_perl_path>,
+adicionando o valor de C<$Config{archname}>.
+
+=head2 install_base_bin_path
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: $caminho_base_de_instalacao_bin
+
+=back
+
+Retorna um caminho de diretório indicando onde instalar programas executáveis
+para essa instalação local de bibliotecas. Baseia-se no valor de retorno do
+método L</install_base_perl_path>, adicionando o diretório C<bin>.
+
+=head2 resolve_empty_path
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: $caminho_base_de_instalacao
+
+=back
+
+Cria e retorna o caminho de diretório raiz em que a instalação local de
+módulos deve ser feita. O padrão é C<~/perl5>.
+
+=head2 resolve_home_path
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: $caminho_para_home
+
+=back
+
+Procura pelo diretório padrão (home) do usuário. Caso esteja instalado,
+utiliza o C<File::HomeDir> para isso. Gera uma exceção caso não encontre
+resultado definitivo.
+
+=head2 resolve_relative_path
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: $caminho_absoluto
+
+=back
+
+Transforma o caminho fornecido em um caminho absoluto.
+
+=head2 resolve_path
+
+=over 4
+
+=item Argumentos: $caminho_do_diretorio
+
+=item Valor de Retorno: $caminho_absoluto
+
+=back
+
+Invoca os seguintes métodos em sequência, passando o resultado do método
+anterior para o seguinte, na tentativa de descobrir onde configurar o
+ambiente para a instalação local de bibliotecas: L</resolve_empty_path>,
+L</resolve_home_path>, L</resolve_relative_path>. Passa o caminho de
+diretório fornecido para L</resolve_empty_path> que retorna um resultado
+que é passado para L</resolve_home_path>, que então tem seu resultado
+passado para L</resolve_relative_path>. O resultado dessa chamada final
+é então retornado pelo L</resolve_path>.
+
+=head1 UM AVISO SOBRE UNINST=1
+
+Tenha cuidado ao usar o local::lib em conjunto com "make install UNINST=1".
+A idéia dessa opção é desinstalar a versão anterior de um módulo antes de
+instalar a mais recente. No entanto ela não possui uma verificação de
+segurança de que a versão antiga e a nova referem-se ao mesmo diretório.
+Usada em combinação com o local::lib, você pode potencialmente apagar uma
+versão globalmente acessível de um módulo e instalar a versão mais nova
+no diretório local. Apenas utilize "make install UNINST=1" junto com o
+local::lib se você entende essas possíveis consequências.
+
+=head1 LIMITAÇÕES
+
+As ferramentas auxiliares do perl não conseguem lidar com nomes de
+diretórios contendo espaços, então não é possível fazer seu bootstrap
+do local::lib em um diretório com espaços. O que você pode fazer é mover
+seu local::lib para um diretório com espaços B<após> ter instalado todos
+os módulos dentro dele. Mas esteja ciente que você não poderá atualizar
+ou instalar outros módulos do CPAN nesse diretório local após a mudança.
+
+A detecção da shell é relativamente básica. Neste momento, qualquer coisa
+com csh no nome será tratada como a C shell ou compatível, e todo o resto
+será tratado como Bourne, exceto em sistemas Win32. Caso a variável de
+ambiente C<SHELL> não esteja disponível, assumiremos tratar-se de uma
+shell compatível com a Bourne.
+
+A técnica de bootstrap é um hack e usará o CPAN.pm para o ExtUtils::MakeMaker
+mesmo que você tenha o CPANPLUS instalado.
+
+Destrói qualquer valor pré-existente nas variáveis de ambiente PERL5LIB,
+PERL_MM_OPT e PERL_MB_OPT.
+
+Provavelmente deveria auto-configurar o CPAN caso isso ainda não tenha
+sido feito.
+
+Correções (patches) são muito bem-vindos para quaisquer dos itens acima.
+
+Em sistemas Win32, não há uma forma de escrever no registro as variáveis
+de ambiente criadas, para que elas persistam a uma reinicialização.
+
+=head1 SOLUÇÃO DE PROBLEMAS
+
+Se você configurou o local::lib para instalar módulos do CPAN em algum lugar
+do seu 'home', e mais tarde tentou instalar um módulo fazendo C<cpan -i
+Foo::Bar>, mas ele falhou com um erro como: C<Warning: You do not have
+permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
+/usr/lib64/perl5/5.8.8/Foo/Bar.pm> e em algum lugar no seu log de instalação
+houver um erro dizendo C<'INSTALL_BASE' is not a known MakeMaker parameter
+name>, então você de alguma forma perdeu seu ExtUtils::MakeMaker atualizado.
+
+Para remediar a situação, execute novamente o procedimento de bootstrap
+descrito acima.
+
+Então, execute C<rm -r ~/.cpan/build/Foo-Bar*>
+
+Finalmente, execute novamente o C<cpan -i Foo::Bar> e ele deve instalar
+sem problemas.
+
+=head1 AMBIENTE
+
+=over 4
+
+=item SHELL
+
+=item COMSPEC
+
+O local::lib procura pela variável de ambiente C<SHELL> do usuário ao
+processar e exibir os comandos a serem adicionados no arquivo de
+configuração da shell.
+
+Em sistemas Win32, C<COMSPEC> também será examinado.
+
+=back
+
+=head1 SUPORTE
+
+IRC:
+
+    Acesse #local-lib em irc.perl.org.
+
+=head1 AUTOR DA TRADUÇÃO
+
+Breno G. de Oliveira, C<< <garu at cpan.org> >>, após ter perdido uma aposta
+para o L<Getty|http://search.cpan.org/~getty/> durante a Copa de 2010.
+
+
+=head1 COPYRIGHT
+
+Copyright (c) 2007 - 2010 L<local::lib/"AUTHOR">
+e L<local::lib/"CONTRIBUTORS"> do local::lib como listados em L<local::lib>.
+
+=head1 LICENÇA
+
+Esta biblioteca é software livre e pode ser distribuída sob os mesmo termos
+do perl.
+