lib/local/lib.pm

   1 use strict;
   2 use warnings;
   3
   4 package local::lib;
   5
   6 use 5.008001; # probably works with earlier versions but I'm not supporting them
   7               # (patches would, of course, be welcome)
   8
   9 use File::Spec ();
  10 use File::Path ();
  11 use Carp ();
  12 use Config;
  13
  14 our $VERSION = '1.004001'; # 1.4.1
  15
  16 sub import {
  17   my ($class, @args) = @_;
  18
  19   # Remember what PERL5LIB was when we started
  20   my $perl5lib = $ENV{PERL5LIB};
  21
  22   # The path is required, but last in the list, so we pop, not shift here.
  23   my $path = pop @args;
  24   $path = $class->resolve_path($path);
  25   $class->setup_local_lib_for($path);
  26
  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
  31   if ($flag =~ /−/) {
  32       die <<'DEATH';
  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.
  39 DEATH
  40   }
  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} );
  45
  46     # We explicitly set PERL5LIB here (back to what it was originally) to prevent @INC from growing with each invocation
  47     $ENV{PERL5LIB} = $perl5lib;
  48   }
  49   elsif (defined $flag) {
  50       die "unrecognized import argument: $flag";
  51   }
  52
  53   m/(.*)/ and $_ = $1 for @INC; # Untaint @INC
  54 }
  55
  56 sub pipeline;
  57
  58 sub pipeline {
  59   my @methods = @_;
  60   my $last = pop(@methods);
  61   if (@methods) {
  62     \sub {
  63       my ($obj, @args) = @_;
  64       $obj->${pipeline @methods}(
  65         $obj->$last(@args)
  66       );
  67     };
  68   } else {
  69     \sub {
  70       shift->$last(@_);
  71     };
  72   }
  73 }
  74
  75 =begin testing
  76
  77 #:: test pipeline
  78
  79 package local::lib;
  80
  81 { package Foo; sub foo { -$_[1] } sub bar { $_[1]+2 } sub baz { $_[1]+3 } }
  82 my $foo = bless({}, 'Foo');
  83 Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
  84
  85 =end testing
  86
  87 =cut
  88
  89 sub resolve_path {
  90   my ($class, $path) = @_;
  91   $class->${pipeline qw(
  92     resolve_relative_path
  93     resolve_home_path
  94     resolve_empty_path
  95   )}($path);
  96 }
  97
  98 sub resolve_empty_path {
  99   my ($class, $path) = @_;
 100   if (defined $path) {
 101     $path;
 102   } else {
 103     '~/perl5';
 104   }
 105 }
 106
 107 =begin testing
 108
 109 #:: test classmethod setup
 110
 111 my $c = 'local::lib';
 112
 113 =end testing
 114
 115 =begin testing
 116
 117 #:: test classmethod
 118
 119 is($c->resolve_empty_path, '~/perl5');
 120 is($c->resolve_empty_path('foo'), 'foo');
 121
 122 =end testing
 123
 124 =cut
 125
 126 sub resolve_home_path {
 127   my ($class, $path) = @_;
 128   return $path unless ($path =~ /^~/);
 129   my ($user) = ($path =~ /^~([^\/]+)/); # can assume ^~ so undef for 'us'
 130   my $tried_file_homedir;
 131   my $homedir = do {
 132     if (eval { require File::HomeDir } && $File::HomeDir::VERSION >= 0.65) {
 133       $tried_file_homedir = 1;
 134       if (defined $user) {
 135         File::HomeDir->users_home($user);
 136       } else {
 137         File::HomeDir->my_home;
 138       }
 139     } else {
 140       if (defined $user) {
 141         (getpwnam $user)[7];
 142       } else {
 143         if (defined $ENV{HOME}) {
 144           $ENV{HOME};
 145         } else {
 146           (getpwuid $<)[7];
 147         }
 148       }
 149     }
 150   };
 151   unless (defined $homedir) {
 152     Carp::croak(
 153       "Couldn't resolve homedir for "
 154       .(defined $user ? $user : 'current user')
 155       .($tried_file_homedir ? '' : ' - consider installing File::HomeDir')
 156     );
 157   }
 158   $path =~ s/^~[^\/]*/$homedir/;
 159   $path;
 160 }
 161
 162 sub resolve_relative_path {
 163   my ($class, $path) = @_;
 164   File::Spec->rel2abs($path);
 165 }
 166
 167 =begin testing
 168
 169 #:: test classmethod
 170
 171 local *File::Spec::rel2abs = sub { shift; 'FOO'.shift; };
 172 is($c->resolve_relative_path('bar'),'FOObar');
 173
 174 =end testing
 175
 176 =cut
 177
 178 sub setup_local_lib_for {
 179   my ($class, $path) = @_;
 180   $class->ensure_dir_structure_for($path);
 181   if ($0 eq '-') {
 182     $class->print_environment_vars_for($path);
 183     exit 0;
 184   } else {
 185     $class->setup_env_hash_for($path);
 186     unshift(@INC, split(':', $ENV{PERL5LIB}));
 187   }
 188 }
 189
 190 sub modulebuildrc_path {
 191   my ($class, $path) = @_;
 192   File::Spec->catfile($path, '.modulebuildrc');
 193 }
 194
 195 sub install_base_bin_path {
 196   my ($class, $path) = @_;
 197   File::Spec->catdir($path, 'bin');
 198 }
 199
 200 sub install_base_perl_path {
 201   my ($class, $path) = @_;
 202   File::Spec->catdir($path, 'lib', 'perl5');
 203 }
 204
 205 sub install_base_arch_path {
 206   my ($class, $path) = @_;
 207   File::Spec->catdir($class->install_base_perl_path($path), $Config{archname});
 208 }
 209
 210 sub ensure_dir_structure_for {
 211   my ($class, $path) = @_;
 212   unless (-d $path) {
 213     warn "Attempting to create directory ${path}\n";
 214   }
 215   File::Path::mkpath($path);
 216   my $modulebuildrc_path = $class->modulebuildrc_path($path);
 217   if (-e $modulebuildrc_path) {
 218     unless (-f _) {
 219       Carp::croak("${modulebuildrc_path} exists but is not a plain file");
 220     }
 221   } else {
 222     warn "Attempting to create file ${modulebuildrc_path}\n";
 223     open MODULEBUILDRC, '>', $modulebuildrc_path
 224       || Carp::croak("Couldn't open ${modulebuildrc_path} for writing: $!");
 225     print MODULEBUILDRC qq{install  --install_base  ${path}\n}
 226       || Carp::croak("Couldn't write line to ${modulebuildrc_path}: $!");
 227     close MODULEBUILDRC
 228       || Carp::croak("Couldn't close file ${modulebuildrc_path}: $@");
 229   }
 230 }
 231
 232 sub INTERPOLATE_ENV () { 1 }
 233 sub LITERAL_ENV     () { 0 }
 234
 235 sub print_environment_vars_for {
 236   my ($class, $path) = @_;
 237   my @envs = $class->build_environment_vars_for($path, LITERAL_ENV);
 238   my $out = '';
 239
 240   # rather basic csh detection, goes on the assumption that something won't
 241   # call itself csh unless it really is. also, default to bourne in the
 242   # pathological situation where a user doesn't have $ENV{SHELL} defined.
 243   # note also that shells with funny names, like zoid, are assumed to be
 244   # bourne.
 245   my $shellbin = 'sh';
 246   if(defined $ENV{'SHELL'}) {
 247       my @shell_bin_path_parts = File::Spec->splitpath($ENV{'SHELL'});
 248       $shellbin = $shell_bin_path_parts[-1];
 249   }
 250   my $shelltype = do {
 251       local $_ = $shellbin;
 252       if(/csh/) {
 253           'csh'
 254       } else {
 255           'bourne'
 256       }
 257   };
 258
 259   while (@envs) {
 260     my ($name, $value) = (shift(@envs), shift(@envs));
 261     $value =~ s/(\\")/\\$1/g;
 262     $out .= $class->${\"build_${shelltype}_env_declaration"}($name, $value);
 263   }
 264   print $out;
 265 }
 266
 267 # simple routines that take two arguments: an %ENV key and a value. return
 268 # strings that are suitable for passing directly to the relevant shell to set
 269 # said key to said value.
 270 sub build_bourne_env_declaration {
 271   my $class = shift;
 272   my($name, $value) = @_;
 273   return qq{export ${name}="${value}"\n};
 274 }
 275
 276 sub build_csh_env_declaration {
 277   my $class = shift;
 278   my($name, $value) = @_;
 279   return qq{setenv ${name} "${value}"\n};
 280 }
 281
 282 sub setup_env_hash_for {
 283   my ($class, $path) = @_;
 284   my %envs = $class->build_environment_vars_for($path, INTERPOLATE_ENV);
 285   @ENV{keys %envs} = values %envs;
 286 }
 287
 288 sub build_environment_vars_for {
 289   my ($class, $path, $interpolate) = @_;
 290   return (
 291     MODULEBUILDRC => $class->modulebuildrc_path($path),
 292     PERL_MM_OPT => "INSTALL_BASE=${path}",
 293     PERL5LIB => join(':',
 294                   $class->install_base_perl_path($path),
 295                   $class->install_base_arch_path($path),
 296                   ($ENV{PERL5LIB} ?
 297                     ($interpolate == INTERPOLATE_ENV
 298                       ? ($ENV{PERL5LIB})
 299                       : ('$PERL5LIB'))
 300                     : ())
 301                 ),
 302     PATH => join(':',
 303               $class->install_base_bin_path($path),
 304               ($interpolate == INTERPOLATE_ENV
 305                 ? $ENV{PATH}
 306                 : '$PATH')
 307              ),
 308   )
 309 }
 310
 311 =begin testing
 312
 313 #:: test classmethod
 314
 315 File::Path::rmtree('t/var/splat');
 316
 317 $c->ensure_dir_structure_for('t/var/splat');
 318
 319 ok(-d 't/var/splat');
 320
 321 ok(-f 't/var/splat/.modulebuildrc');
 322
 323 =end testing
 324
 325 =head1 NAME
 326
 327 local::lib - create and use a local lib/ for perl modules with PERL5LIB
 328
 329 =head1 SYNOPSIS
 330
 331 In code -
 332
 333   use local::lib; # sets up a local lib at ~/perl5
 334
 335   use local::lib '~/foo'; # same, but ~/foo
 336
 337   # Or...
 338   use FindBin;
 339   use local::lib "$FindBin::Bin/../support";  # app-local support library
 340
 341 From the shell -
 342
 343   # Install LWP and it's missing dependencies to the 'my_lwp' directory
 344   perl -MCPAN -Mlocal::lib=my_lwp -e 'CPAN::install(LWP)'
 345
 346   # Install LWP and *all non-core* dependencies to the 'my_lwp' directory
 347   perl -MCPAN -Mlocal::lib=--self-contained,my_lwp -e 'CPAN::install(LWP)'
 348
 349   # Just print out useful shell commands
 350   $ perl -Mlocal::lib
 351   export MODULEBUILDRC=/home/username/perl/.modulebuildrc
 352   export PERL_MM_OPT='INSTALL_BASE=/home/username/perl'
 353   export PERL5LIB='/home/username/perl/lib/perl5:/home/username/perl/lib/perl5/i386-linux'
 354   export PATH="/home/username/perl/bin:$PATH"
 355
 356 To bootstrap if you don't have local::lib itself installed -
 357
 358   <download local::lib tarball from CPAN, unpack and cd into dir>
 359
 360   $ perl Makefile.PL --bootstrap
 361   $ make test && make install
 362
 363   $ echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc
 364
 365   # Or for C shells...
 366
 367   $ /bin/csh
 368   % echo $SHELL
 369   /bin/csh
 370   % perl -I$HOME/perl5/lib/perl5 -Mlocal::lib >> ~/.cshrc
 371
 372 You can also pass --boostrap=~/foo to get a different location -
 373
 374   $ perl Makefile.PL --bootstrap=~/foo
 375   $ make test && make install
 376
 377   $ echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc
 378
 379 If you want to install multiple Perl module environments, say for application evelopment,
 380 install local::lib globally and then:
 381
 382     $ cd ~/mydir1
 383     $ perl -Mlocal::lib=./
 384     $ eval $(perl -Mlocal::lib=./)  ### To set the environment for this shell alone
 385     $ printenv  ### You will see that ~/mydir1 is in the PERL5LIB
 386     $ perl -MCPAN -e install ...    ### whatever modules you want
 387     $ cd ../mydir2
 388     ... REPEAT ...
 389
 390 For multiple environments for multiple apps you may need to include a modified version of
 391 the C<< use FindBin >> instructions in the "In code" sample above. If you did something like
 392 the above, you have a set of Perl modules at C<< ~/mydir1/lib >>. If you have a script at
 393 C<< ~/mydir1/scripts/myscript.pl >>, you need to tell it where to find the modules you installed
 394 for it at C<< ~/mydir1/lib >>.
 395
 396 In C<< ~/mydir1/scripts/myscript.pl >>:
 397
 398     use strict;
 399     use warnings;
 400     use local::lib "$FindBin::Bin/..";  ### points to ~/mydir1 and local::lib finds lib
 401     use lib "$FindBin::Bin/../lib";     ### points to ~/mydir1/lib
 402
 403 Put this before any BEGIN { ... } blocks that require the modules you installed.
 404
 405 =head1 DESCRIPTION
 406
 407 This module provides a quick, convenient way of bootstrapping a user-local Perl
 408 module library located within the user's home directory. It also constructs and
 409 prints out for the user the list of environment variables using the syntax
 410 appropriate for the user's current shell (as specified by the C<SHELL>
 411 environment variable), suitable for directly adding to one's shell configuration
 412 file.
 413
 414 More generally, local::lib allows for the bootstrapping and usage of a directory
 415 containing Perl modules outside of Perl's C<@INC>. This makes it easier to ship
 416 an application with an app-specific copy of a Perl module, or collection of
 417 modules. Useful in cases like when an upstream maintainer hasn't applied a patch
 418 to a module of theirs that you need for your application.
 419
 420 On import, local::lib sets the following environment variables to appropriate
 421 values:
 422
 423 =over 4
 424
 425 =item MODULEBUILDRC
 426
 427 =item PERL_MM_OPT
 428
 429 =item PERL5LIB
 430
 431 =item PATH
 432
 433 PATH is appended to, rather than clobbered.
 434
 435 =back
 436
 437 These values are then available for reference by any code after import.
 438
 439 =head1 METHODS
 440
 441 =head2 ensure_directory_structure_for
 442
 443 =over 4
 444
 445 =item Arguments: path
 446
 447 =back
 448
 449 Attempts to create the given path, and all required parent directories. Throws
 450 an exception on failure.
 451
 452 =head2 print_environment_vars_for
 453
 454 =over 4
 455
 456 =item Arguments: path
 457
 458 =back
 459
 460 Prints to standard output the variables listed above, properly set to use the
 461 given path as the base directory.
 462
 463 =head2 setup_env_hash_for
 464
 465 =over 4
 466
 467 =item Arguments: path
 468
 469 =back
 470
 471 Constructs the C<%ENV> keys for the given path, by calling
 472 C<build_environment_vars_for>.
 473
 474 =head2 install_base_perl_path
 475
 476 =over 4
 477
 478 =item Arguments: path
 479
 480 =back
 481
 482 Returns a path describing where to install the Perl modules for this local
 483 library installation. Appends the directories C<lib> and C<perl5> to the given
 484 path.
 485
 486 =head2 install_base_arch_path
 487
 488 =over 4
 489
 490 =item Arguments: path
 491
 492 =back
 493
 494 Returns a path describing where to install the architecture-specific Perl
 495 modules for this local library installation. Based on the
 496 L</install_base_perl_path> method's return value, and appends the value of
 497 C<$Config{archname}>.
 498
 499 =head2 install_base_bin_path
 500
 501 =over 4
 502
 503 =item Arguments: path
 504
 505 =back
 506
 507 Returns a path describing where to install the executable programs for this
 508 local library installation. Based on the L</install_base_perl_path> method's
 509 return value, and appends the directory C<bin>.
 510
 511 =head2 modulebuildrc_path
 512
 513 =over 4
 514
 515 =item Arguments: path
 516
 517 =back
 518
 519 Returns a path describing where to install the C<.modulebuildrc> file, based on
 520 the given path.
 521
 522 =head2 resolve_empty_path
 523
 524 =over 4
 525
 526 =item Arguments: path
 527
 528 =back
 529
 530 Builds and returns the base path into which to set up the local module
 531 installation. Defaults to C<~/perl5>.
 532
 533 =head2 resolve_home_path
 534
 535 =over 4
 536
 537 =item Arguments: path
 538
 539 =back
 540
 541 Attempts to find the user's home directory. If installed, uses C<File::HomeDir>
 542 for this purpose. If no definite answer is available, throws an exception.
 543
 544 =head2 resolve_relative_path
 545
 546 =over 4
 547
 548 =item Arguments: path
 549
 550 =back
 551
 552 Translates the given path into an absolute path.
 553
 554 =head2 resolve_path
 555
 556 =over 4
 557
 558 =item Arguments: path
 559
 560 =back
 561
 562 Calls the following in a pipeline, passing the result from the previous to the
 563 next, in an attempt to find where to configure the environment for a local
 564 library installation: L</resolve_empty_path>, L</resolve_home_path>,
 565 L</resolve_relative_path>. Passes the given path argument to
 566 L</resolve_empty_path> which then returns a result that is passed to
 567 L</resolve_home_path>, which then has its result passed to
 568 L</resolve_relative_path>. The result of this final call is returned from
 569 L</resolve_path>.
 570
 571 =head1 A WARNING ABOUT UNINST=1
 572
 573 Be careful about using local::lib in combination with "make install UNINST=1".
 574 The idea of this feature is that will uninstall an old version of a module
 575 before installing a new one. However it lacks a safety check that the old
 576 version and the new version will go in the same directory. Used in combination
 577 with local::lib, you can potentially delete a globally accessible version of a
 578 module while installing the new version in a local place. Only combine "make
 579 install UNINST=1" and local::lib if you understand these possible consequences.
 580
 581 =head1 LIMITATIONS
 582
 583 Rather basic shell detection. Right now anything with csh in its name is
 584 assumed to be a C shell or something compatible, and everything else is assumed
 585 to be Bourne. If the C<SHELL> environment variable is not set, a
 586 Bourne-compatible shell is assumed.
 587
 588 Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even if you
 589 have CPANPLUS installed.
 590
 591 Kills any existing PERL5LIB, PERL_MM_OPT or MODULEBUILDRC.
 592
 593 Should probably auto-fixup CPAN config if not already done.
 594
 595 Patches very much welcome for any of the above.
 596
 597 =head1 TROUBLESHOOTING
 598
 599 If you've configured local::lib to install CPAN modules somewhere in to your
 600 home directory, and at some point later you try to install a module with C<cpan
 601 -i Foo::Bar>, but it fails with an error like: C<Warning: You do not have
 602 permissions to install into /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
 603 /usr/lib64/perl5/5.8.8/Foo/Bar.pm> and buried within the install log is an
 604 error saying C<'INSTALL_BASE' is not a known MakeMaker parameter name>, then
 605 you've somehow lost your updated ExtUtils::MakeMaker module.
 606
 607 To remedy this situation, rerun the bootstrapping procedure documented above.
 608
 609 Then, run C<rm -r ~/.cpan/build/Foo-Bar*>
 610
 611 Finally, re-run C<cpan -i Foo::Bar> and it should install without problems.
 612
 613 =head1 ENVIRONMENT
 614
 615 =over 4
 616
 617 =item SHELL
 618
 619 local::lib looks at the user's C<SHELL> environment variable when printing out
 620 commands to add to the shell configuration file.
 621
 622 =back
 623
 624 =head1 AUTHOR
 625
 626 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
 627
 628 auto_install fixes kindly sponsored by http://www.takkle.com/
 629
 630 =head1 CONTRIBUTORS
 631
 632 Patches to correctly output commands for csh style shells, as well as some
 633 documentation additions, contributed by Christopher Nehren <apeiron@cpan.org>.
 634
 635 '--self-contained' feature contributed by Mark Stosberg <mark@summersault.com>.
 636
 637 Doc patches for a custom local::lib directory contributed by Torsten Raudssus
 638 <torsten@raudssus.de>.
 639
 640 Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for ensuring
 641 things will install properly, submitted a fix for the bug causing problems with
 642 writing Makefiles during bootstrapping, contributed an example program, and
 643 submitted yet another fix to ensure that local::lib can install and bootstrap
 644 properly. Many, many thanks!
 645
 646 pattern of Freenode IRC contributed the beginnings of the Troubleshooting
 647 section. Many thanks!
 648
 649 =head1 LICENSE
 650
 651 This library is free software under the same license as perl itself
 652
 653 =cut
 654
 655 1;