6 use 5.008001; # probably works with earlier versions but I'm not supporting them
7 # (patches would, of course, be welcome)
14 our $VERSION = '1.004001'; # 1.4.1
17 my ($class, @args) = @_;
19 # Remember what PERL5LIB was when we started
20 my $perl5lib = $ENV{PERL5LIB};
22 # The path is required, but last in the list, so we pop, not shift here.
24 $path = $class->resolve_path($path);
25 $class->setup_local_lib_for($path);
27 # Handle the '--self-contained' option
28 my $flag = shift @args;
29 no warnings 'uninitialized'; # the flag is optional
30 # make sure fancy dashes cause an error
33 WHOA THERE! It looks like you've got some fancy dashes in your commandline!
34 These are *not* the traditional -- dashes that software recognizes. You
35 probably got these by copy-pasting from the perldoc for this module as
36 rendered by a UTF8-capable formatter. This most typically happens on an OS X
37 terminal, but can happen elsewhere too. Please try again after replacing the
38 dashes with normal minus signs.
41 if ($flag eq '--self-contained') {
42 # The only directories that remain are those that we just defined and those where core modules are stored.
43 # We put PERL5LIB first, so it'll be favored over privlibexp and archlibexp
44 @INC = ( $class->install_base_perl_path($path), $class->install_base_arch_path($path), split( ':', $perl5lib ), $Config::Config{privlibexp}, $Config::Config{archlibexp} );
46 # We explicitly set PERL5LIB here (back to what it was originally) to prevent @INC from growing with each invocation
47 $ENV{PERL5LIB} = $perl5lib;
49 elsif (defined $flag) {
50 die "unrecognized import argument: $flag";
53 for (@INC) { # Untaint @INC
54 next if ref; # Skip entry if it is an ARRAY, CODE, blessed, etc.
63 my $last = pop(@methods);
66 my ($obj, @args) = @_;
67 $obj->${pipeline @methods}(
84 { package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } }
85 my $foo = bless({}, 'Foo');
86 Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
93 my ($class, $path) = @_;
94 $class->${pipeline qw(
101 sub resolve_empty_path {
102 my ($class, $path) = @_;
112 #:: test classmethod setup
114 my $c = 'local::lib';
122 is($c->resolve_empty_path, '~/perl5');
123 is($c->resolve_empty_path('foo'), 'foo');
129 sub resolve_home_path {
130 my ($class, $path) = @_;
131 return $path unless ($path =~ /^~/);
132 my ($user) = ($path =~ /^~([^\/]+)/); # can assume ^~ so undef for 'us'
133 my $tried_file_homedir;
135 if (eval { require File::HomeDir } && $File::HomeDir::VERSION >= 0.65) {
136 $tried_file_homedir = 1;
138 File::HomeDir->users_home($user);
140 File::HomeDir->my_home;
146 if (defined $ENV{HOME}) {
154 unless (defined $homedir) {
156 "Couldn't resolve homedir for "
157 .(defined $user ? $user : 'current user')
158 .($tried_file_homedir ? '' : ' - consider installing File::HomeDir')
161 $path =~ s/^~[^\/]*/$homedir/;
165 sub resolve_relative_path {
166 my ($class, $path) = @_;
167 File::Spec->rel2abs($path);
174 local *File::Spec::rel2abs = sub { shift; 'FOO'.shift; };
175 is($c->resolve_relative_path('bar'),'FOObar');
181 sub setup_local_lib_for {
182 my ($class, $path) = @_;
183 $class->ensure_dir_structure_for($path);
185 $class->print_environment_vars_for($path);
188 $class->setup_env_hash_for($path);
189 unshift(@INC, split(':', $ENV{PERL5LIB}));
193 sub modulebuildrc_path {
194 my ($class, $path) = @_;
195 File::Spec->catfile($path, '.modulebuildrc');
198 sub install_base_bin_path {
199 my ($class, $path) = @_;
200 File::Spec->catdir($path, 'bin');
203 sub install_base_perl_path {
204 my ($class, $path) = @_;
205 File::Spec->catdir($path, 'lib', 'perl5');
208 sub install_base_arch_path {
209 my ($class, $path) = @_;
210 File::Spec->catdir($class->install_base_perl_path($path), $Config{archname});
213 sub ensure_dir_structure_for {
214 my ($class, $path) = @_;
216 warn "Attempting to create directory ${path}\n";
218 File::Path::mkpath($path);
219 my $modulebuildrc_path = $class->modulebuildrc_path($path);
220 if (-e $modulebuildrc_path) {
222 Carp::croak("${modulebuildrc_path} exists but is not a plain file");
225 warn "Attempting to create file ${modulebuildrc_path}\n";
226 open MODULEBUILDRC, '>', $modulebuildrc_path
227 || Carp::croak("Couldn't open ${modulebuildrc_path} for writing: $!");
228 print MODULEBUILDRC qq{install --install_base ${path}\n}
229 || Carp::croak("Couldn't write line to ${modulebuildrc_path}: $!");
231 || Carp::croak("Couldn't close file ${modulebuildrc_path}: $@");
235 sub INTERPOLATE_ENV () { 1 }
236 sub LITERAL_ENV () { 0 }
238 sub print_environment_vars_for {
239 my ($class, $path) = @_;
240 my @envs = $class->build_environment_vars_for($path, LITERAL_ENV);
243 # rather basic csh detection, goes on the assumption that something won't
244 # call itself csh unless it really is. also, default to bourne in the
245 # pathological situation where a user doesn't have $ENV{SHELL} defined.
246 # note also that shells with funny names, like zoid, are assumed to be
249 if(defined $ENV{'SHELL'}) {
250 my @shell_bin_path_parts = File::Spec->splitpath($ENV{'SHELL'});
251 $shellbin = $shell_bin_path_parts[-1];
254 local $_ = $shellbin;
263 my ($name, $value) = (shift(@envs), shift(@envs));
264 $value =~ s/(\\")/\\$1/g;
265 $out .= $class->${\"build_${shelltype}_env_declaration"}($name, $value);
270 # simple routines that take two arguments: an %ENV key and a value. return
271 # strings that are suitable for passing directly to the relevant shell to set
272 # said key to said value.
273 sub build_bourne_env_declaration {
275 my($name, $value) = @_;
276 return qq{export ${name}="${value}"\n};
279 sub build_csh_env_declaration {
281 my($name, $value) = @_;
282 return qq{setenv ${name} "${value}"\n};
285 sub setup_env_hash_for {
286 my ($class, $path) = @_;
287 my %envs = $class->build_environment_vars_for($path, INTERPOLATE_ENV);
288 @ENV{keys %envs} = values %envs;
291 sub build_environment_vars_for {
292 my ($class, $path, $interpolate) = @_;
294 MODULEBUILDRC => $class->modulebuildrc_path($path),
295 PERL_MM_OPT => "INSTALL_BASE=${path}",
296 PERL5LIB => join(':',
297 $class->install_base_perl_path($path),
298 $class->install_base_arch_path($path),
300 ($interpolate == INTERPOLATE_ENV
306 $class->install_base_bin_path($path),
307 ($interpolate == INTERPOLATE_ENV
318 File::Path::rmtree('t/var/splat');
320 $c->ensure_dir_structure_for('t/var/splat');
322 ok(-d 't/var/splat');
324 ok(-f 't/var/splat/.modulebuildrc');
330 local::lib - create and use a local lib/ for perl modules with PERL5LIB
336 use local::lib; # sets up a local lib at ~/perl5
338 use local::lib '~/foo'; # same, but ~/foo
342 use local::lib "$FindBin::Bin/../support"; # app-local support library
346 # Install LWP and it's missing dependencies to the 'my_lwp' directory
347 perl -MCPAN -Mlocal::lib=my_lwp -e 'CPAN::install(LWP)'
349 # Install LWP and *all non-core* dependencies to the 'my_lwp' directory
350 perl -MCPAN -Mlocal::lib=--self-contained,my_lwp -e 'CPAN::install(LWP)'
352 # Just print out useful shell commands
354 export MODULEBUILDRC=/home/username/perl/.modulebuildrc
355 export PERL_MM_OPT='INSTALL_BASE=/home/username/perl'
356 export PERL5LIB='/home/username/perl/lib/perl5:/home/username/perl/lib/perl5/i386-linux'
357 export PATH="/home/username/perl/bin:$PATH"
359 To bootstrap if you don't have local::lib itself installed -
361 <download local::lib tarball from CPAN, unpack and cd into dir>
363 $ perl Makefile.PL --bootstrap
364 $ make test && make install
366 $ echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
373 % perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
375 You can also pass --boostrap=~/foo to get a different location -
377 $ perl Makefile.PL --bootstrap=~/foo
378 $ make test && make install
380 $ echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
382 If you want to install multiple Perl module environments, say for application evelopment,
383 install local::lib globally and then:
386 $ perl -Mlocal::lib=./
387 $ eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone
388 $ printenv ### You will see that ~/mydir1 is in the PERL5LIB
389 $ perl -MCPAN -e install ... ### whatever modules you want
393 For multiple environments for multiple apps you may need to include a modified version of
394 the C<< use FindBin >> instructions in the "In code" sample above. If you did something like
395 the above, you have a set of Perl modules at C<< ~/mydir1/lib >>. If you have a script at
396 C<< ~/mydir1/scripts/myscript.pl >>, you need to tell it where to find the modules you installed
397 for it at C<< ~/mydir1/lib >>.
399 In C<< ~/mydir1/scripts/myscript.pl >>:
403 use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib
404 use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib
406 Put this before any BEGIN { ... } blocks that require the modules you installed.
410 This module provides a quick, convenient way of bootstrapping a user-local Perl
411 module library located within the user's home directory. It also constructs and
412 prints out for the user the list of environment variables using the syntax
413 appropriate for the user's current shell (as specified by the C<SHELL>
414 environment variable), suitable for directly adding to one's shell configuration
417 More generally, local::lib allows for the bootstrapping and usage of a directory
418 containing Perl modules outside of Perl's C<@INC>. This makes it easier to ship
419 an application with an app-specific copy of a Perl module, or collection of
420 modules. Useful in cases like when an upstream maintainer hasn't applied a patch
421 to a module of theirs that you need for your application.
423 On import, local::lib sets the following environment variables to appropriate
436 PATH is appended to, rather than clobbered.
440 These values are then available for reference by any code after import.
444 =head2 ensure_directory_structure_for
448 =item Arguments: path
452 Attempts to create the given path, and all required parent directories. Throws
453 an exception on failure.
455 =head2 print_environment_vars_for
459 =item Arguments: path
463 Prints to standard output the variables listed above, properly set to use the
464 given path as the base directory.
466 =head2 setup_env_hash_for
470 =item Arguments: path
474 Constructs the C<%ENV> keys for the given path, by calling
475 C<build_environment_vars_for>.
477 =head2 install_base_perl_path
481 =item Arguments: path
485 Returns a path describing where to install the Perl modules for this local
486 library installation. Appends the directories C<lib> and C<perl5> to the given
489 =head2 install_base_arch_path
493 =item Arguments: path
497 Returns a path describing where to install the architecture-specific Perl
498 modules for this local library installation. Based on the
499 L</install_base_perl_path> method's return value, and appends the value of
500 C<$Config{archname}>.
502 =head2 install_base_bin_path
506 =item Arguments: path
510 Returns a path describing where to install the executable programs for this
511 local library installation. Based on the L</install_base_perl_path> method's
512 return value, and appends the directory C<bin>.
514 =head2 modulebuildrc_path
518 =item Arguments: path
522 Returns a path describing where to install the C<.modulebuildrc> file, based on
525 =head2 resolve_empty_path
529 =item Arguments: path
533 Builds and returns the base path into which to set up the local module
534 installation. Defaults to C<~/perl5>.
536 =head2 resolve_home_path
540 =item Arguments: path
544 Attempts to find the user's home directory. If installed, uses C<File::HomeDir>
545 for this purpose. If no definite answer is available, throws an exception.
547 =head2 resolve_relative_path
551 =item Arguments: path
555 Translates the given path into an absolute path.
561 =item Arguments: path
565 Calls the following in a pipeline, passing the result from the previous to the
566 next, in an attempt to find where to configure the environment for a local
567 library installation: L</resolve_empty_path>, L</resolve_home_path>,
568 L</resolve_relative_path>. Passes the given path argument to
569 L</resolve_empty_path> which then returns a result that is passed to
570 L</resolve_home_path>, which then has its result passed to
571 L</resolve_relative_path>. The result of this final call is returned from
574 =head1 A WARNING ABOUT UNINST=1
576 Be careful about using local::lib in combination with "make install UNINST=1".
577 The idea of this feature is that will uninstall an old version of a module
578 before installing a new one. However it lacks a safety check that the old
579 version and the new version will go in the same directory. Used in combination
580 with local::lib, you can potentially delete a globally accessible version of a
581 module while installing the new version in a local place. Only combine "make
582 install UNINST=1" and local::lib if you understand these possible consequences.
586 Rather basic shell detection. Right now anything with csh in its name is
587 assumed to be a C shell or something compatible, and everything else is assumed
588 to be Bourne. If the C<SHELL> environment variable is not set, a
589 Bourne-compatible shell is assumed.
591 Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even if you
592 have CPANPLUS installed.
594 Kills any existing PERL5LIB, PERL_MM_OPT or MODULEBUILDRC.
596 Should probably auto-fixup CPAN config if not already done.
598 Patches very much welcome for any of the above.
600 =head1 TROUBLESHOOTING
602 If you've configured local::lib to install CPAN modules somewhere in to your
603 home directory, and at some point later you try to install a module with C<cpan
604 -i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
605 permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
606 /usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
607 error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
608 you've somehow lost your updated ExtUtils::MakeMaker module.
610 To remedy this situation, rerun the bootstrapping procedure documented above.
612 Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
614 Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
622 local::lib looks at the user's C<SHELL> environment variable when printing out
623 commands to add to the shell configuration file.
629 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
631 auto_install fixes kindly sponsored by http://www.takkle.com/
635 Patches to correctly output commands for csh style shells, as well as some
636 documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
638 '--self-contained' feature contributed by Mark Stosberg <mark@summersault.com>.
640 Doc patches for a custom local::lib directory contributed by Torsten Raudssus
641 <torsten@raudssus.de>.
643 Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
644 things will install properly, submitted a fix for the bug causing problems with
645 writing Makefiles during bootstrapping, contributed an example program, and
646 submitted yet another fix to ensure that local::lib can install and bootstrap
647 properly. Many, many thanks!
649 pattern of Freenode IRC contributed the beginnings of the Troubleshooting
650 section. Many thanks!
654 This library is free software under the same license as perl itself