5 local::lib~[pt_br] - crie e use um lib/ local para módulos perl com PERL5LIB
11 use local::lib; # configura um lib local em ~/perl5
13 use local::lib '~/foo'; # idem, mas ~/foo
17 use local::lib "$FindBin::Bin/../suporte"; # bibliotecas de suporte locais à aplicação
19 Pela linha de comando (shell) -
21 # Instala o LWP e suas dependências não encontradas no diretório '~/perl5'
22 perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
24 # Apenas exibe alguns comandos úteis para a shell
26 export MODULEBUILDRC=/home/username/perl/.modulebuildrc
27 export PERL_MM_OPT='INSTALL_BASE=/home/username/perl'
28 export PERL5LIB='/home/username/perl/lib/perl5:/home/username/perl/lib/perl5/i386-linux'
29 export PATH="/home/username/perl/bin:$PATH"
31 =head2 A técnica de 'bootstrapping'
33 Uma forma comum de instalar o local::lib é usando o que é conhecido como
34 técnica de "bootstrapping". É uma boa abordagem caso seu administrador de
35 sistemas não tenha instalado o local::lib. Nesse caso, você precisará
36 instalar o local::lib em seu diretório de usuário.
38 Caso você tenha privilégios de administrador, você ainda assim deverá
39 configurar suas variáveis de ambiente, como discutido no passo 4. Sem elas,
40 você ainda instalará módulos no CPAN do sistema e seus scripts Perl não
41 utilizarão o caminho para o lib/ que você definiu com o local::lib.
43 Por padrão, o local::lib instala os módulos do CPAN e a si próprio em ~/perl5.
45 Usuários do Windows devem ler L</Diferenças ao usar esse módulo em Win32>.
47 1. Baixe e descompacte o local::lib do CPAN (procure por "Download" na página
48 do CPAN sobre o local::lib). Faça isso como um usuário comum, não como root
49 ou administrador. Descompacte o arquivo em seu diretório de usuário ou em
50 qualquer outro local conveniente.
54 perl Makefile.PL --bootstrap
56 Caso o sistema pergunte se deve configurar tudo que puder automaticamente,
57 você provavelmente deve responder que sim (yes).
59 Para instalar o local::lib em um diretório que não o padrão, você precisará
60 especificá-lo ao chamar o bootstrap, da seguinte forma:
62 perl Makefile.PL --bootstrap=~/foo
64 3. Execute isso: (local::lib assume que você possui o comando 'make'
65 instalado em seu sistema)
67 make test && make install
69 4. Agora precisamos configurar as variáveis de ambiente apropriadas para
70 que o Perl use nosso recém-criado diretório lib/. Caso esteja usando bash
71 ou outra shell Bourne, você pode fazer isso adicionando a seguinte linha
72 em seu script de inicialização da shell:
74 echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
76 Caso esteja usando a shell C, pode fazer da seguinte forma:
81 perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
83 Caso tenha passado para o bootstrap um diretório que não o padrão, você
84 precisará indicá-lo na chamada ao local::lib, dessa forma:
86 echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
88 Após atualizar seu arquivo de configuração da shell, certifique-se de processá-lo
89 novamente para obter as modificações em sua shell atual. Shells Bourne usam
90 C<. ~/.bashrc> para isso, enquanto shells C usam C<source ~/.cshrc>.
92 Se estiver em uma máquina lenta ou operando com grandes limitações de
93 espaço em disco, você pode desativar a geração automática de manpages a
94 partir do POD ao instalar módulos. Para isso, basta passar o argumento
95 C<--no-manpages> durante o bootstrap:
97 perl Makefile.PL --bootstrap --no-manpages
99 Para evitar ter que fazer vários bootstraps para vários ambientes de
100 módulos Perl na mesma conta de usuário - por exemplo se você usa o
101 local::lib para desenvolver diferentes aplicativos independentes -
102 você pode utilizar uma única instalação bootstrap do local::lib para
103 instalar módulos em diretórios diferentes da seguinte forma:
107 eval $(perl -Mlocal::lib=./) ### Para configurar o ambiente apenas nessa shell
108 printenv ### Veja que o ~/meudir1 está na PERL5LIB
109 perl -MCPAN -e install ... ### Os módulos que quiser
113 Para múltiplos ambientes para múltiplos aplicativos você pode precisar incluir
114 uma versão modificada das instruções de C<< use FindBin >> no exemplo
115 "No código" acima. Caso tenha feito algo como o que foi descrito acima, terá
116 um conjunto de módulos Perl em C<< ~/meudir1/lib >>. Caso tenha um script em
117 C<< ~/meudir1/scripts/meuscript.pl >>, você precisará indicar a ele onde
118 encontrar os módulos que instalou para ele em C<< ~/meudir1/lib >>.
120 Em C<< ~/meudir1/scripts/meuscript.pl >>:
124 use local::lib "$FindBin::Bin/.."; ### aponta para ~/meudir1 e o local::lib acha o lib/
125 use lib "$FindBin::Bin/../lib"; ### aponta para ~/meudir1/lib
127 Coloque isso antes de qualquer bloco BEGIN { ... } que precise dos módulos instalados.
129 =head2 Diferenças ao usar esse módulo em Win32
131 Para configurar as variáveis de ambiente apropriadas para sua sessão atual
132 do C<CMD.exe>, você pode fazer assim:
134 C:\>perl -Mlocal::lib
135 set MODULEBUILDRC=C:\DOCUME~1\ADMINI~1\perl5\.modulebuildrc
136 set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
137 set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
138 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
140 ### Para configurar o ambiente apenas dessa shell
141 C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat
142 ### em vez de $(perl -Mlocal::lib=./)
144 Caso queira que as configurações do ambiente persistam, você precisará
145 adicioná-las em Painel de Controle -> Sistema, ou usar o L<App::local::lib::Win32Helper>.
147 O "~" é transformado no diretório do perfil do usuário (o diretório com o
148 nome do usuário dentro de "Documents and Settings" (Windows XP ou anterior)
149 ou "Usuários" (Windows Vista e mais recentes)) a menos que $ENV{HOME} exista.
150 Após isso, o nome do diretório é encurtado e os subdiretórios são criados
151 (o que significa que o diretório deve existir).
155 A versão de um pacote Perl na sua máquina nem sempre é a que você precisa.
156 Obviamente, a melhor coisa a fazer seria atualizá-la para a versão desejada.
157 No entanto, você pode estar em uma situação que o impede de fazer isso.
158 Talvez você não tenha privilégios de administrador do sistema; ou talvez
159 esteja usando um sistema de gerenciamento de pacotes como o do Debian,
160 e ainda não exista um pacote disponível na versão desejada.
162 local::lib resolve esse probleme possibilitando a criação de seu próprio
163 diretório de pacotes Perl obtidos do CPAN (em sistemas multi-usuário, isso
164 normalmente fica dentro do diretório de seu usuário). A instalação do Perl
165 no sistema permanece inalterada; você simplesmente chama o Perl com opções
166 especiais para que ele use os pacotes em seu diretório local em vez dos
167 pacotes do sistema. O local::lib organiza as coisas para que versões dos
168 pacotes Perl instalados localmente tenham precedência sobre as do sistema.
170 Caso esteja usando um sistema de gerenciamento de pacote (como em sistemas
171 Debian), não precisará se preocupar com conflitos entre o Debian e o CPAN.
172 Sua versão local dos pacotes será instalada em um diretório completamente
173 diferente das versões instaladas pelo gerenciador de pacotes do sistema.
177 Este módulo oferece uma forma rápida e conveniente para criar um repositório
178 de módulos locais ao usuário, dentro do diretório do mesmo. Ele também monta
179 e exibe para o usuário uma lista de variáveis de ambiente utilizando a
180 sintaxe da shell atual do usuário (conforme especificado pela variável
181 de ambiente C<SHELL>), pronta para ser adicionada diretamente no arquivo
182 de configuração da shell.
184 Generalizando, o local::lib permite a criação e uso de um diretório contendo
185 módulos Perl fora do C<@INC> do Perl. Isso facilita a produção de aplicações
186 com uma versão específica de determinado módulo, ou coleção de módulos.
187 Também é útil quando o mantenedor de um módulo não aplicou determinado patch
188 que você precisa para seu aplicativo.
190 Durante o C<import>, o local::lib define valores apropriados para as
191 seguintes variáveis de ambiente:
203 valores serão anexados ao PATH, em vez de substituí-lo.
207 Esses valores são então disponibilizados para referência por qualquer
208 outro código após o C<import>.
210 =head1 CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS
212 Veja L<lib::core::only|lib::core::only> para uma maneira de fazer isso - mas
213 note que há uma série de ressalvas na abordagem, e a melhor forma é sempre
214 fazer o 'build' contra uma versão limpa do perl (i.e. com 'site' e 'vendor'
215 o mais vazios possível).
219 =head2 ensure_dir_structure_for
223 =item Argumentos: $path
225 =item Valor de Retorno: None
229 Tenta criar o caminho fornecido, e todos os diretórios superiores necessários. Gera uma exceção em caso de falha.
231 =head2 print_environment_vars_for
235 =item Argumentos: $path
237 =item Valor de Retorno: None
241 Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas
242 para utilizar o caminho fornecido como diretório base.
244 =head2 build_environment_vars_for
248 =item Argumentos: $path, $interpolate
250 =item Valor de Retorno: \%environment_vars
254 =head2 setup_env_hash_for
258 =item Argumentos: $path
260 =item Valor de Retorno: None
264 Constrói as chaves no C<%ENV> para o caminho fornecido, chamando
265 C<build_environment_vars_for>.
267 =head2 install_base_perl_path
271 =item Argumentos: $path
273 =item Valor de Retorno: $install_base_perl_path
277 Retorna um caminho de diretório indicando onde instalar os módulos Perl
278 para essa instalação local de bibliotecas. Adiciona os diretórios C<lib>
279 e C<perl5> ao final do caminho fornecido.
281 =head2 install_base_arch_path
285 =item Argumentos: $path
287 =item Valor de Retorno: $install_base_arch_path
291 Retorna um caminho de diretório indicando onde instalar os módulos Perl
292 de arquiteturas específicas para essa instalação local de bibliotecas.
293 Baseia-se no valor de retorno do método L</install_base_perl_path>,
294 adicionando o valor de C<$Config{archname}>.
296 =head2 install_base_bin_path
300 =item Argumentos: $path
302 =item Valor de Retorno: $install_base_bin_path
306 Retorna um caminho de diretório indicando onde instalar programas executáveis
307 para essa instalação local de bibliotecas. Baseia-se no valor de retorno do
308 método L</install_base_perl_path>, adicionando o diretório C<bin>.
310 =head2 modulebuildrc_path
314 =item Argumentos: $path
316 =item Valor de Retorno: $modulebuildrc_path
320 Retorna um caminho de diretório indicando onde instalar o arquivo
321 C<.modulebuildrc>, baseado no caminho fornecido.
323 =head2 resolve_empty_path
327 =item Argumentos: $path
329 =item Valor de Retorno: $base_path
333 Cria e retorna o caminho de diretório raiz em que a instalação local de
334 módulos deve ser feita. O padrão é C<~/perl5>.
336 =head2 resolve_home_path
340 =item Argumentos: $path
342 =item Valor de Retorno: $home_path
346 Procura pelo diretório padrão (home) do usuário. Caso esteja instalado,
347 utiliza o C<File::HomeDir> para isso. Gera uma exceção caso não encontre
348 resultado definitivo.
350 =head2 resolve_relative_path
354 =item Argumentos: $path
356 =item Valor de Retorno: $absolute_path
360 Transforma o caminho fornecido em um caminho absoluto.
366 =item Argumentos: $path
368 =item Valor de Retorno: $absolute_path
372 Invoca os seguintes métodos em sequência, passando o resultado do método
373 anterior para o seguinte, na tentativa de descobrir onde configurar o
374 ambiente para a instalação local de bibliotecas: L</resolve_empty_path>,
375 L</resolve_home_path>, L</resolve_relative_path>. Passa o caminho de
376 diretório fornecido para L</resolve_empty_path> que retorna um resultado
377 que é passado para L</resolve_home_path>, que então tem seu resultado
378 passado para L</resolve_relative_path>. O resultado dessa chamada final
379 é então retornado pelo L</resolve_path>.
381 =head1 UM AVISO SOBRE UNINST=1
383 Tenha cuidado ao usar o local::lib em conjunto com "make install UNINST=1".
384 A idéia dessa opção é desinstalar a versão anterior de um módulo antes de
385 instalar a mais recente. No entanto ela não possui uma verificação de
386 segurança de que a versão antiga e a nova referem-se ao mesmo diretório.
387 Usada em combinação com o local::lib, você pode potencialmente apagar uma
388 versão globalmente acessível de um módulo e instalar a versão mais nova
389 no diretório local. Apenas utilize "make install UNINST=1" junto com o
390 local::lib se você entende essas possíveis consequências.
394 As ferramentas auxiliares do perl não conseguem lidar com nomes de
395 diretórios contendo espaços, então não é possível fazer seu bootstrap
396 do local::lib em um diretório com espaços. O que você pode fazer é mover
397 seu local::lib para um diretório com espaços B<após> ter instalado todos
398 os módulos dentro dele. Mas esteja ciente que você não poderá atualizar
399 ou instalar outros módulos do CPAN nesse diretório local após a mudança.
401 A detecção da shell é relativamente básica. Neste momento, qualquer coisa
402 com csh no nome será tratada como a C shell ou compatível, e todo o resto
403 será tratado como Bourne, exceto em sistemas Win32. Caso a variável de
404 ambiente C<SHELL> não esteja disponível, assumiremos tratar-se de uma
405 shell compatível com a Bourne.
407 A técnica de bootstrap é um hack e usará o CPAN.pm para o ExtUtils::MakeMaker
408 mesmo que você tenha o CPANPLUS instalado.
410 Destrói qualquer valor pré-existente nas variáveis de ambiente PERL5LIB,
411 PERL_MM_OPT e MODULEBUILDRC.
413 Provavelmente deveria auto-configurar o CPAN caso isso ainda não tenha
416 Correções (patches) são muito bem-vindos para quaisquer dos itens acima.
418 Em sistemas Win32, não há uma forma de escrever no registro as variáveis
419 de ambiente criadas, para que elas persistam a uma reinicialização.
421 =head1 SOLUÇÃO DE PROBLEMAS
423 Se você configurou o local::lib para instalar módulos do CPAN em algum lugar
424 do seu 'home', e mais tarde tentou instalar um módulo fazendo C<cpan -i
425 Foo::Bar>, mas ele falhou com um erro como: C<Warning: You do not have
426 permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
427 /usr/lib64/perl5/5.8.8/Foo/Bar.pm> e em algum lugar no seu log de instalação
428 houver um erro dizendo C<'INSTALL_BASE' is not a known MakeMaker parameter
429 name>, então você de alguma forma perdeu seu ExtUtils::MakeMaker atualizado.
431 Para remediar a situação, execute novamente o procedimento de bootstrap
434 Então, execute C<rm -r ~/.cpan/build/Foo-Bar*>
436 Finalmente, execute novamente o C<cpan -i Foo::Bar> e ele deve instalar
447 O local::lib procura pela variável de ambiente C<SHELL> do usuário ao
448 processar e exibir os comandos a serem adicionados no arquivo de
449 configuração da shell.
451 Em sistemas Win32, C<COMSPEC> também será examinado.
459 Acesse #local-lib em irc.perl.org.
461 =head1 AUTOR DA TRADUÇÃO
463 Breno G. de Oliveira, C<< <garu at cpan.org> >>, após ter perdido uma aposta
464 para o L<Getty|http://search.cpan.org/~getty/> durante a Copa de 2010.
469 Copyright (c) 2007 - 2010 L</AUTOR> e L</COLABORADORES> do local::lib como
470 listados em L<local::lib>.
474 Esta biblioteca é software livre e pode ser distribuída sob os mesmo termos