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 export PERL_MB_OPT='--install_base /home/username/perl5'
27 export PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'
28 export PERL5LIB='/home/username/perl5/lib/perl5/i386-linux:/home/username/perl5/lib/perl5'
29 export PATH="/home/username/perl5/bin:$PATH"
30 The bootstrapping technique
32 A typical way to install local::lib is using what is known as the
33 "bootstrapping" technique. You would do this if your system
34 administrator hasn't already installed local::lib. In this case,
35 you'll need to install local::lib in your home directory.
36 If you do have administrative privileges, you will still want to set up
38 your environment variables, as discussed in step 4. Without this, you
39 would still install the modules into the system CPAN installation and
40 also your Perl scripts will not use the lib/ path you bootstrapped with
41 local::lib.
42 By default local::lib installs itself and the CPAN modules into
44 ~/perl5.
45 Windows users must also see "Differences when using this module under
47 Win32".
48 1. Download and unpack the local::lib tarball from CPAN (search for
50 "Download" on the CPAN page about local::lib). Do this as an ordinary
51 user, not as root or administrator. Unpack the file in your home
52 directory or in any other convenient location.
53 2. Run this:
55 perl Makefile.PL --bootstrap
57 If the system asks you whether it should automatically configure as
59 much as possible, you would typically answer yes.
60 In order to install local::lib into a directory other than the default,
62 you need to specify the name of the directory when you call bootstrap,
63 as follows:
64 perl Makefile.PL --bootstrap=~/foo
66 3. Run this: (local::lib assumes you have make installed on your
68 system)
69 make test && make install
71 4. Now we need to setup the appropriate environment variables, so that
73 Perl starts using our newly generated lib/ directory. If you are using
74 bash or any other Bourne shells, you can add this to your shell startup
75 script this way:
76 echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
78 If you are using C shell, you can do this as follows:
80 /bin/csh
82 echo $SHELL
83 /bin/csh
84 perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
85 If you passed to bootstrap a directory other than default, you also
87 need to give that as import parameter to the call of the local::lib
88 module like this way:
89 echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
91 After writing your shell configuration file, be sure to re-read it to
93 get the changed settings into your current shell's environment. Bourne
94 shells use ". ~/.bashrc" for this, whereas C shells use "source
95 ~/.cshrc".
96 If you're on a slower machine, or are operating under draconian disk
98 space limitations, you can disable the automatic generation of manpages
99 from POD when installing modules by using the "--no-manpages" argument
100 when bootstrapping:
101 perl Makefile.PL --bootstrap --no-manpages
103 To avoid doing several bootstrap for several Perl module environments
105 on the same account, for example if you use it for several different
106 deployed applications independently, you can use one bootstrapped
107 local::lib installation to install modules in different directories
108 directly this way:
109 cd ~/mydir1
111 perl -Mlocal::lib=./
112 eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone
113 printenv ### You will see that ~/mydir1 is in the PERL5LIB
114 perl -MCPAN -e install ... ### whatever modules you want
115 cd ../mydir2
116 ... REPEAT ...
117 If you are working with several "local::lib" environments, you may want
119 to remove some of them from the current environment without disturbing
120 the others. You can deactivate one environment like this (using bourne
121 sh):
122 eval $(perl -Mlocal::lib=--deactivate,~/path)
124 which will generate and run the commands needed to remove "~/path" from
126 your various search paths. Whichever environment was activated most
127 recently will remain the target for module installations. That is, if
128 you activate "~/path_A" and then you activate "~/path_B", new modules
129 you install will go in "~/path_B". If you deactivate "~/path_B" then
130 modules will be installed into "~/pathA" -- but if you deactivate
131 "~/path_A" then they will still be installed in "~/pathB" because pathB
132 was activated later.
133 You can also ask "local::lib" to clean itself completely out of the
135 current shell's environment with the "--deactivate-all" option. For
136 multiple environments for multiple apps you may need to include a
137 modified version of the "use FindBin" instructions in the "In code"
138 sample above. If you did something like the above, you have a set of
139 Perl modules at "~/mydir1/lib". If you have a script at
140 "~/mydir1/scripts/myscript.pl", you need to tell it where to find the
141 modules you installed for it at "~/mydir1/lib".
142 In "~/mydir1/scripts/myscript.pl":
144 use strict;
146 use warnings;
147 use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib
148 use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib
149 Put this before any BEGIN { ... } blocks that require the modules you
151 installed.
152 Differences when using this module under Win32
154 To set up the proper environment variables for your current session of
155 "CMD.exe", you can use this:
156 C:\>perl -Mlocal::lib
158 set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
159 set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
160 set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5;C:\DOCUME~1\ADMINI~1\perl5\lib\perl5\MSWin32-x86-multi-thread
161 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
162 ### To set the environment for this shell alone
164 C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat
165 ### instead of $(perl -Mlocal::lib=./)
166 If you want the environment entries to persist, you'll need to add then
168 to the Control Panel's System applet yourself or use
169 App::local::lib::Win32Helper.
170 The "~" is translated to the user's profile directory (the directory
172 named for the user under "Documents and Settings" (Windows XP or
173 earlier) or "Users" (Windows Vista or later)) unless $ENV{HOME} exists.
174 After that, the home directory is translated to a short name (which
175 means the directory must exist) and the subdirectories are created.
176
178 The version of a Perl package on your machine is not always the version
179 you need. Obviously, the best thing to do would be to update to the
180 version you need. However, you might be in a situation where you're
181 prevented from doing this. Perhaps you don't have system administrator
182 privileges; or perhaps you are using a package management system such
183 as Debian, and nobody has yet gotten around to packaging up the version
184 you need.
185 local::lib solves this problem by allowing you to create your own
187 directory of Perl packages downloaded from CPAN (in a multi-user
188 system, this would typically be within your own home directory). The
189 existing system Perl installation is not affected; you simply invoke
190 Perl with special options so that Perl uses the packages in your own
191 local package directory rather than the system packages. local::lib
192 arranges things so that your locally installed version of the Perl
193 packages takes precedence over the system installation.
194 If you are using a package management system (such as Debian), you
196 don't need to worry about Debian and CPAN stepping on each other's
197 toes. Your local version of the packages will be written to an
198 entirely separate directory from those installed by Debian.
199
201 This module provides a quick, convenient way of bootstrapping a user-
202 local Perl module library located within the user's home directory. It
203 also constructs and prints out for the user the list of environment
204 variables using the syntax appropriate for the user's current shell (as
205 specified by the "SHELL" environment variable), suitable for directly
206 adding to one's shell configuration file.
207 More generally, local::lib allows for the bootstrapping and usage of a
209 directory containing Perl modules outside of Perl's @INC. This makes it
210 easier to ship an application with an app-specific copy of a Perl
211 module, or collection of modules. Useful in cases like when an upstream
212 maintainer hasn't applied a patch to a module of theirs that you need
213 for your application.
214 On import, local::lib sets the following environment variables to
216 appropriate values:
217 PERL_MB_OPT
219 PERL_MM_OPT
220 PERL5LIB
221 PATH
222 PATH is appended to, rather than clobbered.
223 These values are then available for reference by any code after import.
225
227 See lib::core::only for one way to do this - but note that there are a
228 number of caveats, and the best approach is always to perform a build
229 against a clean perl (i.e. site and vendor as close to empty as
230 possible).
231
233 Options are values that can be passed to the "local::lib" import
234 besides the directory to use. They are specified as "use local::lib
235 '--option'[, path];" or "perl -Mlocal::lib=--option[,path]".
236 --deactivate
238 Remove the chosen path (or the default path) from the module search
239 paths if it was added by "local::lib", instead of adding it.
240 --deactivate-all
242 Remove all directories that were added to search paths by "local::lib"
243 from the search paths.
244
246 ensure_dir_structure_for
247 Arguments: $path
248 Return value: None
249 Attempts to create the given path, and all required parent directories.
251 Throws an exception on failure.
252 print_environment_vars_for
254 Arguments: $path
255 Return value: None
256 Prints to standard output the variables listed above, properly set to
258 use the given path as the base directory.
259 build_environment_vars_for
261 Arguments: $path, $interpolate
262 Return value: \%environment_vars
263 Returns a hash with the variables listed above, properly set to use the
265 given path as the base directory.
266 setup_env_hash_for
268 Arguments: $path
269 Return value: None
270 Constructs the %ENV keys for the given path, by calling
272 "build_environment_vars_for".
273 active_paths
275 Arguments: None
276 Return value: @paths
277 Returns a list of active "local::lib" paths, according to the
279 "PERL_LOCAL_LIB_ROOT" environment variable.
280 install_base_perl_path
282 Arguments: $path
283 Return value: $install_base_perl_path
284 Returns a path describing where to install the Perl modules for this
286 local library installation. Appends the directories "lib" and "perl5"
287 to the given path.
288 install_base_arch_path
290 Arguments: $path
291 Return value: $install_base_arch_path
292 Returns a path describing where to install the architecture-specific
294 Perl modules for this local library installation. Based on the
295 "install_base_perl_path" method's return value, and appends the value
296 of $Config{archname}.
297 install_base_bin_path
299 Arguments: $path
300 Return value: $install_base_bin_path
301 Returns a path describing where to install the executable programs for
303 this local library installation. Based on the "install_base_perl_path"
304 method's return value, and appends the directory "bin".
305 resolve_empty_path
307 Arguments: $path
308 Return value: $base_path
309 Builds and returns the base path into which to set up the local module
311 installation. Defaults to "~/perl5".
312 resolve_home_path
314 Arguments: $path
315 Return value: $home_path
316 Attempts to find the user's home directory. If installed, uses
318 "File::HomeDir" for this purpose. If no definite answer is available,
319 throws an exception.
320 resolve_relative_path
322 Arguments: $path
323 Return value: $absolute_path
324 Translates the given path into an absolute path.
326 resolve_path
328 Arguments: $path
329 Return value: $absolute_path
330 Calls the following in a pipeline, passing the result from the previous
332 to the next, in an attempt to find where to configure the environment
333 for a local library installation: "resolve_empty_path",
334 "resolve_home_path", "resolve_relative_path". Passes the given path
335 argument to "resolve_empty_path" which then returns a result that is
336 passed to "resolve_home_path", which then has its result passed to
337 "resolve_relative_path". The result of this final call is returned from
338 "resolve_path".
339
341 Be careful about using local::lib in combination with "make install
342 UNINST=1". The idea of this feature is that will uninstall an old
343 version of a module before installing a new one. However it lacks a
344 safety check that the old version and the new version will go in the
345 same directory. Used in combination with local::lib, you can
346 potentially delete a globally accessible version of a module while
347 installing the new version in a local place. Only combine "make install
348 UNINST=1" and local::lib if you understand these possible consequences.
349
351 The perl toolchain is unable to handle directory names with spaces in
352 it, so you cant put your local::lib bootstrap into a directory with
353 spaces. What you can do is moving your local::lib to a directory with
354 spaces after you installed all modules inside your local::lib
355 bootstrap. But be aware that you cant update or install CPAN modules
356 after the move.
357 Rather basic shell detection. Right now anything with csh in its name
359 is assumed to be a C shell or something compatible, and everything else
360 is assumed to be Bourne, except on Win32 systems. If the "SHELL"
361 environment variable is not set, a Bourne-compatible shell is assumed.
362 Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even
364 if you have CPANPLUS installed.
365 Kills any existing PERL5LIB, PERL_MM_OPT or PERL_MB_OPT.
367 Should probably auto-fixup CPAN config if not already done.
369 Patches very much welcome for any of the above.
371 On Win32 systems, does not have a way to write the created environment
373 variables to the registry, so that they can persist through a reboot.
374
376 If you've configured local::lib to install CPAN modules somewhere in to
377 your home directory, and at some point later you try to install a
378 module with "cpan -i Foo::Bar", but it fails with an error like:
379 "Warning: You do not have permissions to install into
380 /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
381 /usr/lib64/perl5/5.8.8/Foo/Bar.pm" and buried within the install log is
382 an error saying "'INSTALL_BASE' is not a known MakeMaker parameter
383 name", then you've somehow lost your updated ExtUtils::MakeMaker
384 module.
385 To remedy this situation, rerun the bootstrapping procedure documented
387 above.
388 Then, run "rm -r ~/.cpan/build/Foo-Bar*"
390 Finally, re-run "cpan -i Foo::Bar" and it should install without
392 problems.
393
395 SHELL
396 COMSPEC
397 local::lib looks at the user's "SHELL" environment variable when
398 printing out commands to add to the shell configuration file.
399 On Win32 systems, "COMSPEC" is also examined.
401
403 IRC:
404 Join #local-lib on irc.perl.org.
406
408 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
409 auto_install fixes kindly sponsored by http://www.takkle.com/
411
413 Patches to correctly output commands for csh style shells, as well as
414 some documentation additions, contributed by Christopher Nehren
415 <apeiron@cpan.org>.
416 Doc patches for a custom local::lib directory, more cleanups in the
418 english documentation and a german documentation contributed by Torsten
419 Raudssus <torsten@raudssus.de>.
420 Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for
422 ensuring things will install properly, submitted a fix for the bug
423 causing problems with writing Makefiles during bootstrapping,
424 contributed an example program, and submitted yet another fix to ensure
425 that local::lib can install and bootstrap properly. Many, many thanks!
426 pattern of Freenode IRC contributed the beginnings of the
428 Troubleshooting section. Many thanks!
429 Patch to add Win32 support contributed by Curtis Jewell
431 <csjewell@cpan.org>.
432 Warnings for missing PATH/PERL5LIB (as when not running interactively)
434 silenced by a patch from Marco Emilio Poleggi.
435 Mark Stosberg <mark@summersault.com> provided the code for the now
437 deleted '--self-contained' option.
438 Documentation patches to make win32 usage clearer by David Mertens
440 <dcmertens.perl@gmail.com> (run4flat).
441 Brazilian portuguese translation and minor doc patches contributed by
443 Breno G. de Oliveira <garu@cpan.org>.
444 Improvements to stacking multiple local::lib dirs and removing them
446 from the environment later on contributed by Andrew Rodland
447 <arodland@cpan.org>.
448 Patch for Carp version mismatch contributed by Hakim Cassimally
450 <osfameron@cpan.org>.
451
453 Copyright (c) 2007 - 2010 the local::lib "AUTHOR" and "CONTRIBUTORS" as
454 listed above.
455
457 This library is free software and may be distributed under the same
458 terms as perl itself.
459perl v5.16.3 2017-08-05 local::lib(3)