X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2Flocal%2Flib.pm;h=a5f463a61843d8c2cc12909ad206c336fa19074e;hb=752af3ad8da1a50dd2be9231526235a78b712b94;hp=79201497336ec3297bccd6455db495397944356d;hpb=67502693237dae374a11cae2e91bac57d2d8e4c9;p=p5sagit%2Flocal-lib.git diff --git a/lib/local/lib.pm b/lib/local/lib.pm index 7920149..a5f463a 100644 --- a/lib/local/lib.pm +++ b/lib/local/lib.pm @@ -8,7 +8,7 @@ use 5.006; use File::Spec (); use Config; -our $VERSION = '1.008026'; # 1.8.26 +our $VERSION = '2.000_000'; # 2.0.0 $VERSION = eval $VERSION; sub import { @@ -16,6 +16,7 @@ sub import { my @steps; my %opts; + my $shelltype; while (@args) { my $arg = shift @args; @@ -52,8 +53,7 @@ DEATH push @steps, ['deactivate_all']; } elsif ( $arg =~ /^--shelltype(?:=(.*))?$/ ) { - my $shell = defined $1 ? $1 : shift @args; - $opts{shelltype} = $shell; + $shelltype = defined $1 ? $1 : shift @args; } elsif ( $arg eq '--no-create' ) { $opts{no_create} = 1; @@ -77,7 +77,7 @@ DEATH } if ($0 eq '-') { - $self->print_environment_vars; + print $self->environment_vars_string($shelltype); exit 0; } else { @@ -169,12 +169,12 @@ sub _mb_escape_path { sub installer_options_for { my ($class, $path) = @_; - return { + return ( PERL_MM_OPT => defined $path ? "INSTALL_BASE="._mm_escape_path($path) : undef, PERL_MB_OPT => defined $path ? "--install_base "._mb_escape_path($path) : undef, - }; + ); } sub active_paths { @@ -212,7 +212,7 @@ sub deactivate { roots => [ _remove_from($self->roots, $path) ], ); - $args{extra} = $self->installer_options_for($args{roots}[0]); + $args{extra} = { $self->installer_options_for($args{roots}[0]) }; $self->clone(%args); } @@ -236,7 +236,7 @@ sub deactivate_all { ); } - $args{extra} = $self->installer_options_for(undef); + $args{extra} = { $self->installer_options_for(undef) }; $self->clone(%args); } @@ -266,7 +266,7 @@ sub activate { ); } - $args{extra} = $self->installer_options_for($path); + $args{extra} = { $self->installer_options_for($path) }; $self->clone(%args); } @@ -321,12 +321,7 @@ sub setup_env_hash { } sub print_environment_vars_for { - my $self = $_[0]->new->activate($_[1]); - $self->print_environment_vars; -} -sub print_environment_vars { - my $self = shift; - print $self->environment_vars_string; + print $_[0]->environment_vars_string_for(@_[1..$#_]); } sub environment_vars_string_for { @@ -334,9 +329,11 @@ sub environment_vars_string_for { $self->environment_vars_string; } sub environment_vars_string { - my $self = shift; + my ($self, $shelltype) = @_; + + $shelltype ||= $self->guess_shelltype; - my $build_method = 'build_' . $self->shelltype . '_env_declaration'; + my $build_method = "build_${shelltype}_env_declaration"; my @envs = ( PATH => $self->bins, @@ -383,7 +380,7 @@ sub build_bourne_env_declaration { $value =~ s/(^|\G|$_path_sep)\$$name$_path_sep/$1\$$name\${$name+$_path_sep}/g; $value =~ s/$_path_sep\$$name$/\${$name+$_path_sep}\$$name/; - qq{export ${name}="$value";\n} + qq{${name}="$value";\nexport ${name};\n} } sub build_csh_env_declaration { @@ -657,6 +654,10 @@ From the shell - export PERL5LIB="/home/username/perl5/lib/perl5" export PATH="/home/username/perl5/bin:$PATH" +From a .bashrc file - + + [ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)" + =head2 The bootstrapping technique A typical way to install local::lib is using what is known as the @@ -673,12 +674,18 @@ By default local::lib installs itself and the CPAN modules into ~/perl5. Windows users must also see L. -1. Download and unpack the local::lib tarball from CPAN (search for "Download" +=over 4 + +=item 1. + +Download and unpack the local::lib tarball from CPAN (search for "Download" on the CPAN page about local::lib). Do this as an ordinary user, not as root or administrator. Unpack the file in your home directory or in any other convenient location. -2. Run this: +=item 2. + +Run this: perl Makefile.PL --bootstrap @@ -690,16 +697,20 @@ to specify the name of the directory when you call bootstrap, as follows: perl Makefile.PL --bootstrap=~/foo -3. Run this: (local::lib assumes you have make installed on your system) +=item 3. + +Run this: (local::lib assumes you have make installed on your system) make test && make install -4. Now we need to setup the appropriate environment variables, so that Perl +=item 4. + +Now we need to setup the appropriate environment variables, so that Perl starts using our newly generated lib/ directory. If you are using bash or any other Bourne shells, you can add this to your shell startup script this way: - echo 'eval $(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)' >>~/.bashrc + echo '[ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc If you are using C shell, you can do this as follows: @@ -712,12 +723,14 @@ If you passed to bootstrap a directory other than default, you also need to give that as import parameter to the call of the local::lib module like this way: - echo 'eval $(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)' >>~/.bashrc + echo '[ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc After writing your shell configuration file, be sure to re-read it to get the changed settings into your current shell's environment. Bourne shells use C<. ~/.bashrc> for this, whereas C shells use C. +=back + If you're on a slower machine, or are operating under draconian disk space limitations, you can disable the automatic generation of manpages from POD when installing modules by using the C<--no-manpages> argument when bootstrapping: @@ -737,6 +750,12 @@ installation to install modules in different directories directly this way: cd ../mydir2 ... REPEAT ... +When used in a C<.bashrc> file, it is recommended that you protect against +re-activating a directory in a sub-shell. This can be done by checking the +C<$SHLVL> variable as shown in synopsis. Without this, sub-shells created by +the user or other programs will override changes made to the parent shell's +environment. + If you are working with several C environments, you may want to remove some of them from the current environment without disturbing the others. You can deactivate one environment like this (using bourne sh): @@ -795,7 +814,7 @@ and the subdirectories are created. =head3 PowerShell -local::lib also supports PowerShell, and an be used with the +local::lib also supports PowerShell, and can be used with the C cmdlet. Invoke-Expression "$(perl -Mlocal::lib)" @@ -850,6 +869,8 @@ values: =item PATH +=item PERL_LOCAL_LIB_ROOT + =back When possible, these will be appended to instead of overwritten entirely. @@ -862,7 +883,7 @@ See L for one way to do this - but note that there are a number of caveats, and the best approach is always to perform a build against a clean perl (i.e. site and vendor as close to empty as possible). -=head1 OPTIONS +=head1 IMPORT OPTIONS Options are values that can be passed to the C import besides the directory to use. They are specified as C @@ -889,7 +910,7 @@ C, or C. Prevents C from creating directories when activating dirs. This is likely to cause issues on Win32 systems. -=head1 METHODS +=head1 CLASS METHODS =head2 ensure_dir_structure_for @@ -971,6 +992,20 @@ Returns a path describing where to install the Perl modules for this local library installation. Appends the directories C and C to the given path. +=head2 lib_paths_for + +=over 4 + +=item Arguments: $path + +=item Return value: @lib_paths + +=back + +Returns the list of paths perl will search for libraries, given a base path. +This includes the base path itself, the architecture specific subdirectory, and +perl version specific subdirectories. These paths may not all exist. + =head2 install_base_bin_path =over 4 @@ -984,6 +1019,19 @@ path. Returns a path describing where to install the executable programs for this local library installation. Appends the directory C to the given path. +=head2 installer_options_for + +=over 4 + +=item Arguments: $path + +=item Return value: %installer_env_vars + +=back + +Returns a hash of environment variables that should be set to cause +installation into the given path. + =head2 resolve_empty_path =over 4 @@ -1041,6 +1089,141 @@ L, which then has its result passed to L. The result of this final call is returned from L. +=head1 OBJECT INTERFACE + +=head2 new + +=over 4 + +=item Arguments: %attributes + +=item Return value: $local_lib + +=back + +Constructs a new C object, representing the current state of +C<@INC> and the relevant environment variables. + +=head1 ATTRIBUTES + +=head2 roots + +An arrayref representing active C directories. + +=head2 inc + +An arrayref representing C<@INC>. + +=head2 libs + +An arrayref representing the PERL5LIB environment variable. + +=head2 bins + +An arrayref representing the PATH environment variable. + +=head2 extra + +A hashref of extra environment variables (e.g. C and +C) + +=head2 no_create + +If set, C will not try to create directories when activating them. + +=head1 OBJECT METHODS + +=head2 clone + +=over 4 + +=item Arguments: %attributes + +=item Return value: $local_lib + +=back + +Constructs a new C object based on the existing one, overriding the +specified attributes. + +=head2 activate + +=over 4 + +=item Arguments: $path + +=item Return value: $new_local_lib + +=back + +Constructs a new instance with the specified path active. + +=head2 deactivate + +=over 4 + +=item Arguments: $path + +=item Return value: $new_local_lib + +=back + +Constructs a new instance with the specified path deactivated. + +=head2 deactivate_all + +=over 4 + +=item Arguments: None + +=item Return value: $new_local_lib + +=back + +Constructs a new instance with all C directories deactivated. + +=head2 environment_vars_string + +=over 4 + +=item Arguments: [ $shelltype ] + +=item Return value: $shell_env_string + +=back + +Returns a string to set up the C, meant to be run by a shell. + +=head2 build_environment_vars + +=over 4 + +=item Arguments: None + +=item Return value: %environment_vars + +=back + +Returns a hash with the variables listed above, properly set to use the +given path as the base directory. + +=head2 setup_env_hash + +=over 4 + +=item Arguments: None + +=item Return value: None + +=back + +Constructs the C<%ENV> keys for the given path, by calling +L. + +=head2 setup_local_lib + +Constructs the C<%ENV> hash using L, and set up C<@INC>. + =head1 A WARNING ABOUT UNINST=1 Be careful about using local::lib in combination with "make install UNINST=1". @@ -1071,6 +1254,24 @@ not set, a Bourne-compatible shell is assumed. =item * Should probably auto-fixup CPAN config if not already done. +=item * local::lib loads L. When used to set shell variables, +this isn't a problem. When used inside a perl script, any L +version inside the local::lib will be ignored. A workaround for this is using +C inside the script instead of using +C directly. + +=item * Conflicts with L's C option. +C uses the C option, as it has more predictable and +sane behavior. If something attempts to use the C option when running +a F, L will refuse to run, as the two +options conflict. This can be worked around by temporarily unsetting the +C environment variable. + +=item * Conflicts with L's C<--prefix> option. Similar to the +previous limitation, but any C<--prefix> option specified will be ignored. +This can be worked around by temporarily unsetting the C +environment variable. + =back Patches very much welcome for any of the above. @@ -1171,9 +1372,12 @@ environment later on contributed by Andrew Rodland . Patch for Carp version mismatch contributed by Hakim Cassimally . +Rewrite of internals and numerous bug fixes and added features contributed by +Graham Knop . + =head1 COPYRIGHT -Copyright (c) 2007 - 2010 the local::lib L and L as +Copyright (c) 2007 - 2013 the local::lib L and L as listed above. =head1 LICENSE