Provided by: liblocal-lib-perl_2.000029-1_all 
NAME
local::lib~[pt_br] - crie e use um diretório lib/ local para módulos perl com PERL5LIB
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"
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 "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 ". ~/.bashrc" para isso, enquanto shells C usam
"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 "--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 "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 "~/meudir1/lib". Caso tenha um script em
"~/meudir1/scripts/meuscript.pl", você precisará indicar a ele onde encontrar os módulos que instalou
para ele em "~/meudir1/lib".
Em "~/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.
Diferenças ao usar esse módulo em Win32
Para configurar as variáveis de ambiente apropriadas para sua sessão atual do "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 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).
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.
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
"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 @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 "import", o local::lib define valores apropriados para as seguintes variáveis de ambiente:
PERL_MB_OPT
PERL_MM_OPT
PERL5LIB
PATH
valores serão anexados ao PATH, em vez de substituí-lo.
Esses valores são então disponibilizados para referência por qualquer outro código após o "import".
CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS
Veja 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).
MÉTODOS
ensure_dir_structure_for
Argumentos: $caminho_do_diretorio
Valor de Retorno: Nenhum
Tenta criar o caminho fornecido, e todos os diretórios superiores necessários. Gera uma exceção em caso
de falha.
print_environment_vars_for
Argumentos: $caminho_do_diretorio
Valor de Retorno: Nenhum
Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas para utilizar o caminho
fornecido como diretório base.
build_environment_vars_for
Argumentos: $caminho_do_diretorio, $interpolar
Valor de Retorno: %variaveis_de_ambiente
Retorna hash contendo as variáveis de ambiente listadas acima, devidamente ajustadas para utilizar o
caminho fornecido como diretório base.
setup_env_hash_for
Argumentos: $caminho_do_diretorio
Valor de Retorno: Nenhum
Constrói as chaves no %ENV para o caminho fornecido, chamando "build_environment_vars_for".
install_base_perl_path
Argumentos: $caminho_do_diretorio
Valor de Retorno: $caminho_base_de_instalacao
Retorna um caminho de diretório indicando onde instalar os módulos Perl para essa instalação local de
bibliotecas. Adiciona os diretórios "lib" e "perl5" ao final do caminho fornecido.
install_base_arch_path
Argumentos: $caminho_do_diretorio
Valor de Retorno: $caminho_base_de_instalacao_arch
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 "install_base_perl_path",
adicionando o valor de $Config{archname}.
install_base_bin_path
Argumentos: $caminho_do_diretorio
Valor de Retorno: $caminho_base_de_instalacao_bin
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 "install_base_perl_path", adicionando o diretório
"bin".
resolve_empty_path
Argumentos: $caminho_do_diretorio
Valor de Retorno: $caminho_base_de_instalacao
Cria e retorna o caminho de diretório raiz em que a instalação local de módulos deve ser feita. O padrão
é "~/perl5".
resolve_home_path
Argumentos: $caminho_do_diretorio
Valor de Retorno: $caminho_para_home
Procura pelo diretório padrão (home) do usuário. Gera uma exceção caso não encontre resultado
definitivo.
resolve_relative_path
Argumentos: $caminho_do_diretorio
Valor de Retorno: $caminho_absoluto
Transforma o caminho fornecido em um caminho absoluto.
resolve_path
Argumentos: $caminho_do_diretorio
Valor de Retorno: $caminho_absoluto
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:
"resolve_empty_path", "resolve_home_path", "resolve_relative_path". Passa o caminho de diretório
fornecido para "resolve_empty_path" que retorna um resultado que é passado para "resolve_home_path", que
então tem seu resultado passado para "resolve_relative_path". O resultado dessa chamada final é então
retornado pelo "resolve_path".
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.
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 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 "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.
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 "cpan -i Foo::Bar", mas ele falhou com um erro como: "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
"'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 "rm -r ~/.cpan/build/Foo-Bar*"
Finalmente, execute novamente o "cpan -i Foo::Bar" e ele deve instalar sem problemas.
AMBIENTE
SHELL
COMSPEC
O local::lib procura pela variável de ambiente "SHELL" do usuário ao processar e exibir os comandos a
serem adicionados no arquivo de configuração da shell.
Em sistemas Win32, "COMSPEC" também será examinado.
SUPORTE
IRC:
Acesse #local-lib em irc.perl.org.
AUTOR DA TRADUÇÃO
Breno G. de Oliveira, "<garu at cpan.org>", após ter perdido uma aposta para o Getty
<http://search.cpan.org/~getty/> durante a Copa de 2010.
COPYRIGHT
Copyright (c) 2007 - 2010 "AUTHOR" in local::lib e "CONTRIBUTORS" in local::lib do local::lib como
listados em local::lib.
LICENÇA
Esta biblioteca é software livre e pode ser distribuída sob os mesmo termos do perl.
perl v5.34.0 2022-04-24 POD2::PT_BR::local::lib(3pm)