1local::lib(3)         User Contributed Perl Documentation        local::lib(3)
2
3
4

NAME

6       local::lib - create and use a local lib/ for perl modules with PERL5LIB
7

SYNOPSIS

9       In code -
10
11         use local::lib; # sets up a local lib at ~/perl5
12
13         use local::lib '~/foo'; # same, but ~/foo
14
15         # Or...
16         use FindBin;
17         use local::lib "$FindBin::Bin/../support";  # app-local support library
18
19       From the shell -
20
21         # Install LWP and its missing dependencies to the '~/perl5' directory
22         perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
23
24         # 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
32       From a .bash_profile or .bashrc file -
33
34         eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
35
36   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
42       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
48       By default local::lib installs itself and the CPAN modules into
49       ~/perl5.
50
51       Windows users must also see "Differences when using this module under
52       Win32".
53
54       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
59       2.  Run this:
60
61             perl Makefile.PL --bootstrap
62
63           If the system asks you whether it should automatically configure as
64           much as possible, you would typically answer yes.
65
66           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
70             perl Makefile.PL --bootstrap=~/foo
71
72       3.  Run this: (local::lib assumes you have make installed on your
73           system)
74
75             make test && make install
76
77       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
82             echo 'eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc
83
84           If you are using C shell, you can do this as follows:
85
86             /bin/csh
87             echo $SHELL
88             /bin/csh
89             echo 'eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >> ~/.cshrc
90
91           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
95             echo 'eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc
96
97           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
102       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
107         perl Makefile.PL --bootstrap --no-manpages
108
109       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
115         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
123       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
129         [ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
130
131       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
136         eval $(perl -Mlocal::lib=--deactivate,~/path)
137
138       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
147       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
156       In "~/mydir1/scripts/myscript.pl":
157
158         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
163       Put this before any BEGIN { ... } blocks that require the modules you
164       installed.
165
166   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
170         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
176         ### 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
180       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
184       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
190       PowerShell
191
192       local::lib also supports PowerShell, and can be used with the
193       "Invoke-Expression" cmdlet.
194
195         Invoke-Expression "$(perl -Mlocal::lib)"
196

RATIONALE

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
206       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
215       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

DESCRIPTION

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
228       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
235       On import, local::lib sets the following environment variables to
236       appropriate values:
237
238       PERL_MB_OPT
239       PERL_MM_OPT
240       PERL5LIB
241       PATH
242       PERL_LOCAL_LIB_ROOT
243
244       When possible, these will be appended to instead of overwritten
245       entirely.
246
247       These values are then available for reference by any code after import.
248

CREATING A SELF-CONTAINED SET OF MODULES

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

IMPORT OPTIONS

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
260   --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
264   --deactivate-all
265       Remove all directories that were added to search paths by "local::lib"
266       from the search paths.
267
268   --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
273   --no-create
274       Prevents "local::lib" from creating directories when activating dirs.
275       This is likely to cause issues on Win32 systems.
276

CLASS METHODS

278   ensure_dir_structure_for
279       Arguments: $path
280       Return value: None
281
282       Attempts to create a local::lib directory, including subdirectories and
283       all required parent directories. Throws an exception on failure.
284
285   print_environment_vars_for
286       Arguments: $path
287       Return value: None
288
289       Prints to standard output the variables listed above, properly set to
290       use the given path as the base directory.
291
292   build_environment_vars_for
293       Arguments: $path
294       Return value: %environment_vars
295
296       Returns a hash with the variables listed above, properly set to use the
297       given path as the base directory.
298
299   setup_env_hash_for
300       Arguments: $path
301       Return value: None
302
303       Constructs the %ENV keys for the given path, by calling
304       "build_environment_vars_for".
305
306   active_paths
307       Arguments: None
308       Return value: @paths
309
310       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
314   install_base_perl_path
315       Arguments: $path
316       Return value: $install_base_perl_path
317
318       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
322   lib_paths_for
323       Arguments: $path
324       Return value: @lib_paths
325
326       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
331   install_base_bin_path
332       Arguments: $path
333       Return value: $install_base_bin_path
334
335       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
339   installer_options_for
340       Arguments: $path
341       Return value: %installer_env_vars
342
343       Returns a hash of environment variables that should be set to cause
344       installation into the given path.
345
346   resolve_empty_path
347       Arguments: $path
348       Return value: $base_path
349
350       Builds and returns the base path into which to set up the local module
351       installation. Defaults to "~/perl5".
352
353   resolve_home_path
354       Arguments: $path
355       Return value: $home_path
356
357       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
361   resolve_relative_path
362       Arguments: $path
363       Return value: $absolute_path
364
365       Translates the given path into an absolute path.
366
367   resolve_path
368       Arguments: $path
369       Return value: $absolute_path
370
371       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

OBJECT INTERFACE

381   new
382       Arguments: %attributes
383       Return value: $local_lib
384
385       Constructs a new "local::lib" object, representing the current state of
386       @INC and the relevant environment variables.
387

ATTRIBUTES

389   roots
390       An arrayref representing active "local::lib" directories.
391
392   inc
393       An arrayref representing @INC.
394
395   libs
396       An arrayref representing the PERL5LIB environment variable.
397
398   bins
399       An arrayref representing the PATH environment variable.
400
401   extra
402       A hashref of extra environment variables (e.g. "PERL_MM_OPT" and
403       "PERL_MB_OPT")
404
405   no_create
406       If set, "local::lib" will not try to create directories when activating
407       them.
408

OBJECT METHODS

410   clone
411       Arguments: %attributes
412       Return value: $local_lib
413
414       Constructs a new "local::lib" object based on the existing one,
415       overriding the specified attributes.
416
417   activate
418       Arguments: $path
419       Return value: $new_local_lib
420
421       Constructs a new instance with the specified path active.
422
423   deactivate
424       Arguments: $path
425       Return value: $new_local_lib
426
427       Constructs a new instance with the specified path deactivated.
428
429   deactivate_all
430       Arguments: None
431       Return value: $new_local_lib
432
433       Constructs a new instance with all "local::lib" directories
434       deactivated.
435
436   environment_vars_string
437       Arguments: [ $shelltype ]
438       Return value: $shell_env_string
439
440       Returns a string to set up the "local::lib", meant to be run by a
441       shell.
442
443   build_environment_vars
444       Arguments: None
445       Return value: %environment_vars
446
447       Returns a hash with the variables listed above, properly set to use the
448       given path as the base directory.
449
450   setup_env_hash
451       Arguments: None
452       Return value: None
453
454       Constructs the %ENV keys for the given path, by calling
455       "build_environment_vars".
456
457   setup_local_lib
458       Constructs the %ENV hash using "setup_env_hash", and set up @INC.
459

A WARNING ABOUT UNINST=1

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

LIMITATIONS

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
479       ·   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
485       ·   Kills any existing PERL_MM_OPT or PERL_MB_OPT.
486
487       ·   Should probably auto-fixup CPAN config if not already done.
488
489       ·   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
495       ·   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
502       ·   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
507       Patches very much welcome for any of the above.
508
509       ·   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

TROUBLESHOOTING

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
524       To remedy this situation, rerun the bootstrapping procedure documented
525       above.
526
527       Then, run "rm -r ~/.cpan/build/Foo-Bar*"
528
529       Finally, re-run "cpan -i Foo::Bar" and it should install without
530       problems.
531

ENVIRONMENT

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
538           On Win32 systems, "COMSPEC" is also examined.
539

SEE ALSO

541       ·   Perl Advent article, 2011
542           <http://perladvent.org/2011/2011-12-01.html>
543

SUPPORT

545       IRC:
546
547           Join #toolchain on irc.perl.org.
548

AUTHOR

550       Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
551
552       auto_install fixes kindly sponsored by http://www.takkle.com/
553

CONTRIBUTORS

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
559       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
563       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
569       pattern of Freenode IRC contributed the beginnings of the
570       Troubleshooting section. Many thanks!
571
572       Patch to add Win32 support contributed by Curtis Jewell
573       <csjewell@cpan.org>.
574
575       Warnings for missing PATH/PERL5LIB (as when not running interactively)
576       silenced by a patch from Marco Emilio Poleggi.
577
578       Mark Stosberg <mark@summersault.com> provided the code for the now
579       deleted '--self-contained' option.
580
581       Documentation patches to make win32 usage clearer by David Mertens
582       <dcmertens.perl@gmail.com> (run4flat).
583
584       Brazilian portuguese translation and minor doc patches contributed by
585       Breno G. de Oliveira <garu@cpan.org>.
586
587       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
591       Patch for Carp version mismatch contributed by Hakim Cassimally
592       <osfameron@cpan.org>.
593
594       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

LICENSE

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.
604
605
606
607perl v5.32.0                      2020-07-28                     local::lib(3)
Impressum