1local::lib(3) User Contributed Perl Documentation local::lib(3)
2
6 local::lib - create and use a local lib/ for perl modules with PERL5LIB
7
9 In code -
10 use local::lib; # sets up a local lib at ~/perl5
12 use local::lib '~/foo'; # same, but ~/foo
14 # Or...
16 use FindBin;
17 use local::lib "$FindBin::Bin/../support"; # app-local support library
18 From the shell -
20 # Install LWP and its missing dependencies to the '~/perl5' directory
22 perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
23 # Just print out useful shell commands
25 $ perl -Mlocal::lib
26 PERL_MB_OPT='--install_base /home/username/perl5'; export PERL_MB_OPT;
27 PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'; export PERL_MM_OPT;
28 PERL5LIB="/home/username/perl5/lib/perl5"; export PERL5LIB;
29 PATH="/home/username/perl5/bin:$PATH"; export PATH;
30 PERL_LOCAL_LIB_ROOT="/home/usename/perl5:$PERL_LOCAL_LIB_ROOT"; export PERL_LOCAL_LIB_ROOT;
31 From a .bash_profile or .bashrc file -
33 eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
35 The bootstrapping technique
37 A typical way to install local::lib is using what is known as the
38 "bootstrapping" technique. You would do this if your system
39 administrator hasn't already installed local::lib. In this case,
40 you'll need to install local::lib in your home directory.
41 Even if you do have administrative privileges, you will still want to
43 set up your environment variables, as discussed in step 4. Without
44 this, you would still install the modules into the system CPAN
45 installation and also your Perl scripts will not use the lib/ path you
46 bootstrapped with local::lib.
47 By default local::lib installs itself and the CPAN modules into
49 ~/perl5.
50 Windows users must also see "Differences when using this module under
52 Win32".
53 1. Download and unpack the local::lib tarball from CPAN (search for
55 "Download" on the CPAN page about local::lib). Do this as an
56 ordinary user, not as root or administrator. Unpack the file in
57 your home directory or in any other convenient location.
58 2. Run this:
60 perl Makefile.PL --bootstrap
62 If the system asks you whether it should automatically configure as
64 much as possible, you would typically answer yes.
65 In order to install local::lib into a directory other than the
67 default, you need to specify the name of the directory when you
68 call bootstrap, as follows:
69 perl Makefile.PL --bootstrap=~/foo
71 3. Run this: (local::lib assumes you have make installed on your
73 system)
74 make test && make install
76 4. Now we need to setup the appropriate environment variables, so that
78 Perl starts using our newly generated lib/ directory. If you are
79 using bash or any other Bourne shells, you can add this to your
80 shell startup script this way:
81 echo 'eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc
83 If you are using C shell, you can do this as follows:
85 /bin/csh
87 echo $SHELL
88 /bin/csh
89 echo 'eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >> ~/.cshrc
90 If you passed to bootstrap a directory other than default, you also
92 need to give that as import parameter to the call of the local::lib
93 module like this way:
94 echo 'eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc
96 After writing your shell configuration file, be sure to re-read it
98 to get the changed settings into your current shell's environment.
99 Bourne shells use ". ~/.bashrc" for this, whereas C shells use
100 "source ~/.cshrc".
101 If you're on a slower machine, or are operating under draconian disk
103 space limitations, you can disable the automatic generation of manpages
104 from POD when installing modules by using the "--no-manpages" argument
105 when bootstrapping:
106 perl Makefile.PL --bootstrap --no-manpages
108 To avoid doing several bootstrap for several Perl module environments
110 on the same account, for example if you use it for several different
111 deployed applications independently, you can use one bootstrapped
112 local::lib installation to install modules in different directories
113 directly this way:
114 cd ~/mydir1
116 perl -Mlocal::lib=./
117 eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone
118 printenv ### You will see that ~/mydir1 is in the PERL5LIB
119 perl -MCPAN -e install ... ### whatever modules you want
120 cd ../mydir2
121 ... REPEAT ...
122 If you use .bashrc to activate a local::lib automatically, the
124 local::lib will be re-enabled in any sub-shells used, overriding
125 adjustments you may have made in the parent shell. To avoid this, you
126 can initialize the local::lib in .bash_profile rather than .bashrc, or
127 protect the local::lib invocation with a $SHLVL check:
128 [ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
130 If you are working with several "local::lib" environments, you may want
132 to remove some of them from the current environment without disturbing
133 the others. You can deactivate one environment like this (using bourne
134 sh):
135 eval $(perl -Mlocal::lib=--deactivate,~/path)
137 which will generate and run the commands needed to remove "~/path" from
139 your various search paths. Whichever environment was activated most
140 recently will remain the target for module installations. That is, if
141 you activate "~/path_A" and then you activate "~/path_B", new modules
142 you install will go in "~/path_B". If you deactivate "~/path_B" then
143 modules will be installed into "~/pathA" -- but if you deactivate
144 "~/path_A" then they will still be installed in "~/pathB" because pathB
145 was activated later.
146 You can also ask "local::lib" to clean itself completely out of the
148 current shell's environment with the "--deactivate-all" option. For
149 multiple environments for multiple apps you may need to include a
150 modified version of the "use FindBin" instructions in the "In code"
151 sample above. If you did something like the above, you have a set of
152 Perl modules at "~/mydir1/lib". If you have a script at
153 "~/mydir1/scripts/myscript.pl", you need to tell it where to find the
154 modules you installed for it at "~/mydir1/lib".
155 In "~/mydir1/scripts/myscript.pl":
157 use strict;
159 use warnings;
160 use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib
161 use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib
162 Put this before any BEGIN { ... } blocks that require the modules you
164 installed.
165 Differences when using this module under Win32
167 To set up the proper environment variables for your current session of
168 "CMD.exe", you can use this:
169 C:\>perl -Mlocal::lib
171 set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
172 set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
173 set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5
174 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
175 ### To set the environment for this shell alone
177 C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat
178 ### instead of $(perl -Mlocal::lib=./)
179 If you want the environment entries to persist, you'll need to add them
181 to the Control Panel's System applet yourself or use
182 App::local::lib::Win32Helper.
183 The "~" is translated to the user's profile directory (the directory
185 named for the user under "Documents and Settings" (Windows XP or
186 earlier) or "Users" (Windows Vista or later)) unless $ENV{HOME} exists.
187 After that, the home directory is translated to a short name (which
188 means the directory must exist) and the subdirectories are created.
189 PowerShell
191 local::lib also supports PowerShell, and can be used with the
193 "Invoke-Expression" cmdlet.
194 Invoke-Expression "$(perl -Mlocal::lib)"
196
198 The version of a Perl package on your machine is not always the version
199 you need. Obviously, the best thing to do would be to update to the
200 version you need. However, you might be in a situation where you're
201 prevented from doing this. Perhaps you don't have system administrator
202 privileges; or perhaps you are using a package management system such
203 as Debian, and nobody has yet gotten around to packaging up the version
204 you need.
205 local::lib solves this problem by allowing you to create your own
207 directory of Perl packages downloaded from CPAN (in a multi-user
208 system, this would typically be within your own home directory). The
209 existing system Perl installation is not affected; you simply invoke
210 Perl with special options so that Perl uses the packages in your own
211 local package directory rather than the system packages. local::lib
212 arranges things so that your locally installed version of the Perl
213 packages takes precedence over the system installation.
214 If you are using a package management system (such as Debian), you
216 don't need to worry about Debian and CPAN stepping on each other's
217 toes. Your local version of the packages will be written to an
218 entirely separate directory from those installed by Debian.
219
221 This module provides a quick, convenient way of bootstrapping a user-
222 local Perl module library located within the user's home directory. It
223 also constructs and prints out for the user the list of environment
224 variables using the syntax appropriate for the user's current shell (as
225 specified by the "SHELL" environment variable), suitable for directly
226 adding to one's shell configuration file.
227 More generally, local::lib allows for the bootstrapping and usage of a
229 directory containing Perl modules outside of Perl's @INC. This makes it
230 easier to ship an application with an app-specific copy of a Perl
231 module, or collection of modules. Useful in cases like when an upstream
232 maintainer hasn't applied a patch to a module of theirs that you need
233 for your application.
234 On import, local::lib sets the following environment variables to
236 appropriate values:
237 PERL_MB_OPT
239 PERL_MM_OPT
240 PERL5LIB
241 PATH
242 PERL_LOCAL_LIB_ROOT
243 When possible, these will be appended to instead of overwritten
245 entirely.
246 These values are then available for reference by any code after import.
248
250 See lib::core::only for one way to do this - but note that there are a
251 number of caveats, and the best approach is always to perform a build
252 against a clean perl (i.e. site and vendor as close to empty as
253 possible).
254
256 Options are values that can be passed to the "local::lib" import
257 besides the directory to use. They are specified as "use local::lib
258 '--option'[, path];" or "perl -Mlocal::lib=--option[,path]".
259 --deactivate
261 Remove the chosen path (or the default path) from the module search
262 paths if it was added by "local::lib", instead of adding it.
263 --deactivate-all
265 Remove all directories that were added to search paths by "local::lib"
266 from the search paths.
267 --shelltype
269 Specify the shell type to use for output. By default, the shell will
270 be detected based on the environment. Should be one of: "bourne",
271 "csh", "cmd", or "powershell".
272 --no-create
274 Prevents "local::lib" from creating directories when activating dirs.
275 This is likely to cause issues on Win32 systems.
276
278 ensure_dir_structure_for
279 Arguments: $path
280 Return value: None
281 Attempts to create a local::lib directory, including subdirectories and
283 all required parent directories. Throws an exception on failure.
284 print_environment_vars_for
286 Arguments: $path
287 Return value: None
288 Prints to standard output the variables listed above, properly set to
290 use the given path as the base directory.
291 build_environment_vars_for
293 Arguments: $path
294 Return value: %environment_vars
295 Returns a hash with the variables listed above, properly set to use the
297 given path as the base directory.
298 setup_env_hash_for
300 Arguments: $path
301 Return value: None
302 Constructs the %ENV keys for the given path, by calling
304 "build_environment_vars_for".
305 active_paths
307 Arguments: None
308 Return value: @paths
309 Returns a list of active "local::lib" paths, according to the
311 "PERL_LOCAL_LIB_ROOT" environment variable and verified against what is
312 really in @INC.
313 install_base_perl_path
315 Arguments: $path
316 Return value: $install_base_perl_path
317 Returns a path describing where to install the Perl modules for this
319 local library installation. Appends the directories "lib" and "perl5"
320 to the given path.
321 lib_paths_for
323 Arguments: $path
324 Return value: @lib_paths
325 Returns the list of paths perl will search for libraries, given a base
327 path. This includes the base path itself, the architecture specific
328 subdirectory, and perl version specific subdirectories. These paths
329 may not all exist.
330 install_base_bin_path
332 Arguments: $path
333 Return value: $install_base_bin_path
334 Returns a path describing where to install the executable programs for
336 this local library installation. Appends the directory "bin" to the
337 given path.
338 installer_options_for
340 Arguments: $path
341 Return value: %installer_env_vars
342 Returns a hash of environment variables that should be set to cause
344 installation into the given path.
345 resolve_empty_path
347 Arguments: $path
348 Return value: $base_path
349 Builds and returns the base path into which to set up the local module
351 installation. Defaults to "~/perl5".
352 resolve_home_path
354 Arguments: $path
355 Return value: $home_path
356 Attempts to find the user's home directory. If installed, uses
358 "File::HomeDir" for this purpose. If no definite answer is available,
359 throws an exception.
360 resolve_relative_path
362 Arguments: $path
363 Return value: $absolute_path
364 Translates the given path into an absolute path.
366 resolve_path
368 Arguments: $path
369 Return value: $absolute_path
370 Calls the following in a pipeline, passing the result from the previous
372 to the next, in an attempt to find where to configure the environment
373 for a local library installation: "resolve_empty_path",
374 "resolve_home_path", "resolve_relative_path". Passes the given path
375 argument to "resolve_empty_path" which then returns a result that is
376 passed to "resolve_home_path", which then has its result passed to
377 "resolve_relative_path". The result of this final call is returned from
378 "resolve_path".
379
381 new
382 Arguments: %attributes
383 Return value: $local_lib
384 Constructs a new "local::lib" object, representing the current state of
386 @INC and the relevant environment variables.
387
389 roots
390 An arrayref representing active "local::lib" directories.
391 inc
393 An arrayref representing @INC.
394 libs
396 An arrayref representing the PERL5LIB environment variable.
397 bins
399 An arrayref representing the PATH environment variable.
400 extra
402 A hashref of extra environment variables (e.g. "PERL_MM_OPT" and
403 "PERL_MB_OPT")
404 no_create
406 If set, "local::lib" will not try to create directories when activating
407 them.
408
410 clone
411 Arguments: %attributes
412 Return value: $local_lib
413 Constructs a new "local::lib" object based on the existing one,
415 overriding the specified attributes.
416 activate
418 Arguments: $path
419 Return value: $new_local_lib
420 Constructs a new instance with the specified path active.
422 deactivate
424 Arguments: $path
425 Return value: $new_local_lib
426 Constructs a new instance with the specified path deactivated.
428 deactivate_all
430 Arguments: None
431 Return value: $new_local_lib
432 Constructs a new instance with all "local::lib" directories
434 deactivated.
435 environment_vars_string
437 Arguments: [ $shelltype ]
438 Return value: $shell_env_string
439 Returns a string to set up the "local::lib", meant to be run by a
441 shell.
442 build_environment_vars
444 Arguments: None
445 Return value: %environment_vars
446 Returns a hash with the variables listed above, properly set to use the
448 given path as the base directory.
449 setup_env_hash
451 Arguments: None
452 Return value: None
453 Constructs the %ENV keys for the given path, by calling
455 "build_environment_vars".
456 setup_local_lib
458 Constructs the %ENV hash using "setup_env_hash", and set up @INC.
459
461 Be careful about using local::lib in combination with "make install
462 UNINST=1". The idea of this feature is that will uninstall an old
463 version of a module before installing a new one. However it lacks a
464 safety check that the old version and the new version will go in the
465 same directory. Used in combination with local::lib, you can
466 potentially delete a globally accessible version of a module while
467 installing the new version in a local place. Only combine "make install
468 UNINST=1" and local::lib if you understand these possible consequences.
469
471 · Directory names with spaces in them are not well supported by the
472 perl toolchain and the programs it uses. Pure-perl distributions
473 should support spaces, but problems are more likely with dists that
474 require compilation. A workaround you can do is moving your
475 local::lib to a directory with spaces after you installed all
476 modules inside your local::lib bootstrap. But be aware that you
477 can't update or install CPAN modules after the move.
478 · Rather basic shell detection. Right now anything with csh in its
480 name is assumed to be a C shell or something compatible, and
481 everything else is assumed to be Bourne, except on Win32 systems.
482 If the "SHELL" environment variable is not set, a Bourne-compatible
483 shell is assumed.
484 · Kills any existing PERL_MM_OPT or PERL_MB_OPT.
486 · Should probably auto-fixup CPAN config if not already done.
488 · On VMS and MacOS Classic (pre-OS X), local::lib loads File::Spec.
490 This means any File::Spec version installed in the local::lib will
491 be ignored by scripts using local::lib. A workaround for this is
492 using "use lib "$local_lib/lib/perl5";" instead of using
493 "local::lib" directly.
494 · Conflicts with ExtUtils::MakeMaker's "PREFIX" option. "local::lib"
496 uses the "INSTALL_BASE" option, as it has more predictable and sane
497 behavior. If something attempts to use the "PREFIX" option when
498 running a Makefile.PL, ExtUtils::MakeMaker will refuse to run, as
499 the two options conflict. This can be worked around by temporarily
500 unsetting the "PERL_MM_OPT" environment variable.
501 · Conflicts with Module::Build's "--prefix" option. Similar to the
503 previous limitation, but any "--prefix" option specified will be
504 ignored. This can be worked around by temporarily unsetting the
505 "PERL_MB_OPT" environment variable.
506 Patches very much welcome for any of the above.
508 · On Win32 systems, does not have a way to write the created
510 environment variables to the registry, so that they can persist
511 through a reboot.
512
514 If you've configured local::lib to install CPAN modules somewhere in to
515 your home directory, and at some point later you try to install a
516 module with "cpan -i Foo::Bar", but it fails with an error like:
517 "Warning: You do not have permissions to install into
518 /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
519 /usr/lib64/perl5/5.8.8/Foo/Bar.pm" and buried within the install log is
520 an error saying "'INSTALL_BASE' is not a known MakeMaker parameter
521 name", then you've somehow lost your updated ExtUtils::MakeMaker
522 module.
523 To remedy this situation, rerun the bootstrapping procedure documented
525 above.
526 Then, run "rm -r ~/.cpan/build/Foo-Bar*"
528 Finally, re-run "cpan -i Foo::Bar" and it should install without
530 problems.
531
533 SHELL
534 COMSPEC
535 local::lib looks at the user's "SHELL" environment variable when
536 printing out commands to add to the shell configuration file.
537 On Win32 systems, "COMSPEC" is also examined.
539
541 · Perl Advent article, 2011
542 <http://perladvent.org/2011/2011-12-01.html>
543
545 IRC:
546 Join #toolchain on irc.perl.org.
548
550 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
551 auto_install fixes kindly sponsored by http://www.takkle.com/
553
555 Patches to correctly output commands for csh style shells, as well as
556 some documentation additions, contributed by Christopher Nehren
557 <apeiron@cpan.org>.
558 Doc patches for a custom local::lib directory, more cleanups in the
560 english documentation and a german documentation contributed by Torsten
561 Raudssus <torsten@raudssus.de>.
562 Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for
564 ensuring things will install properly, submitted a fix for the bug
565 causing problems with writing Makefiles during bootstrapping,
566 contributed an example program, and submitted yet another fix to ensure
567 that local::lib can install and bootstrap properly. Many, many thanks!
568 pattern of Freenode IRC contributed the beginnings of the
570 Troubleshooting section. Many thanks!
571 Patch to add Win32 support contributed by Curtis Jewell
573 <csjewell@cpan.org>.
574 Warnings for missing PATH/PERL5LIB (as when not running interactively)
576 silenced by a patch from Marco Emilio Poleggi.
577 Mark Stosberg <mark@summersault.com> provided the code for the now
579 deleted '--self-contained' option.
580 Documentation patches to make win32 usage clearer by David Mertens
582 <dcmertens.perl@gmail.com> (run4flat).
583 Brazilian portuguese translation and minor doc patches contributed by
585 Breno G. de Oliveira <garu@cpan.org>.
586 Improvements to stacking multiple local::lib dirs and removing them
588 from the environment later on contributed by Andrew Rodland
589 <arodland@cpan.org>.
590 Patch for Carp version mismatch contributed by Hakim Cassimally
592 <osfameron@cpan.org>.
593 Rewrite of internals and numerous bug fixes and added features
595 contributed by Graham Knop <haarg@haarg.org>.
596
598 Copyright (c) 2007 - 2013 the local::lib "AUTHOR" and "CONTRIBUTORS" as
599 listed above.
600
602 This is free software; you can redistribute it and/or modify it under
603 the same terms as the Perl 5 programming language system itself.
604perl v5.32.0 2020-07-28 local::lib(3)