Commit | Line | Data |
e681beb3 |
1 | =encoding utf8 |
2 | |
5863e79d |
3 | =head1 NAME |
e681beb3 |
4 | |
c38c8621 |
5 | local::lib~[pt_br] - crie e use um diretório lib/ local para módulos perl com PERL5LIB |
e681beb3 |
6 | |
7 | =head1 SINOPSE |
8 | |
9 | No código - |
10 | |
11 | use local::lib; # configura um lib local em ~/perl5 |
12 | |
13 | use local::lib '~/foo'; # idem, mas ~/foo |
14 | |
15 | # Ou... |
16 | use FindBin; |
17 | use local::lib "$FindBin::Bin/../suporte"; # bibliotecas de suporte locais à aplicação |
18 | |
19 | Pela linha de comando (shell) - |
20 | |
21 | # Instala o LWP e suas dependências não encontradas no diretório '~/perl5' |
22 | perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)' |
23 | |
24 | # Apenas exibe alguns comandos úteis para a shell |
25 | $ perl -Mlocal::lib |
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" |
30 | |
31 | =head2 A técnica de 'bootstrapping' |
32 | |
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. |
37 | |
c38c8621 |
38 | Caso você tenha privilégios de administrador, ainda assim deverá |
39 | configurar suas variáveis de ambiente, como discutido no passo 4, abaixo. |
40 | Sem elas, você ainda instalará módulos no CPAN do sistema e seus scripts |
41 | Perl não utilizarão o caminho para o lib/ que você definiu com o local::lib. |
e681beb3 |
42 | |
43 | Por padrão, o local::lib instala os módulos do CPAN e a si próprio em ~/perl5. |
44 | |
45 | Usuários do Windows devem ler L</Diferenças ao usar esse módulo em Win32>. |
46 | |
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. |
51 | |
52 | 2. Execute isso: |
53 | |
54 | perl Makefile.PL --bootstrap |
55 | |
56 | Caso o sistema pergunte se deve configurar tudo que puder automaticamente, |
57 | você provavelmente deve responder que sim (yes). |
58 | |
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: |
61 | |
62 | perl Makefile.PL --bootstrap=~/foo |
63 | |
64 | 3. Execute isso: (local::lib assume que você possui o comando 'make' |
65 | instalado em seu sistema) |
66 | |
67 | make test && make install |
68 | |
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: |
73 | |
74 | echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc |
75 | |
76 | Caso esteja usando a shell C, pode fazer da seguinte forma: |
77 | |
78 | /bin/csh |
79 | echo $SHELL |
80 | /bin/csh |
81 | perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc |
82 | |
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: |
85 | |
86 | echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc |
87 | |
c38c8621 |
88 | Após atualizar seu arquivo de configuração da shell, certifique-se de |
89 | processá-lo novamente para obter as modificações em sua shell atual. |
90 | Shells Bourne usam C<. ~/.bashrc> para isso, enquanto shells C |
91 | usam C<source ~/.cshrc>. |
e681beb3 |
92 | |
93 | Se estiver em uma máquina lenta ou operando com grandes limitações de |
94 | espaço em disco, você pode desativar a geração automática de manpages a |
95 | partir do POD ao instalar módulos. Para isso, basta passar o argumento |
96 | C<--no-manpages> durante o bootstrap: |
97 | |
98 | perl Makefile.PL --bootstrap --no-manpages |
99 | |
100 | Para evitar ter que fazer vários bootstraps para vários ambientes de |
101 | módulos Perl na mesma conta de usuário - por exemplo se você usa o |
102 | local::lib para desenvolver diferentes aplicativos independentes - |
103 | você pode utilizar uma única instalação bootstrap do local::lib para |
104 | instalar módulos em diretórios diferentes da seguinte forma: |
105 | |
106 | cd ~/meudir1 |
107 | perl -Mlocal::lib=./ |
108 | eval $(perl -Mlocal::lib=./) ### Para configurar o ambiente apenas nessa shell |
109 | printenv ### Veja que o ~/meudir1 está na PERL5LIB |
110 | perl -MCPAN -e install ... ### Os módulos que quiser |
111 | cd ../meudir2 |
112 | ... REPITA ... |
113 | |
c38c8621 |
114 | Para múltiplos ambientes destinados a múltiplos aplicativos, você pode |
115 | precisar incluir uma versão modificada das instruções de C<< use FindBin >> |
116 | no exemplo "No código" acima. Caso tenha feito algo como o que foi descrito |
117 | acima, terá um conjunto de módulos Perl em C<< ~/meudir1/lib >>. Caso |
118 | tenha um script em C<< ~/meudir1/scripts/meuscript.pl >>, você precisará |
119 | indicar a ele onde encontrar os módulos que instalou para ele |
120 | em C<< ~/meudir1/lib >>. |
e681beb3 |
121 | |
122 | Em C<< ~/meudir1/scripts/meuscript.pl >>: |
123 | |
124 | use strict; |
125 | use warnings; |
126 | use local::lib "$FindBin::Bin/.."; ### aponta para ~/meudir1 e o local::lib acha o lib/ |
127 | use lib "$FindBin::Bin/../lib"; ### aponta para ~/meudir1/lib |
128 | |
129 | Coloque isso antes de qualquer bloco BEGIN { ... } que precise dos módulos instalados. |
130 | |
131 | =head2 Diferenças ao usar esse módulo em Win32 |
132 | |
133 | Para configurar as variáveis de ambiente apropriadas para sua sessão atual |
134 | do C<CMD.exe>, você pode fazer assim: |
135 | |
136 | C:\>perl -Mlocal::lib |
137 | set MODULEBUILDRC=C:\DOCUME~1\ADMINI~1\perl5\.modulebuildrc |
138 | set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5 |
139 | set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread |
140 | set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH% |
141 | |
142 | ### Para configurar o ambiente apenas dessa shell |
143 | C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\temp.bat |
144 | ### em vez de $(perl -Mlocal::lib=./) |
145 | |
146 | Caso queira que as configurações do ambiente persistam, você precisará |
147 | adicioná-las em Painel de Controle -> Sistema, ou usar o L<App::local::lib::Win32Helper>. |
148 | |
149 | O "~" é transformado no diretório do perfil do usuário (o diretório com o |
150 | nome do usuário dentro de "Documents and Settings" (Windows XP ou anterior) |
151 | ou "Usuários" (Windows Vista e mais recentes)) a menos que $ENV{HOME} exista. |
152 | Após isso, o nome do diretório é encurtado e os subdiretórios são criados |
153 | (o que significa que o diretório deve existir). |
154 | |
155 | =head1 MOTIVAÇÃO |
156 | |
157 | A versão de um pacote Perl na sua máquina nem sempre é a que você precisa. |
158 | Obviamente, a melhor coisa a fazer seria atualizá-la para a versão desejada. |
159 | No entanto, você pode estar em uma situação que o impede de fazer isso. |
160 | Talvez você não tenha privilégios de administrador do sistema; ou talvez |
161 | esteja usando um sistema de gerenciamento de pacotes como o do Debian, |
162 | e ainda não exista um pacote disponível na versão desejada. |
163 | |
c38c8621 |
164 | local::lib resolve esse problema possibilitando a criação de seu próprio |
e681beb3 |
165 | diretório de pacotes Perl obtidos do CPAN (em sistemas multi-usuário, isso |
166 | normalmente fica dentro do diretório de seu usuário). A instalação do Perl |
167 | no sistema permanece inalterada; você simplesmente chama o Perl com opções |
168 | especiais para que ele use os pacotes em seu diretório local em vez dos |
169 | pacotes do sistema. O local::lib organiza as coisas para que versões dos |
170 | pacotes Perl instalados localmente tenham precedência sobre as do sistema. |
171 | |
172 | Caso esteja usando um sistema de gerenciamento de pacote (como em sistemas |
173 | Debian), não precisará se preocupar com conflitos entre o Debian e o CPAN. |
174 | Sua versão local dos pacotes será instalada em um diretório completamente |
175 | diferente das versões instaladas pelo gerenciador de pacotes do sistema. |
176 | |
177 | =head1 DESCRIÇÃO |
178 | |
179 | Este módulo oferece uma forma rápida e conveniente para criar um repositório |
180 | de módulos locais ao usuário, dentro do diretório do mesmo. Ele também monta |
181 | e exibe para o usuário uma lista de variáveis de ambiente utilizando a |
182 | sintaxe da shell atual do usuário (conforme especificado pela variável |
183 | de ambiente C<SHELL>), pronta para ser adicionada diretamente no arquivo |
184 | de configuração da shell. |
185 | |
186 | Generalizando, o local::lib permite a criação e uso de um diretório contendo |
187 | módulos Perl fora do C<@INC> do Perl. Isso facilita a produção de aplicações |
188 | com uma versão específica de determinado módulo, ou coleção de módulos. |
189 | Também é útil quando o mantenedor de um módulo não aplicou determinado patch |
190 | que você precisa para seu aplicativo. |
191 | |
192 | Durante o C<import>, o local::lib define valores apropriados para as |
193 | seguintes variáveis de ambiente: |
194 | |
195 | =over 4 |
196 | |
197 | =item MODULEBUILDRC |
198 | |
199 | =item PERL_MM_OPT |
200 | |
201 | =item PERL5LIB |
202 | |
203 | =item PATH |
204 | |
205 | valores serão anexados ao PATH, em vez de substituí-lo. |
206 | |
207 | =back |
208 | |
209 | Esses valores são então disponibilizados para referência por qualquer |
210 | outro código após o C<import>. |
211 | |
212 | =head1 CRIANDO UM CONJUNTO AUTO-CONTIDO DE MÓDULOS |
213 | |
214 | Veja L<lib::core::only|lib::core::only> para uma maneira de fazer isso - mas |
215 | note que há uma série de ressalvas na abordagem, e a melhor forma é sempre |
216 | fazer o 'build' contra uma versão limpa do perl (i.e. com 'site' e 'vendor' |
217 | o mais vazios possível). |
218 | |
219 | =head1 MÉTODOS |
220 | |
a949ebcd |
221 | =head2 ensure_dir_structure_for |
e681beb3 |
222 | |
223 | =over 4 |
224 | |
b41e7884 |
225 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
226 | |
b41e7884 |
227 | =item Valor de Retorno: Nenhum |
e681beb3 |
228 | |
229 | =back |
230 | |
231 | Tenta criar o caminho fornecido, e todos os diretórios superiores necessários. Gera uma exceção em caso de falha. |
232 | |
233 | =head2 print_environment_vars_for |
234 | |
235 | =over 4 |
236 | |
b41e7884 |
237 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
238 | |
b41e7884 |
239 | =item Valor de Retorno: Nenhum |
e681beb3 |
240 | |
241 | =back |
242 | |
243 | Exibe na saída padrão as variáveis listadas acima, devidamente ajustadas |
244 | para utilizar o caminho fornecido como diretório base. |
245 | |
a949ebcd |
246 | =head2 build_environment_vars_for |
247 | |
248 | =over 4 |
249 | |
b41e7884 |
250 | =item Argumentos: $caminho_do_diretorio, $interpolar |
a949ebcd |
251 | |
b41e7884 |
252 | =item Valor de Retorno: %variaveis_de_ambiente |
a949ebcd |
253 | |
254 | =back |
255 | |
b41e7884 |
256 | Retorna hash contendo as variáveis de ambiente listadas acima, devidamente |
257 | ajustadas para utilizar o caminho fornecido como diretório base. |
258 | |
e681beb3 |
259 | =head2 setup_env_hash_for |
260 | |
261 | =over 4 |
262 | |
b41e7884 |
263 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
264 | |
b41e7884 |
265 | =item Valor de Retorno: Nenhum |
e681beb3 |
266 | |
267 | =back |
268 | |
269 | Constrói as chaves no C<%ENV> para o caminho fornecido, chamando |
270 | C<build_environment_vars_for>. |
271 | |
272 | =head2 install_base_perl_path |
273 | |
274 | =over 4 |
275 | |
b41e7884 |
276 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
277 | |
b41e7884 |
278 | =item Valor de Retorno: $caminho_base_de_instalacao |
e681beb3 |
279 | |
280 | =back |
281 | |
282 | Retorna um caminho de diretório indicando onde instalar os módulos Perl |
283 | para essa instalação local de bibliotecas. Adiciona os diretórios C<lib> |
284 | e C<perl5> ao final do caminho fornecido. |
285 | |
286 | =head2 install_base_arch_path |
287 | |
288 | =over 4 |
289 | |
b41e7884 |
290 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
291 | |
b41e7884 |
292 | =item Valor de Retorno: $caminho_base_de_instalacao_arch |
e681beb3 |
293 | |
294 | =back |
295 | |
296 | Retorna um caminho de diretório indicando onde instalar os módulos Perl |
297 | de arquiteturas específicas para essa instalação local de bibliotecas. |
298 | Baseia-se no valor de retorno do método L</install_base_perl_path>, |
299 | adicionando o valor de C<$Config{archname}>. |
300 | |
301 | =head2 install_base_bin_path |
302 | |
303 | =over 4 |
304 | |
b41e7884 |
305 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
306 | |
b41e7884 |
307 | =item Valor de Retorno: $caminho_base_de_instalacao_bin |
e681beb3 |
308 | |
309 | =back |
310 | |
311 | Retorna um caminho de diretório indicando onde instalar programas executáveis |
312 | para essa instalação local de bibliotecas. Baseia-se no valor de retorno do |
313 | método L</install_base_perl_path>, adicionando o diretório C<bin>. |
314 | |
315 | =head2 modulebuildrc_path |
316 | |
317 | =over 4 |
318 | |
b41e7884 |
319 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
320 | |
b41e7884 |
321 | =item Valor de Retorno: $caminho_para_modulebuildrc |
e681beb3 |
322 | |
323 | =back |
324 | |
325 | Retorna um caminho de diretório indicando onde instalar o arquivo |
326 | C<.modulebuildrc>, baseado no caminho fornecido. |
327 | |
328 | =head2 resolve_empty_path |
329 | |
330 | =over 4 |
331 | |
b41e7884 |
332 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
333 | |
b41e7884 |
334 | =item Valor de Retorno: $caminho_base_de_instalacao |
e681beb3 |
335 | |
336 | =back |
337 | |
338 | Cria e retorna o caminho de diretório raiz em que a instalação local de |
339 | módulos deve ser feita. O padrão é C<~/perl5>. |
340 | |
341 | =head2 resolve_home_path |
342 | |
343 | =over 4 |
344 | |
b41e7884 |
345 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
346 | |
b41e7884 |
347 | =item Valor de Retorno: $caminho_para_home |
e681beb3 |
348 | |
349 | =back |
350 | |
351 | Procura pelo diretório padrão (home) do usuário. Caso esteja instalado, |
352 | utiliza o C<File::HomeDir> para isso. Gera uma exceção caso não encontre |
353 | resultado definitivo. |
354 | |
355 | =head2 resolve_relative_path |
356 | |
357 | =over 4 |
358 | |
b41e7884 |
359 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
360 | |
b41e7884 |
361 | =item Valor de Retorno: $caminho_absoluto |
e681beb3 |
362 | |
363 | =back |
364 | |
365 | Transforma o caminho fornecido em um caminho absoluto. |
366 | |
367 | =head2 resolve_path |
368 | |
369 | =over 4 |
370 | |
b41e7884 |
371 | =item Argumentos: $caminho_do_diretorio |
a949ebcd |
372 | |
b41e7884 |
373 | =item Valor de Retorno: $caminho_absoluto |
e681beb3 |
374 | |
375 | =back |
376 | |
377 | Invoca os seguintes métodos em sequência, passando o resultado do método |
378 | anterior para o seguinte, na tentativa de descobrir onde configurar o |
379 | ambiente para a instalação local de bibliotecas: L</resolve_empty_path>, |
380 | L</resolve_home_path>, L</resolve_relative_path>. Passa o caminho de |
381 | diretório fornecido para L</resolve_empty_path> que retorna um resultado |
382 | que é passado para L</resolve_home_path>, que então tem seu resultado |
383 | passado para L</resolve_relative_path>. O resultado dessa chamada final |
384 | é então retornado pelo L</resolve_path>. |
385 | |
386 | =head1 UM AVISO SOBRE UNINST=1 |
387 | |
388 | Tenha cuidado ao usar o local::lib em conjunto com "make install UNINST=1". |
389 | A idéia dessa opção é desinstalar a versão anterior de um módulo antes de |
390 | instalar a mais recente. No entanto ela não possui uma verificação de |
391 | segurança de que a versão antiga e a nova referem-se ao mesmo diretório. |
392 | Usada em combinação com o local::lib, você pode potencialmente apagar uma |
393 | versão globalmente acessível de um módulo e instalar a versão mais nova |
394 | no diretório local. Apenas utilize "make install UNINST=1" junto com o |
395 | local::lib se você entende essas possíveis consequências. |
396 | |
397 | =head1 LIMITAÇÕES |
398 | |
399 | As ferramentas auxiliares do perl não conseguem lidar com nomes de |
400 | diretórios contendo espaços, então não é possível fazer seu bootstrap |
401 | do local::lib em um diretório com espaços. O que você pode fazer é mover |
402 | seu local::lib para um diretório com espaços B<após> ter instalado todos |
403 | os módulos dentro dele. Mas esteja ciente que você não poderá atualizar |
404 | ou instalar outros módulos do CPAN nesse diretório local após a mudança. |
405 | |
406 | A detecção da shell é relativamente básica. Neste momento, qualquer coisa |
407 | com csh no nome será tratada como a C shell ou compatível, e todo o resto |
408 | será tratado como Bourne, exceto em sistemas Win32. Caso a variável de |
409 | ambiente C<SHELL> não esteja disponível, assumiremos tratar-se de uma |
410 | shell compatível com a Bourne. |
411 | |
412 | A técnica de bootstrap é um hack e usará o CPAN.pm para o ExtUtils::MakeMaker |
413 | mesmo que você tenha o CPANPLUS instalado. |
414 | |
415 | Destrói qualquer valor pré-existente nas variáveis de ambiente PERL5LIB, |
416 | PERL_MM_OPT e MODULEBUILDRC. |
417 | |
418 | Provavelmente deveria auto-configurar o CPAN caso isso ainda não tenha |
419 | sido feito. |
420 | |
421 | Correções (patches) são muito bem-vindos para quaisquer dos itens acima. |
422 | |
423 | Em sistemas Win32, não há uma forma de escrever no registro as variáveis |
424 | de ambiente criadas, para que elas persistam a uma reinicialização. |
425 | |
426 | =head1 SOLUÇÃO DE PROBLEMAS |
427 | |
428 | Se você configurou o local::lib para instalar módulos do CPAN em algum lugar |
429 | do seu 'home', e mais tarde tentou instalar um módulo fazendo C<cpan -i |
430 | Foo::Bar>, mas ele falhou com um erro como: C<Warning: You do not have |
431 | permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at |
432 | /usr/lib64/perl5/5.8.8/Foo/Bar.pm> e em algum lugar no seu log de instalação |
433 | houver um erro dizendo C<'INSTALL_BASE' is not a known MakeMaker parameter |
434 | name>, então você de alguma forma perdeu seu ExtUtils::MakeMaker atualizado. |
435 | |
436 | Para remediar a situação, execute novamente o procedimento de bootstrap |
437 | descrito acima. |
438 | |
439 | Então, execute C<rm -r ~/.cpan/build/Foo-Bar*> |
440 | |
441 | Finalmente, execute novamente o C<cpan -i Foo::Bar> e ele deve instalar |
442 | sem problemas. |
443 | |
444 | =head1 AMBIENTE |
445 | |
446 | =over 4 |
447 | |
448 | =item SHELL |
449 | |
450 | =item COMSPEC |
451 | |
452 | O local::lib procura pela variável de ambiente C<SHELL> do usuário ao |
453 | processar e exibir os comandos a serem adicionados no arquivo de |
454 | configuração da shell. |
455 | |
456 | Em sistemas Win32, C<COMSPEC> também será examinado. |
457 | |
458 | =back |
459 | |
460 | =head1 SUPORTE |
461 | |
462 | IRC: |
463 | |
464 | Acesse #local-lib em irc.perl.org. |
465 | |
466 | =head1 AUTOR DA TRADUÇÃO |
467 | |
1313d3bf |
468 | Breno G. de Oliveira, C<< <garu at cpan.org> >>, após ter perdido uma aposta |
469 | para o L<Getty|http://search.cpan.org/~getty/> durante a Copa de 2010. |
470 | |
e681beb3 |
471 | |
472 | =head1 COPYRIGHT |
473 | |
c38c8621 |
474 | Copyright (c) 2007 - 2010 L<local::lib/"AUTHOR"> |
475 | e L<local::lib/"CONTRIBUTORS"> do local::lib como listados em L<local::lib>. |
e681beb3 |
476 | |
477 | =head1 LICENÇA |
478 | |
479 | Esta biblioteca é software livre e pode ser distribuída sob os mesmo termos |
480 | do perl. |
481 | |