Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "local::lib 3" |
132 | .TH local::lib 3 "2009-11-08" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | local::lib \- create and use a local lib/ for perl modules with PERL5LIB |
135 | .SH "SYNOPSIS" |
136 | .IX Header "SYNOPSIS" |
137 | In code \- |
138 | .PP |
139 | .Vb 1 |
140 | \& use local::lib; # sets up a local lib at ~/perl5 |
141 | .Ve |
142 | .PP |
143 | .Vb 1 |
144 | \& use local::lib '~/foo'; # same, but ~/foo |
145 | .Ve |
146 | .PP |
147 | .Vb 3 |
148 | \& # Or... |
149 | \& use FindBin; |
150 | \& use local::lib "$FindBin::Bin/../support"; # app\-local support library |
151 | .Ve |
152 | .PP |
153 | From the shell \- |
154 | .PP |
155 | .Vb 2 |
156 | \& # Install LWP and it's missing dependencies to the 'my_lwp' directory |
157 | \& perl \-MCPAN \-Mlocal::lib=my_lwp \-e 'CPAN::install(LWP)' |
158 | .Ve |
159 | .PP |
160 | .Vb 2 |
161 | \& # Install LWP and *all non\-core* dependencies to the 'my_lwp' directory |
162 | \& perl \-MCPAN \-Mlocal::lib=\-\-self\-contained,my_lwp \-e 'CPAN::install(LWP)' |
163 | .Ve |
164 | .PP |
165 | .Vb 6 |
166 | \& # Just print out useful shell commands |
167 | \& $ perl \-Mlocal::lib |
168 | \& export MODULEBUILDRC=/home/username/perl/.modulebuildrc |
169 | \& export PERL_MM_OPT='INSTALL_BASE=/home/username/perl' |
170 | \& export PERL5LIB='/home/username/perl/lib/perl5:/home/username/perl/lib/perl5/i386\-linux' |
171 | \& export PATH="/home/username/perl/bin:$PATH" |
172 | .Ve |
173 | .Sh "The bootstrapping technique" |
174 | .IX Subsection "The bootstrapping technique" |
175 | A typical way to install local::lib is using what is known as the |
176 | \&\*(L"bootstrapping\*(R" technique. You would do this if your system administrator |
177 | hasn't already installed local::lib. In this case, you'll need to install |
178 | local::lib in your home directory. |
179 | .PP |
180 | 1. Download and unpack the local::lib tarball from \s-1CPAN\s0 (search for \*(L"Download\*(R" |
181 | on the \s-1CPAN\s0 page about local::lib). Do this as an ordinary user, not as root |
182 | or administrator. Unpack the file in your home directory or in any other |
183 | convenient location. |
184 | .PP |
185 | 2. Run this: |
186 | .PP |
187 | .Vb 1 |
188 | \& perl Makefile.PL \-\-bootstrap |
189 | .Ve |
190 | .PP |
191 | If the system asks you whether it should automatically configure as much |
192 | as possible, you would typically answer yes. |
193 | .PP |
194 | 3. Run this: |
195 | .PP |
196 | .Vb 1 |
197 | \& make test && make install |
198 | .Ve |
199 | .PP |
200 | 4. Arrange for Perl to use your own packages instead of the system |
201 | packages. If you are using bash, you can do this as follows: |
202 | .PP |
203 | .Vb 1 |
204 | \& echo 'eval $(perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib)' >>~/.bashrc |
205 | .Ve |
206 | .PP |
207 | If you are using C shell, you can do this as follows: |
208 | .PP |
209 | .Vb 4 |
210 | \& /bin/csh |
211 | \& echo $SHELL |
212 | \& /bin/csh |
213 | \& perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib >> ~/.cshrc |
214 | .Ve |
215 | .PP |
216 | You can also pass \-\-bootstrap=~/foo to get a different location \- |
217 | .PP |
218 | .Vb 2 |
219 | \& perl Makefile.PL \-\-bootstrap=~/foo |
220 | \& make test && make install |
221 | .Ve |
222 | .PP |
223 | .Vb 1 |
224 | \& echo 'eval $(perl \-I$HOME/foo/lib/perl5 \-Mlocal::lib=$HOME/foo)' >>~/.bashrc |
225 | .Ve |
226 | .PP |
227 | After writing your shell configuration file, be sure to re-read it to get the |
228 | changed settings into your current shell's environment. |
229 | .PP |
230 | .Vb 1 |
231 | \& . ~/.bashrc |
232 | .Ve |
233 | .PP |
234 | If you are using C shell, you can do this as follows: |
235 | .PP |
236 | .Vb 4 |
237 | \& /bin/csh |
238 | \& echo $SHELL |
239 | \& /bin/csh |
240 | \& perl \-I$HOME/perl5/lib/perl5 \-Mlocal::lib >> ~/.cshrc |
241 | .Ve |
242 | .PP |
243 | .Vb 1 |
244 | \& source ~/.cshrc |
245 | .Ve |
246 | .PP |
247 | You can also pass \-\-bootstrap=~/foo to get a different location \- |
248 | .PP |
249 | .Vb 2 |
250 | \& perl Makefile.PL \-\-bootstrap=~/foo |
251 | \& make test && make install |
252 | .Ve |
253 | .PP |
254 | .Vb 1 |
255 | \& echo 'eval $(perl \-I$HOME/foo/lib/perl5 \-Mlocal::lib=$HOME/foo)' >> ~/.bashrc |
256 | .Ve |
257 | .PP |
258 | .Vb 1 |
259 | \& . ~/.bashrc |
260 | .Ve |
261 | .PP |
262 | If you're on a slower machine, or are operating under draconian disk space |
263 | limitations, you can disable the automatic generation of manpages from \s-1POD\s0 when |
264 | installing modules by using the \f(CW\*(C`\-\-no\-manpages\*(C'\fR argument when bootstrapping: |
265 | .PP |
266 | .Vb 1 |
267 | \& perl Makefile.PL \-\-bootstrap \-\-no\-manpages |
268 | .Ve |
269 | .PP |
270 | If you want to install multiple Perl module environments, say for application evelopment, |
271 | install local::lib globally and then: |
272 | .PP |
273 | .Vb 7 |
274 | \& cd ~/mydir1 |
275 | \& perl \-Mlocal::lib=./ |
276 | \& eval $(perl \-Mlocal::lib=./) ### To set the environment for this shell alone |
277 | \& printenv ### You will see that ~/mydir1 is in the PERL5LIB |
278 | \& perl \-MCPAN \-e install ... ### whatever modules you want |
279 | \& cd ../mydir2 |
280 | \& ... REPEAT ... |
281 | .Ve |
282 | .PP |
283 | For multiple environments for multiple apps you may need to include a modified |
284 | version of the \f(CW\*(C`use FindBin\*(C'\fR instructions in the \*(L"In code\*(R" sample above. |
285 | If you did something like the above, you have a set of Perl modules at \f(CW\*(C`~/mydir1/lib\*(C'\fR. If you have a script at \f(CW\*(C`~/mydir1/scripts/myscript.pl\*(C'\fR, |
286 | you need to tell it where to find the modules you installed for it at \f(CW\*(C`~/mydir1/lib\*(C'\fR. |
287 | .PP |
288 | In \f(CW\*(C`~/mydir1/scripts/myscript.pl\*(C'\fR: |
289 | .PP |
290 | .Vb 4 |
291 | \& use strict; |
292 | \& use warnings; |
293 | \& use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib |
294 | \& use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib |
295 | .Ve |
296 | .PP |
297 | Put this before any \s-1BEGIN\s0 { ... } blocks that require the modules you installed. |
298 | .Sh "Differences when using this module under Win32" |
299 | .IX Subsection "Differences when using this module under Win32" |
300 | .Vb 5 |
301 | \& C:\e>perl \-Mlocal::lib |
302 | \& set MODULEBUILDRC=C:\eDOCUME~1\eADMINI~1\eperl5\e.modulebuildrc |
303 | \& set PERL_MM_OPT=INSTALL_BASE=C:\eDOCUME~1\eADMINI~1\eperl5 |
304 | \& set PERL5LIB=C:\eDOCUME~1\eADMINI~1\eperl5\elib\eperl5;C:\eDOCUME~1\eADMINI~1\eperl5\elib\eperl5\eMSWin32\-x86\-multi\-thread |
305 | \& set PATH=C:\eDOCUME~1\eADMINI~1\eperl5\ebin;%PATH% |
306 | .Ve |
307 | .PP |
308 | .Vb 3 |
309 | \& ### To set the environment for this shell alone |
310 | \& C:\e>perl \-Mlocal::lib > %TEMP%\etmp.bat && %TEMP%\etmp.bat && del %TEMP%\etemp.bat |
311 | \& ### instead of $(perl \-Mlocal::lib=./) |
312 | .Ve |
313 | .PP |
314 | If you want the environment entries to persist, you'll need to add then to the |
315 | Control Panel's System applet yourself at the moment. |
316 | .PP |
317 | The \*(L"~\*(R" is translated to the user's profile directory (the directory named for |
318 | the user under \*(L"Documents and Settings\*(R" (Windows \s-1XP\s0 or earlier) or \*(L"Users\*(R" |
319 | (Windows Vista or later) unless \f(CW$ENV\fR{\s-1HOME\s0} exists. After that, the home |
320 | directory is translated to a short name (which means the directory must exist) |
321 | and the subdirectories are created. |
322 | .SH "RATIONALE" |
323 | .IX Header "RATIONALE" |
324 | The version of a Perl package on your machine is not always the version you |
325 | need. Obviously, the best thing to do would be to update to the version you |
326 | need. However, you might be in a situation where you're prevented from doing |
327 | this. Perhaps you don't have system administrator privileges; or perhaps you |
328 | are using a package management system such as Debian, and nobody has yet gotten |
329 | around to packaging up the version you need. |
330 | .PP |
331 | local::lib solves this problem by allowing you to create your own directory of |
332 | Perl packages downloaded from \s-1CPAN\s0 (in a multi-user system, this would typically |
333 | be within your own home directory). The existing system Perl installation is |
334 | not affected; you simply invoke Perl with special options so that Perl uses the |
335 | packages in your own local package directory rather than the system packages. |
336 | local::lib arranges things so that your locally installed version of the Perl |
337 | packages takes precedence over the system installation. |
338 | .PP |
339 | If you are using a package management system (such as Debian), you don't need to |
340 | worry about Debian and \s-1CPAN\s0 stepping on each other's toes. Your local version |
341 | of the packages will be written to an entirely separate directory from those |
342 | installed by Debian. |
343 | .SH "DESCRIPTION" |
344 | .IX Header "DESCRIPTION" |
345 | This module provides a quick, convenient way of bootstrapping a user-local Perl |
346 | module library located within the user's home directory. It also constructs and |
347 | prints out for the user the list of environment variables using the syntax |
348 | appropriate for the user's current shell (as specified by the \f(CW\*(C`SHELL\*(C'\fR |
349 | environment variable), suitable for directly adding to one's shell |
350 | configuration file. |
351 | .PP |
352 | More generally, local::lib allows for the bootstrapping and usage of a |
353 | directory containing Perl modules outside of Perl's \f(CW@INC\fR. This makes it |
354 | easier to ship an application with an app-specific copy of a Perl module, or |
355 | collection of modules. Useful in cases like when an upstream maintainer hasn't |
356 | applied a patch to a module of theirs that you need for your application. |
357 | .PP |
358 | On import, local::lib sets the following environment variables to appropriate |
359 | values: |
360 | .IP "\s-1MODULEBUILDRC\s0" 4 |
361 | .IX Item "MODULEBUILDRC" |
362 | .PD 0 |
363 | .IP "\s-1PERL_MM_OPT\s0" 4 |
364 | .IX Item "PERL_MM_OPT" |
365 | .IP "\s-1PERL5LIB\s0" 4 |
366 | .IX Item "PERL5LIB" |
367 | .IP "\s-1PATH\s0" 4 |
368 | .IX Item "PATH" |
369 | .PD |
370 | \&\s-1PATH\s0 is appended to, rather than clobbered. |
371 | .PP |
372 | These values are then available for reference by any code after import. |
373 | .SH "METHODS" |
374 | .IX Header "METHODS" |
375 | .Sh "ensure_directory_structure_for" |
376 | .IX Subsection "ensure_directory_structure_for" |
377 | .IP "Arguments: path" 4 |
378 | .IX Item "Arguments: path" |
379 | .PP |
380 | Attempts to create the given path, and all required parent directories. Throws |
381 | an exception on failure. |
382 | .Sh "print_environment_vars_for" |
383 | .IX Subsection "print_environment_vars_for" |
384 | .IP "Arguments: path" 4 |
385 | .IX Item "Arguments: path" |
386 | .PP |
387 | Prints to standard output the variables listed above, properly set to use the |
388 | given path as the base directory. |
389 | .Sh "setup_env_hash_for" |
390 | .IX Subsection "setup_env_hash_for" |
391 | .IP "Arguments: path" 4 |
392 | .IX Item "Arguments: path" |
393 | .PP |
394 | Constructs the \f(CW%ENV\fR keys for the given path, by calling |
395 | \&\f(CW\*(C`build_environment_vars_for\*(C'\fR. |
396 | .Sh "install_base_perl_path" |
397 | .IX Subsection "install_base_perl_path" |
398 | .IP "Arguments: path" 4 |
399 | .IX Item "Arguments: path" |
400 | .PP |
401 | Returns a path describing where to install the Perl modules for this local |
402 | library installation. Appends the directories \f(CW\*(C`lib\*(C'\fR and \f(CW\*(C`perl5\*(C'\fR to the given |
403 | path. |
404 | .Sh "install_base_arch_path" |
405 | .IX Subsection "install_base_arch_path" |
406 | .IP "Arguments: path" 4 |
407 | .IX Item "Arguments: path" |
408 | .PP |
409 | Returns a path describing where to install the architecture-specific Perl |
410 | modules for this local library installation. Based on the |
411 | \&\*(L"install_base_perl_path\*(R" method's return value, and appends the value of |
412 | \&\f(CW$Config{archname}\fR. |
413 | .Sh "install_base_bin_path" |
414 | .IX Subsection "install_base_bin_path" |
415 | .IP "Arguments: path" 4 |
416 | .IX Item "Arguments: path" |
417 | .PP |
418 | Returns a path describing where to install the executable programs for this |
419 | local library installation. Based on the \*(L"install_base_perl_path\*(R" method's |
420 | return value, and appends the directory \f(CW\*(C`bin\*(C'\fR. |
421 | .Sh "modulebuildrc_path" |
422 | .IX Subsection "modulebuildrc_path" |
423 | .IP "Arguments: path" 4 |
424 | .IX Item "Arguments: path" |
425 | .PP |
426 | Returns a path describing where to install the \f(CW\*(C`.modulebuildrc\*(C'\fR file, based on |
427 | the given path. |
428 | .Sh "resolve_empty_path" |
429 | .IX Subsection "resolve_empty_path" |
430 | .IP "Arguments: path" 4 |
431 | .IX Item "Arguments: path" |
432 | .PP |
433 | Builds and returns the base path into which to set up the local module |
434 | installation. Defaults to \f(CW\*(C`~/perl5\*(C'\fR. |
435 | .Sh "resolve_home_path" |
436 | .IX Subsection "resolve_home_path" |
437 | .IP "Arguments: path" 4 |
438 | .IX Item "Arguments: path" |
439 | .PP |
440 | Attempts to find the user's home directory. If installed, uses \f(CW\*(C`File::HomeDir\*(C'\fR |
441 | for this purpose. If no definite answer is available, throws an exception. |
442 | .Sh "resolve_relative_path" |
443 | .IX Subsection "resolve_relative_path" |
444 | .IP "Arguments: path" 4 |
445 | .IX Item "Arguments: path" |
446 | .PP |
447 | Translates the given path into an absolute path. |
448 | .Sh "resolve_path" |
449 | .IX Subsection "resolve_path" |
450 | .IP "Arguments: path" 4 |
451 | .IX Item "Arguments: path" |
452 | .PP |
453 | Calls the following in a pipeline, passing the result from the previous to the |
454 | next, in an attempt to find where to configure the environment for a local |
455 | library installation: \*(L"resolve_empty_path\*(R", \*(L"resolve_home_path\*(R", |
456 | \&\*(L"resolve_relative_path\*(R". Passes the given path argument to |
457 | \&\*(L"resolve_empty_path\*(R" which then returns a result that is passed to |
458 | \&\*(L"resolve_home_path\*(R", which then has its result passed to |
459 | \&\*(L"resolve_relative_path\*(R". The result of this final call is returned from |
460 | \&\*(L"resolve_path\*(R". |
461 | .SH "A WARNING ABOUT UNINST=1" |
462 | .IX Header "A WARNING ABOUT UNINST=1" |
463 | Be careful about using local::lib in combination with \*(L"make install UNINST=1\*(R". |
464 | The idea of this feature is that will uninstall an old version of a module |
465 | before installing a new one. However it lacks a safety check that the old |
466 | version and the new version will go in the same directory. Used in combination |
467 | with local::lib, you can potentially delete a globally accessible version of a |
468 | module while installing the new version in a local place. Only combine \*(L"make |
469 | install UNINST=1\*(R" and local::lib if you understand these possible consequences. |
470 | .SH "LIMITATIONS" |
471 | .IX Header "LIMITATIONS" |
472 | Rather basic shell detection. Right now anything with csh in its name is |
473 | assumed to be a C shell or something compatible, and everything else is assumed |
474 | to be Bourne, except on Win32 systems. If the \f(CW\*(C`SHELL\*(C'\fR environment variable is |
475 | not set, a Bourne-compatible shell is assumed. |
476 | .PP |
477 | Bootstrap is a hack and will use \s-1CPAN\s0.pm for ExtUtils::MakeMaker even if you |
478 | have \s-1CPANPLUS\s0 installed. |
479 | .PP |
480 | Kills any existing \s-1PERL5LIB\s0, \s-1PERL_MM_OPT\s0 or \s-1MODULEBUILDRC\s0. |
481 | .PP |
482 | Should probably auto-fixup \s-1CPAN\s0 config if not already done. |
483 | .PP |
484 | Patches very much welcome for any of the above. |
485 | .PP |
486 | On Win32 systems, does not have a way to write the created environment variables |
487 | to the registry, so that they can persist through a reboot. |
488 | .SH "TROUBLESHOOTING" |
489 | .IX Header "TROUBLESHOOTING" |
490 | If you've configured local::lib to install \s-1CPAN\s0 modules somewhere in to your |
491 | home directory, and at some point later you try to install a module with \f(CW\*(C`cpan |
492 | \&\-i Foo::Bar\*(C'\fR, but it fails with an error like: \f(CW\*(C`Warning: You do not have |
493 | permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64\-linux at |
494 | /usr/lib64/perl5/5.8.8/Foo/Bar.pm\*(C'\fR and buried within the install log is an |
495 | error saying \f(CW\*(C`'INSTALL_BASE' is not a known MakeMaker parameter name\*(C'\fR, then |
496 | you've somehow lost your updated ExtUtils::MakeMaker module. |
497 | .PP |
498 | To remedy this situation, rerun the bootstrapping procedure documented above. |
499 | .PP |
500 | Then, run \f(CW\*(C`rm \-r ~/.cpan/build/Foo\-Bar*\*(C'\fR |
501 | .PP |
502 | Finally, re-run \f(CW\*(C`cpan \-i Foo::Bar\*(C'\fR and it should install without problems. |
503 | .SH "ENVIRONMENT" |
504 | .IX Header "ENVIRONMENT" |
505 | .IP "\s-1SHELL\s0" 4 |
506 | .IX Item "SHELL" |
507 | .PD 0 |
508 | .IP "\s-1COMSPEC\s0" 4 |
509 | .IX Item "COMSPEC" |
510 | .PD |
511 | local::lib looks at the user's \f(CW\*(C`SHELL\*(C'\fR environment variable when printing out |
512 | commands to add to the shell configuration file. |
513 | .Sp |
514 | On Win32 systems, \f(CW\*(C`COMSPEC\*(C'\fR is also examined. |
515 | .SH "AUTHOR" |
516 | .IX Header "AUTHOR" |
517 | Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/ |
518 | .PP |
519 | auto_install fixes kindly sponsored by http://www.takkle.com/ |
520 | .SH "CONTRIBUTORS" |
521 | .IX Header "CONTRIBUTORS" |
522 | Chris Nehren <apeiron@cpan.org> now oversees maintenance of local::lib, in |
523 | addition to providing doc patches and bootstrap fixes to prevent users from |
524 | shooting themselves in the foot (it's more likely than you think). |
525 | .PP |
526 | Patches to correctly output commands for csh style shells, as well as some |
527 | documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>. |
528 | .PP |
529 | \&'\-\-self\-contained' feature contributed by Mark Stosberg <mark@summersault.com>. |
530 | .PP |
531 | Ability to pass '\-\-self\-contained' without a directory inspired by frew on |
532 | irc.perl.org/#catalyst. |
533 | .PP |
534 | Doc patches for a custom local::lib directory contributed by Torsten Raudssus |
535 | <torsten@raudssus.de>. |
536 | .PP |
537 | Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring |
538 | things will install properly, submitted a fix for the bug causing problems with |
539 | writing Makefiles during bootstrapping, contributed an example program, and |
540 | submitted yet another fix to ensure that local::lib can install and bootstrap |
541 | properly. Many, many thanks! |
542 | .PP |
543 | pattern of Freenode \s-1IRC\s0 contributed the beginnings of the Troubleshooting |
544 | section. Many thanks! |
545 | .PP |
546 | Patch to add Win32 support contributed by Curtis Jewell <csjewell@cpan.org>. |
547 | .PP |
548 | kgish/#perl\-help@irc.perl.org suggested revamping the section on sourcing the |
549 | shell file to make it clearer to those quickly reading the \s-1POD\s0. |
550 | .PP |
551 | t0m and chrisa on #local\-lib@irc.perl.org pointed out a \s-1PERL5LIB\s0 ordering issue |
552 | with \f(CW\*(C`\-\-self\-contained\*(C'\fR. |
553 | .SH "COPYRIGHT" |
554 | .IX Header "COPYRIGHT" |
555 | Copyright (c) 2007 \- 2009 the local::lib \*(L"\s-1AUTHOR\s0\*(R" and \*(L"\s-1CONTRIBUTORS\s0\*(R" as |
556 | listed above. |
557 | .SH "LICENSE" |
558 | .IX Header "LICENSE" |
559 | This library is free software and may be distributed under the same terms |
560 | as perl itself. |