--- /dev/null
+=encoding utf8
+
+=head1 NOME
+
+local::lib~[pt_br] - crie e use um 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 MODULEBUILDRC=/home/username/perl/.modulebuildrc
+ export PERL_MM_OPT='INSTALL_BASE=/home/username/perl'
+ export PERL5LIB='/home/username/perl/lib/perl5:/home/username/perl/lib/perl5/i386-linux'
+ export PATH="/home/username/perl/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, você ainda assim deverá
+configurar suas variáveis de ambiente, como discutido no passo 4. 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 para 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 MODULEBUILDRC=C:\DOCUME~1\ADMINI~1\perl5\.modulebuildrc
+ 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 probleme 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 MODULEBUILDRC
+
+=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_directory_structure_for
+
+=over 4
+
+=item Argumentos: caminho de diretório
+
+=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 de diretório
+
+=back
+
+Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas
+para utilizar o caminho fornecido como diretório base.
+
+=head2 setup_env_hash_for
+
+=over 4
+
+=item Argumentos: caminho de diretório
+
+=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 de diretório
+
+=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 de diretório
+
+=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 de diretório
+
+=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 modulebuildrc_path
+
+=over 4
+
+=item Argumentos: caminho de diretório
+
+=back
+
+Retorna um caminho de diretório indicando onde instalar o arquivo
+C<.modulebuildrc>, baseado no caminho fornecido.
+
+=head2 resolve_empty_path
+
+=over 4
+
+=item Argumentos: caminho de diretório
+
+=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 de diretório
+
+=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 de diretório
+
+=back
+
+Transforma o caminho fornecido em um caminho absoluto.
+
+=head2 resolve_path
+
+=over 4
+
+=item Argumentos: caminho de diretório
+
+=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 MODULEBUILDRC.
+
+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> >>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2007 - 2010 L</AUTOR> e L</COLABORADORES> 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.
+
projects / p5sagit/local-lib.git / commitdiff