|
Packit Service |
992def |
NAME
|
|
Packit Service |
992def |
local::lib - create and use a local lib/ for perl modules with PERL5LIB
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
SYNOPSIS
|
|
Packit Service |
992def |
In code -
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
use local::lib; # sets up a local lib at ~/perl5
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
use local::lib '~/foo'; # same, but ~/foo
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
# Or...
|
|
Packit Service |
992def |
use FindBin;
|
|
Packit Service |
992def |
use local::lib "$FindBin::Bin/../support"; # app-local support library
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
From the shell -
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
# Install LWP and its missing dependencies to the '~/perl5' directory
|
|
Packit Service |
992def |
perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
# Just print out useful shell commands
|
|
Packit Service |
992def |
$ perl -Mlocal::lib
|
|
Packit Service |
992def |
PERL_MB_OPT='--install_base /home/username/perl5'; export PERL_MB_OPT;
|
|
Packit Service |
992def |
PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'; export PERL_MM_OPT;
|
|
Packit Service |
992def |
PERL5LIB="/home/username/perl5/lib/perl5"; export PERL5LIB;
|
|
Packit Service |
992def |
PATH="/home/username/perl5/bin:$PATH"; export PATH;
|
|
Packit Service |
992def |
PERL_LOCAL_LIB_ROOT="/home/usename/perl5:$PERL_LOCAL_LIB_ROOT"; export PERL_LOCAL_LIB_ROOT;
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
From a .bash_profile or .bashrc file -
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
The bootstrapping technique
|
|
Packit Service |
992def |
A typical way to install local::lib is using what is known as the
|
|
Packit Service |
992def |
"bootstrapping" technique. You would do this if your system
|
|
Packit Service |
992def |
administrator hasn't already installed local::lib. In this case, you'll
|
|
Packit Service |
992def |
need to install local::lib in your home directory.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Even if you do have administrative privileges, you will still want to
|
|
Packit Service |
992def |
set up your environment variables, as discussed in step 4. Without this,
|
|
Packit Service |
992def |
you would still install the modules into the system CPAN installation
|
|
Packit Service |
992def |
and also your Perl scripts will not use the lib/ path you bootstrapped
|
|
Packit Service |
992def |
with local::lib.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
By default local::lib installs itself and the CPAN modules into ~/perl5.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Windows users must also see "Differences when using this module under
|
|
Packit Service |
992def |
Win32".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
1. Download and unpack the local::lib tarball from CPAN (search for
|
|
Packit Service |
992def |
"Download" on the CPAN page about local::lib). Do this as an
|
|
Packit Service |
992def |
ordinary user, not as root or administrator. Unpack the file in your
|
|
Packit Service |
992def |
home directory or in any other convenient location.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
2. Run this:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
perl Makefile.PL --bootstrap
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If the system asks you whether it should automatically configure as
|
|
Packit Service |
992def |
much as possible, you would typically answer yes.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
In order to install local::lib into a directory other than the
|
|
Packit Service |
992def |
default, you need to specify the name of the directory when you call
|
|
Packit Service |
992def |
bootstrap, as follows:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
perl Makefile.PL --bootstrap=~/foo
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
3. Run this: (local::lib assumes you have make installed on your
|
|
Packit Service |
992def |
system)
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
make test && make install
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
4. Now we need to setup the appropriate environment variables, so that
|
|
Packit Service |
992def |
Perl starts using our newly generated lib/ directory. If you are
|
|
Packit Service |
992def |
using bash or any other Bourne shells, you can add this to your
|
|
Packit Service |
992def |
shell startup script this way:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
echo 'eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If you are using C shell, you can do this as follows:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
/bin/csh
|
|
Packit Service |
992def |
echo $SHELL
|
|
Packit Service |
992def |
/bin/csh
|
|
Packit Service |
992def |
echo 'eval `perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >> ~/.cshrc
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If you passed to bootstrap a directory other than default, you also
|
|
Packit Service |
992def |
need to give that as import parameter to the call of the local::lib
|
|
Packit Service |
992def |
module like this way:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
echo 'eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
After writing your shell configuration file, be sure to re-read it
|
|
Packit Service |
992def |
to get the changed settings into your current shell's environment.
|
|
Packit Service |
992def |
Bourne shells use ". ~/.bashrc" for this, whereas C shells use
|
|
Packit Service |
992def |
"source ~/.cshrc".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If you're on a slower machine, or are operating under draconian disk
|
|
Packit Service |
992def |
space limitations, you can disable the automatic generation of manpages
|
|
Packit Service |
992def |
from POD when installing modules by using the "--no-manpages" argument
|
|
Packit Service |
992def |
when bootstrapping:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
perl Makefile.PL --bootstrap --no-manpages
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
To avoid doing several bootstrap for several Perl module environments on
|
|
Packit Service |
992def |
the same account, for example if you use it for several different
|
|
Packit Service |
992def |
deployed applications independently, you can use one bootstrapped
|
|
Packit Service |
992def |
local::lib installation to install modules in different directories
|
|
Packit Service |
992def |
directly this way:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
cd ~/mydir1
|
|
Packit Service |
992def |
perl -Mlocal::lib=./
|
|
Packit Service |
992def |
eval $(perl -Mlocal::lib=./) ### To set the environment for this shell alone
|
|
Packit Service |
992def |
printenv ### You will see that ~/mydir1 is in the PERL5LIB
|
|
Packit Service |
992def |
perl -MCPAN -e install ... ### whatever modules you want
|
|
Packit Service |
992def |
cd ../mydir2
|
|
Packit Service |
992def |
... REPEAT ...
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If you use .bashrc to activate a local::lib automatically, the
|
|
Packit Service |
992def |
local::lib will be re-enabled in any sub-shells used, overriding
|
|
Packit Service |
992def |
adjustments you may have made in the parent shell. To avoid this, you
|
|
Packit Service |
992def |
can initialize the local::lib in .bash_profile rather than .bashrc, or
|
|
Packit Service |
992def |
protect the local::lib invocation with a $SHLVL check:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
[ $SHLVL -eq 1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If you are working with several "local::lib" environments, you may want
|
|
Packit Service |
992def |
to remove some of them from the current environment without disturbing
|
|
Packit Service |
992def |
the others. You can deactivate one environment like this (using bourne
|
|
Packit Service |
992def |
sh):
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
eval $(perl -Mlocal::lib=--deactivate,~/path)
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
which will generate and run the commands needed to remove "~/path" from
|
|
Packit Service |
992def |
your various search paths. Whichever environment was activated most
|
|
Packit Service |
992def |
recently will remain the target for module installations. That is, if
|
|
Packit Service |
992def |
you activate "~/path_A" and then you activate "~/path_B", new modules
|
|
Packit Service |
992def |
you install will go in "~/path_B". If you deactivate "~/path_B" then
|
|
Packit Service |
992def |
modules will be installed into "~/pathA" -- but if you deactivate
|
|
Packit Service |
992def |
"~/path_A" then they will still be installed in "~/pathB" because pathB
|
|
Packit Service |
992def |
was activated later.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
You can also ask "local::lib" to clean itself completely out of the
|
|
Packit Service |
992def |
current shell's environment with the "--deactivate-all" option. For
|
|
Packit Service |
992def |
multiple environments for multiple apps you may need to include a
|
|
Packit Service |
992def |
modified version of the "use FindBin" instructions in the "In code"
|
|
Packit Service |
992def |
sample above. If you did something like the above, you have a set of
|
|
Packit Service |
992def |
Perl modules at "~/mydir1/lib". If you have a script at
|
|
Packit Service |
992def |
"~/mydir1/scripts/myscript.pl", you need to tell it where to find the
|
|
Packit Service |
992def |
modules you installed for it at "~/mydir1/lib".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
In "~/mydir1/scripts/myscript.pl":
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
use strict;
|
|
Packit Service |
992def |
use warnings;
|
|
Packit Service |
992def |
use local::lib "$FindBin::Bin/.."; ### points to ~/mydir1 and local::lib finds lib
|
|
Packit Service |
992def |
use lib "$FindBin::Bin/../lib"; ### points to ~/mydir1/lib
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Put this before any BEGIN { ... } blocks that require the modules you
|
|
Packit Service |
992def |
installed.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Differences when using this module under Win32
|
|
Packit Service |
992def |
To set up the proper environment variables for your current session of
|
|
Packit Service |
992def |
"CMD.exe", you can use this:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
C:\>perl -Mlocal::lib
|
|
Packit Service |
992def |
set PERL_MB_OPT=--install_base C:\DOCUME~1\ADMINI~1\perl5
|
|
Packit Service |
992def |
set PERL_MM_OPT=INSTALL_BASE=C:\DOCUME~1\ADMINI~1\perl5
|
|
Packit Service |
992def |
set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5
|
|
Packit Service |
992def |
set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
### To set the environment for this shell alone
|
|
Packit Service |
992def |
C:\>perl -Mlocal::lib > %TEMP%\tmp.bat && %TEMP%\tmp.bat && del %TEMP%\tmp.bat
|
|
Packit Service |
992def |
### instead of $(perl -Mlocal::lib=./)
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If you want the environment entries to persist, you'll need to add them
|
|
Packit Service |
992def |
to the Control Panel's System applet yourself or use
|
|
Packit Service |
992def |
App::local::lib::Win32Helper.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
The "~" is translated to the user's profile directory (the directory
|
|
Packit Service |
992def |
named for the user under "Documents and Settings" (Windows XP or
|
|
Packit Service |
992def |
earlier) or "Users" (Windows Vista or later)) unless $ENV{HOME} exists.
|
|
Packit Service |
992def |
After that, the home directory is translated to a short name (which
|
|
Packit Service |
992def |
means the directory must exist) and the subdirectories are created.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
PowerShell
|
|
Packit Service |
992def |
local::lib also supports PowerShell, and can be used with the
|
|
Packit Service |
992def |
"Invoke-Expression" cmdlet.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Invoke-Expression "$(perl -Mlocal::lib)"
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
RATIONALE
|
|
Packit Service |
992def |
The version of a Perl package on your machine is not always the version
|
|
Packit Service |
992def |
you need. Obviously, the best thing to do would be to update to the
|
|
Packit Service |
992def |
version you need. However, you might be in a situation where you're
|
|
Packit Service |
992def |
prevented from doing this. Perhaps you don't have system administrator
|
|
Packit Service |
992def |
privileges; or perhaps you are using a package management system such as
|
|
Packit Service |
992def |
Debian, and nobody has yet gotten around to packaging up the version you
|
|
Packit Service |
992def |
need.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
local::lib solves this problem by allowing you to create your own
|
|
Packit Service |
992def |
directory of Perl packages downloaded from CPAN (in a multi-user system,
|
|
Packit Service |
992def |
this would typically be within your own home directory). The existing
|
|
Packit Service |
992def |
system Perl installation is not affected; you simply invoke Perl with
|
|
Packit Service |
992def |
special options so that Perl uses the packages in your own local package
|
|
Packit Service |
992def |
directory rather than the system packages. local::lib arranges things so
|
|
Packit Service |
992def |
that your locally installed version of the Perl packages takes
|
|
Packit Service |
992def |
precedence over the system installation.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
If you are using a package management system (such as Debian), you don't
|
|
Packit Service |
992def |
need to worry about Debian and CPAN stepping on each other's toes. Your
|
|
Packit Service |
992def |
local version of the packages will be written to an entirely separate
|
|
Packit Service |
992def |
directory from those installed by Debian.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
DESCRIPTION
|
|
Packit Service |
992def |
This module provides a quick, convenient way of bootstrapping a
|
|
Packit Service |
992def |
user-local Perl module library located within the user's home directory.
|
|
Packit Service |
992def |
It also constructs and prints out for the user the list of environment
|
|
Packit Service |
992def |
variables using the syntax appropriate for the user's current shell (as
|
|
Packit Service |
992def |
specified by the "SHELL" environment variable), suitable for directly
|
|
Packit Service |
992def |
adding to one's shell configuration file.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
More generally, local::lib allows for the bootstrapping and usage of a
|
|
Packit Service |
992def |
directory containing Perl modules outside of Perl's @INC. This makes it
|
|
Packit Service |
992def |
easier to ship an application with an app-specific copy of a Perl
|
|
Packit Service |
992def |
module, or collection of modules. Useful in cases like when an upstream
|
|
Packit Service |
992def |
maintainer hasn't applied a patch to a module of theirs that you need
|
|
Packit Service |
992def |
for your application.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
On import, local::lib sets the following environment variables to
|
|
Packit Service |
992def |
appropriate values:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
PERL_MB_OPT
|
|
Packit Service |
992def |
PERL_MM_OPT
|
|
Packit Service |
992def |
PERL5LIB
|
|
Packit Service |
992def |
PATH
|
|
Packit Service |
992def |
PERL_LOCAL_LIB_ROOT
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
When possible, these will be appended to instead of overwritten
|
|
Packit Service |
992def |
entirely.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
These values are then available for reference by any code after import.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
CREATING A SELF-CONTAINED SET OF MODULES
|
|
Packit Service |
992def |
See lib::core::only for one way to do this - but note that there are a
|
|
Packit Service |
992def |
number of caveats, and the best approach is always to perform a build
|
|
Packit Service |
992def |
against a clean perl (i.e. site and vendor as close to empty as
|
|
Packit Service |
992def |
possible).
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
IMPORT OPTIONS
|
|
Packit Service |
992def |
Options are values that can be passed to the "local::lib" import besides
|
|
Packit Service |
992def |
the directory to use. They are specified as "use local::lib '--option'[,
|
|
Packit Service |
992def |
path];" or "perl -Mlocal::lib=--option[,path]".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
--deactivate
|
|
Packit Service |
992def |
Remove the chosen path (or the default path) from the module search
|
|
Packit Service |
992def |
paths if it was added by "local::lib", instead of adding it.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
--deactivate-all
|
|
Packit Service |
992def |
Remove all directories that were added to search paths by "local::lib"
|
|
Packit Service |
992def |
from the search paths.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
--shelltype
|
|
Packit Service |
992def |
Specify the shell type to use for output. By default, the shell will be
|
|
Packit Service |
992def |
detected based on the environment. Should be one of: "bourne", "csh",
|
|
Packit Service |
992def |
"cmd", or "powershell".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
--no-create
|
|
Packit Service |
992def |
Prevents "local::lib" from creating directories when activating dirs.
|
|
Packit Service |
992def |
This is likely to cause issues on Win32 systems.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
CLASS METHODS
|
|
Packit Service |
992def |
ensure_dir_structure_for
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: None
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Attempts to create a local::lib directory, including subdirectories and
|
|
Packit Service |
992def |
all required parent directories. Throws an exception on failure.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
print_environment_vars_for
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: None
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Prints to standard output the variables listed above, properly set to
|
|
Packit Service |
992def |
use the given path as the base directory.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
build_environment_vars_for
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: %environment_vars
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns a hash with the variables listed above, properly set to use the
|
|
Packit Service |
992def |
given path as the base directory.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
setup_env_hash_for
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: None
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Constructs the %ENV keys for the given path, by calling
|
|
Packit Service |
992def |
"build_environment_vars_for".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
active_paths
|
|
Packit Service |
992def |
Arguments: None
|
|
Packit Service |
992def |
Return value: @paths
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns a list of active "local::lib" paths, according to the
|
|
Packit Service |
992def |
"PERL_LOCAL_LIB_ROOT" environment variable and verified against what is
|
|
Packit Service |
992def |
really in @INC.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
install_base_perl_path
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $install_base_perl_path
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns a path describing where to install the Perl modules for this
|
|
Packit Service |
992def |
local library installation. Appends the directories "lib" and "perl5" to
|
|
Packit Service |
992def |
the given path.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
lib_paths_for
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: @lib_paths
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns the list of paths perl will search for libraries, given a base
|
|
Packit Service |
992def |
path. This includes the base path itself, the architecture specific
|
|
Packit Service |
992def |
subdirectory, and perl version specific subdirectories. These paths may
|
|
Packit Service |
992def |
not all exist.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
install_base_bin_path
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $install_base_bin_path
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns a path describing where to install the executable programs for
|
|
Packit Service |
992def |
this local library installation. Appends the directory "bin" to the
|
|
Packit Service |
992def |
given path.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
installer_options_for
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: %installer_env_vars
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns a hash of environment variables that should be set to cause
|
|
Packit Service |
992def |
installation into the given path.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
resolve_empty_path
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $base_path
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Builds and returns the base path into which to set up the local module
|
|
Packit Service |
992def |
installation. Defaults to "~/perl5".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
resolve_home_path
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $home_path
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Attempts to find the user's home directory. If installed, uses
|
|
Packit Service |
992def |
"File::HomeDir" for this purpose. If no definite answer is available,
|
|
Packit Service |
992def |
throws an exception.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
resolve_relative_path
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $absolute_path
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Translates the given path into an absolute path.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
resolve_path
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $absolute_path
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Calls the following in a pipeline, passing the result from the previous
|
|
Packit Service |
992def |
to the next, in an attempt to find where to configure the environment
|
|
Packit Service |
992def |
for a local library installation: "resolve_empty_path",
|
|
Packit Service |
992def |
"resolve_home_path", "resolve_relative_path". Passes the given path
|
|
Packit Service |
992def |
argument to "resolve_empty_path" which then returns a result that is
|
|
Packit Service |
992def |
passed to "resolve_home_path", which then has its result passed to
|
|
Packit Service |
992def |
"resolve_relative_path". The result of this final call is returned from
|
|
Packit Service |
992def |
"resolve_path".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
OBJECT INTERFACE
|
|
Packit Service |
992def |
new
|
|
Packit Service |
992def |
Arguments: %attributes
|
|
Packit Service |
992def |
Return value: $local_lib
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Constructs a new "local::lib" object, representing the current state of
|
|
Packit Service |
992def |
@INC and the relevant environment variables.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
ATTRIBUTES
|
|
Packit Service |
992def |
roots
|
|
Packit Service |
992def |
An arrayref representing active "local::lib" directories.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
inc
|
|
Packit Service |
992def |
An arrayref representing @INC.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
libs
|
|
Packit Service |
992def |
An arrayref representing the PERL5LIB environment variable.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
bins
|
|
Packit Service |
992def |
An arrayref representing the PATH environment variable.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
extra
|
|
Packit Service |
992def |
A hashref of extra environment variables (e.g. "PERL_MM_OPT" and
|
|
Packit Service |
992def |
"PERL_MB_OPT")
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
no_create
|
|
Packit Service |
992def |
If set, "local::lib" will not try to create directories when activating
|
|
Packit Service |
992def |
them.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
OBJECT METHODS
|
|
Packit Service |
992def |
clone
|
|
Packit Service |
992def |
Arguments: %attributes
|
|
Packit Service |
992def |
Return value: $local_lib
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Constructs a new "local::lib" object based on the existing one,
|
|
Packit Service |
992def |
overriding the specified attributes.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
activate
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $new_local_lib
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Constructs a new instance with the specified path active.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
deactivate
|
|
Packit Service |
992def |
Arguments: $path
|
|
Packit Service |
992def |
Return value: $new_local_lib
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Constructs a new instance with the specified path deactivated.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
deactivate_all
|
|
Packit Service |
992def |
Arguments: None
|
|
Packit Service |
992def |
Return value: $new_local_lib
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Constructs a new instance with all "local::lib" directories deactivated.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
environment_vars_string
|
|
Packit Service |
992def |
Arguments: [ $shelltype ]
|
|
Packit Service |
992def |
Return value: $shell_env_string
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns a string to set up the "local::lib", meant to be run by a shell.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
build_environment_vars
|
|
Packit Service |
992def |
Arguments: None
|
|
Packit Service |
992def |
Return value: %environment_vars
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Returns a hash with the variables listed above, properly set to use the
|
|
Packit Service |
992def |
given path as the base directory.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
setup_env_hash
|
|
Packit Service |
992def |
Arguments: None
|
|
Packit Service |
992def |
Return value: None
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Constructs the %ENV keys for the given path, by calling
|
|
Packit Service |
992def |
"build_environment_vars".
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
setup_local_lib
|
|
Packit Service |
992def |
Constructs the %ENV hash using "setup_env_hash", and set up @INC.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
A WARNING ABOUT UNINST=1
|
|
Packit Service |
992def |
Be careful about using local::lib in combination with "make install
|
|
Packit Service |
992def |
UNINST=1". The idea of this feature is that will uninstall an old
|
|
Packit Service |
992def |
version of a module before installing a new one. However it lacks a
|
|
Packit Service |
992def |
safety check that the old version and the new version will go in the
|
|
Packit Service |
992def |
same directory. Used in combination with local::lib, you can potentially
|
|
Packit Service |
992def |
delete a globally accessible version of a module while installing the
|
|
Packit Service |
992def |
new version in a local place. Only combine "make install UNINST=1" and
|
|
Packit Service |
992def |
local::lib if you understand these possible consequences.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
LIMITATIONS
|
|
Packit Service |
992def |
* Directory names with spaces in them are not well supported by the
|
|
Packit Service |
992def |
perl toolchain and the programs it uses. Pure-perl distributions
|
|
Packit Service |
992def |
should support spaces, but problems are more likely with dists that
|
|
Packit Service |
992def |
require compilation. A workaround you can do is moving your
|
|
Packit Service |
992def |
local::lib to a directory with spaces after you installed all
|
|
Packit Service |
992def |
modules inside your local::lib bootstrap. But be aware that you
|
|
Packit Service |
992def |
can't update or install CPAN modules after the move.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
* Rather basic shell detection. Right now anything with csh in its
|
|
Packit Service |
992def |
name is assumed to be a C shell or something compatible, and
|
|
Packit Service |
992def |
everything else is assumed to be Bourne, except on Win32 systems. If
|
|
Packit Service |
992def |
the "SHELL" environment variable is not set, a Bourne-compatible
|
|
Packit Service |
992def |
shell is assumed.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
* Kills any existing PERL_MM_OPT or PERL_MB_OPT.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
* Should probably auto-fixup CPAN config if not already done.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
* On VMS and MacOS Classic (pre-OS X), local::lib loads File::Spec.
|
|
Packit Service |
992def |
This means any File::Spec version installed in the local::lib will
|
|
Packit Service |
992def |
be ignored by scripts using local::lib. A workaround for this is
|
|
Packit Service |
992def |
using "use lib "$local_lib/lib/perl5";" instead of using
|
|
Packit Service |
992def |
"local::lib" directly.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
* Conflicts with ExtUtils::MakeMaker's "PREFIX" option. "local::lib"
|
|
Packit Service |
992def |
uses the "INSTALL_BASE" option, as it has more predictable and sane
|
|
Packit Service |
992def |
behavior. If something attempts to use the "PREFIX" option when
|
|
Packit Service |
992def |
running a Makefile.PL, ExtUtils::MakeMaker will refuse to run, as
|
|
Packit Service |
992def |
the two options conflict. This can be worked around by temporarily
|
|
Packit Service |
992def |
unsetting the "PERL_MM_OPT" environment variable.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
* Conflicts with Module::Build's "--prefix" option. Similar to the
|
|
Packit Service |
992def |
previous limitation, but any "--prefix" option specified will be
|
|
Packit Service |
992def |
ignored. This can be worked around by temporarily unsetting the
|
|
Packit Service |
992def |
"PERL_MB_OPT" environment variable.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Patches very much welcome for any of the above.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
* On Win32 systems, does not have a way to write the created
|
|
Packit Service |
992def |
environment variables to the registry, so that they can persist
|
|
Packit Service |
992def |
through a reboot.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
TROUBLESHOOTING
|
|
Packit Service |
992def |
If you've configured local::lib to install CPAN modules somewhere in to
|
|
Packit Service |
992def |
your home directory, and at some point later you try to install a module
|
|
Packit Service |
992def |
with "cpan -i Foo::Bar", but it fails with an error like: "Warning: You
|
|
Packit Service |
992def |
do not have permissions to install into
|
|
Packit Service |
992def |
/usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
|
|
Packit Service |
992def |
/usr/lib64/perl5/5.8.8/Foo/Bar.pm" and buried within the install log is
|
|
Packit Service |
992def |
an error saying "'INSTALL_BASE' is not a known MakeMaker parameter
|
|
Packit Service |
992def |
name", then you've somehow lost your updated ExtUtils::MakeMaker module.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
To remedy this situation, rerun the bootstrapping procedure documented
|
|
Packit Service |
992def |
above.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Then, run "rm -r ~/.cpan/build/Foo-Bar*"
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Finally, re-run "cpan -i Foo::Bar" and it should install without
|
|
Packit Service |
992def |
problems.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
ENVIRONMENT
|
|
Packit Service |
992def |
SHELL
|
|
Packit Service |
992def |
COMSPEC
|
|
Packit Service |
992def |
local::lib looks at the user's "SHELL" environment variable when
|
|
Packit Service |
992def |
printing out commands to add to the shell configuration file.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
On Win32 systems, "COMSPEC" is also examined.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
SEE ALSO
|
|
Packit Service |
992def |
* Perl Advent article, 2011
|
|
Packit Service |
992def |
<http://perladvent.org/2011/2011-12-01.html>
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
SUPPORT
|
|
Packit Service |
992def |
IRC:
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Join #toolchain on irc.perl.org.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
AUTHOR
|
|
Packit Service |
992def |
Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
auto_install fixes kindly sponsored by http://www.takkle.com/
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
CONTRIBUTORS
|
|
Packit Service |
992def |
Patches to correctly output commands for csh style shells, as well as
|
|
Packit Service |
992def |
some documentation additions, contributed by Christopher Nehren
|
|
Packit Service |
992def |
<apeiron@cpan.org>.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Doc patches for a custom local::lib directory, more cleanups in the
|
|
Packit Service |
992def |
english documentation and a german documentation contributed by Torsten
|
|
Packit Service |
992def |
Raudssus <torsten@raudssus.de>.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Hans Dieter Pearcey <hdp@cpan.org> sent in some additional tests for
|
|
Packit Service |
992def |
ensuring things will install properly, submitted a fix for the bug
|
|
Packit Service |
992def |
causing problems with writing Makefiles during bootstrapping,
|
|
Packit Service |
992def |
contributed an example program, and submitted yet another fix to ensure
|
|
Packit Service |
992def |
that local::lib can install and bootstrap properly. Many, many thanks!
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
pattern of Freenode IRC contributed the beginnings of the
|
|
Packit Service |
992def |
Troubleshooting section. Many thanks!
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Patch to add Win32 support contributed by Curtis Jewell
|
|
Packit Service |
992def |
<csjewell@cpan.org>.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Warnings for missing PATH/PERL5LIB (as when not running interactively)
|
|
Packit Service |
992def |
silenced by a patch from Marco Emilio Poleggi.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Mark Stosberg <mark@summersault.com> provided the code for the now
|
|
Packit Service |
992def |
deleted '--self-contained' option.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Documentation patches to make win32 usage clearer by David Mertens
|
|
Packit Service |
992def |
<dcmertens.perl@gmail.com> (run4flat).
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Brazilian portuguese translation and minor doc patches contributed by
|
|
Packit Service |
992def |
Breno G. de Oliveira <garu@cpan.org>.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Improvements to stacking multiple local::lib dirs and removing them from
|
|
Packit Service |
992def |
the environment later on contributed by Andrew Rodland
|
|
Packit Service |
992def |
<arodland@cpan.org>.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Patch for Carp version mismatch contributed by Hakim Cassimally
|
|
Packit Service |
992def |
<osfameron@cpan.org>.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
Rewrite of internals and numerous bug fixes and added features
|
|
Packit Service |
992def |
contributed by Graham Knop <haarg@haarg.org>.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
COPYRIGHT
|
|
Packit Service |
992def |
Copyright (c) 2007 - 2013 the local::lib "AUTHOR" and "CONTRIBUTORS" as
|
|
Packit Service |
992def |
listed above.
|
|
Packit Service |
992def |
|
|
Packit Service |
992def |
LICENSE
|
|
Packit Service |
992def |
This is free software; you can redistribute it and/or modify it under
|
|
Packit Service |
992def |
the same terms as the Perl 5 programming language system itself.
|
|
Packit Service |
992def |
|