perlbrew - Perl environment manager.
perlbrew command syntax:
perlbrew <command> [options] [arguments]
Commands:
init Initialize perlbrew environment. install Install perl uninstall Uninstall the given installation available List perls available to install lib Manage local::lib directories. alias Give perl installations a new name upgrade-perl Upgrade the current perl list List perl installations use Use the specified perl in current shell off Turn off perlbrew in current shell switch Permanently use the specified perl as default switch-off Permanently turn off perlbrew (revert to system perl) exec exec programs with specified perl enviroments. self-install Install perlbrew itself under PERLBREW_ROOT/bin self-upgrade Upgrade perlbrew itself. install-patchperl Install patchperl install-cpanm Install cpanm, a friendly companion. install-ack Install ack download Download the specified perl distribution tarball. mirror Pick a preferred mirror site version Display version help Read more detailed instructions
Generic command options:
-q --quiet Be quiet on informative output message. -v --verbose Tell me more about it.
See `perlbrew help` for the full documentation of perlbrew, or
See `perlbrew help <command>` for detail description of the command.
By default, perlbrew builds and installs perls into $ENV{HOME}/perl5/perlbrew directory. To use a different directory, set this environment variable in your bashrc to the directory in your shell RC before sourcing perlbrew's RC.
$ENV{HOME}/perl5/perlbrew
bashrc
It is possible to share one perlbrew root with multiple user account on the same machine. Therefore people do not have to install the same version of perl over an over. Let's say /opt/perl5 is the directory we want to share. All users should be able append this snippet to their bashrc to make it effective:
/opt/perl5
export PERLBREW_ROOT=/opt/perl5 source ${PERLBREW_ROOT}/etc/bashrc
After doing so, everone's PATH should include /opt/perl5/bin and /opt/perl5/perls/${PERLBREW_PERL}/bin. Each user can invoke perlbrew switch and perlbrew use to independently switch to different perl environment of their choice. However, only the user with write permission to $PERLBREW_ROOT may install CPAN modules. This is both good and bad depending on the working convention of your team.
/opt/perl5/bin
/opt/perl5/perls/${PERLBREW_PERL}/bin
perlbrew switch
perlbrew use
$PERLBREW_ROOT
If you wish to install CPAN modules only for yourself, you should use the lib command to construct a personal local::lib environment. local::lib environments are personal, and are not shared between different users. For more detail, read perlbrew help lib and the documentation of local::lib.
lib
perlbrew help lib
If you want even a cooler module isolation and wish to install CPAN modules used for just one project, you should use carton for this purpose.
It is also possible to set this variable before installing perlbrew to make perlbrew install itself under the given PERLBREW_ROOT:
export PERLBREW_ROOT=/opt/perl5 curl -kL http://install.perlbrew.pl | bash
After doing this, the perlbrew executable is installed as /opt/perl5/bin/perlbrew
/opt/perl5/bin/perlbrew
By default, perlbrew stores per-user setting to $ENV{HOME}/.perlbrew directory. To use a different directory, set this environment variable in your shell RC before sourcing perlbrew's RC.
$ENV{HOME}/.perlbrew
In some cases, say, your home directory is on NFS and shared across multiple machines, you may wish to have several different perlbrew setting per-machine. To do so, you can use the PERLBREW_HOME environment variable to tell perlbrew where to look for the initialization file. Here's a brief bash snippet for the given senario.
PERLBREW_HOME
if [ "$(hostname)" == "machine-a" ]; then export PERLBREW_HOME=~/.perlbrew-a elif [ "$(hostname)" == "machine-b" ]; then export PERLBREW_HOME=~/.perlbrew-b fi source ~/perl5/perlbrew/etc/bashrc
This environment variable specify the list of command like flags to pass through to 'sh Configure'. By default it is '-de'.
The CPAN mirror url of your choice.
Usage: perlbrew init
The init command should be manually invoked whenever you (the perlbrew user) upgrade or reinstall perlbrew.
init
If the upgrade is done with self-upgrade command, or by running the one-line installer manually, this command is invoked automatically.
self-upgrade
Usage: perlbrew info
The `info` command dumps a page of handful information for the perlbrew installation.
Build and install the given version of perl.
Version numbers usually look like "5.x.xx", or "perl-5.xx.x-RCx" for release candidates.
The specified perl is downloaded from the offical CPAN website or from the mirror site configured before.
To configure mirror site, invoke `mirror` command.
A convenient way to install the most recent stable version of Perl, of those that are available.
A special way to install the blead version of perl, which is downloaded from this specific URL regardless of mirror settings:
http://perl5.git.perl.org/perl.git/snapshot/blead.tar.gz
Build and install from the given git checkout dir.
Build and install from the given archive file.
Build and install from the given URL. Supported URL schemes are http://, https://, ftp:// and file://.
http://
https://
ftp://
file://
Options for install command:
install
-f --force Force installation -j $n Parallel building and testing. ex. C<perlbrew install -j 5 perl-5.14.2> -n --notest Skip testing --switch Automatically switch to this Perl once successfully installed, as if with `perlbrew switch <version>` --as Install the given version of perl by a name. ex. C<perlbrew install perl-5.6.2 --as legacy-perl> -D,-U,-A Switches passed to perl Configure script. ex. C<perlbrew install perl-5.10.1 -D usemymalloc -U uselargefiles> --sitecustomize $filename Specify a file to be installed as sitecustomize.pl
By default, all installations are configured after their name like this:
sh Configure -de -Dprefix=$PERLBREW_ROOT/perls/<name>
Usage: perlbrew uninstall <name>
Uninstalls the given perl installation. The name is the installation name as in the output of `perlbrew list`
Usage: perlbrew use [perl-<version> | <version> | <name>]
Use the given version perl in current shell. This will not effect newly opened shells.
Without a parameter, shows the version of perl currently in use.
Usage: perlbrew switch [ <name> ]
Switch to the given version, and makes it the default for this and all future terminal sessions.
Without a parameter, shows the version of perl currently selected.
Usage: perlbrew list
List the installed versions of perl.
Usage: perlbrew available
List the recently available versions of perl on CPAN.
The list is retrieved from the web page http://www.cpan.org/src/README.html, and is not the list of *all* perl versions ever released in the past.
NOTICE: This command might be gone in the future and becomes an option of 'list' command.
Usage: perlbrew off
Temporarily disable perlbrew in the current shell. Effectively re-enables the default system Perl, whatever that is.
This command works only if you add the statement of `source $PERLBREW_ROOT/etc/bashrc` in your shell initialization (bashrc / zshrc).
Usage: perlbrew switch-off
Permananently disable perlbrew. Use switch command to re-enable it. Invoke use command to enable it only in the current shell.
switch
use
Re-enables the default system Perl, whatever that is.
Usage: perlbrew alias [-f] create <name> <alias>
Create an alias for the installation named <name>.
Usage: perlbrew alias [-f] rename <old_alias> <new_alias>
Rename the alias to a new name.
Usage: perlbrew alias delete <alias>
Delete the given alias.
Usage: perlbrew mirror
Run this if you want to choose a specific CPAN mirror to install the perls from. It will display a list of mirrors for you to pick from. Hit 'q' to cancel the selection.
Usage: perlbrew exec [--with perl-name[,perl-name...]] <command> <args...>
Execute command for each perl installations, one by one.
For example, run a Hello program:
perlbrew exec perl -e 'print "Hello from $]\n"'
The output looks like this:
perl-5.12.2 ========== Hello word from perl-5.012002 perl-5.13.10 ========== Hello word from perl-5.013010 perl-5.14.0 ========== Hello word from perl-5.014000
Notice that the command is not executed in parallel.
When --with arugemnt is provided, the command will be only executed with the specified perl installations. The following command install Moose module into perl-5.12, regardless the current perl:
--with
perlbrew exec --with perl-5.12 cpanm Moose
Multiple installation names can be provided:
perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo
The are splited by either spaces or commas. When spaces are used, it is required to quote the whole specifiacion as one argument, but then commas can be used in the installation names:
perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo
As demonstrated above, "perl-" prefix can be omitted, and lib names can be specified too. Lib names can appear without a perl installation name, in such cases it is assumed to be "current perl".
At the moment, any specified names that fails to be resolved as a real installation names are silently ignored in the output. Also, the command exit status are not populated back.
Usage: perlbrew env <name>
Low-level command. Invoke this command to see the list of environment variables that are set by perlbrew itself for shell integration.
perlbrew
The output is something similar to this (if your shell is bash/zsh):
export PERLBREW_ROOT=/Users/gugod/perl5/perlbrew export PERLBREW_VERSION=0.31 export PERLBREW_PATH=/Users/gugod/perl5/perlbrew/bin:/Users/gugod/perl5/perlbrew/perls/current/bin export PERLBREW_PERL=perl-5.14.1
tcsh / csh users shall seens lines of 'setenv' statements instead of `export`.
Usage: perlbrew symlink-executables <name>
Low-level command. This command is used to create the perl executable symbolic link to, say, perl5.13.6. This is only required for development version of perls.
perl
perl5.13.6
You don't need to do this unless you have been using old perlbrew to install perls, and you find youself confused because the perl that you just installed appears to be missing after invoking `use` or `switch`. perbrew changes its installation layout since version 0.11, which generades symlinks to executables in a better way.
If you just upgraded perlbrew (from 0.11 or earlier versions) and perlbrew switch failed to work after you switch to a development release of perl, say, perl-5.13.6, run this command:
perlbrew symlink-executables perl-5.13.6
This essentially creates this symlink:
${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl -> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6
Newly installed perls, whether they are development versions or not, does not need manually treatment with this command.
Usage: perlbrew install-cpanm
Install the cpanm standalone executable in $PERLBREW_ROOT/bin.
cpanm
$PERLBREW_ROOT/bin
For more rationale about the existence of this command, read <http://www.perlbrew.pl/Perlbrew-and-Friends.html>
Usage: perlbrew install-patchperl
Install the patchperl standalone executable in $PERLBREW_ROOT/bin. This is automaticall invoked if your perlbrew installation is done with the installer, but not with cpan.
patchperl
Usage: perlbrew self-upgrade
This command upgrades Perlbrew to its latest version.
Usage: perlbrew self-install
NOTICE: You should not need to run this command in your daily routine.
This command install perlbrew itself to $PERLBREW_ROOT/bin. It is intended used by the perlbrew installer. However, you may manually do the following to re-install only the perlbrew executable:
curl -kL http://get.perlbrew.pl -o perlbrew perl ./perlbrew self-install
It is slightly different from running the perlbrew installer because patchperl is not installed in this case.
Usage: perlbrew version
Show the version of perlbrew.
Usage:
perlbrew lib list perlbrew lib create <lib-name> perlbrew lib delete <lib-name>
The `lib` command is used to manipulate local::lib roots inside perl installations. Effectively it is similar to `perl -Mlocal::lib=/path/to/lib-name`, but a little bit more than just that.
A lib name can be a short name, containing alphanumeric, like 'awesome', or a full name, prefixed by a perl installation name and a '@' sign, for example, 'perl-5.14.2@awesome'.
Here are some a brief examples to invoke the `lib` command:
# Create libs by name perlbrew lib create nobita perlbrew lib create perl-5.12.3@shizuka perlbrew list # See the list of use/switch targets. # Activate a lib in current shell. perlbrew use perl-5.12.3@nobita perlbrew use perl-5.14.2@nobita # Activate a lib as default. perlbrew switch perl-5.14.2@nobita # Delete the lib perlbrew lib delete nobita perlbrew lib delete perl-5.12.3@shizuka
Short lib names are local to current perl. A lib name 'nobita' can refer to 'perl-5.12.3@nobita' or 'perl-5.14.2@nobita', depending on your current perl.
When useing or switching to a lib, always provide the long name. A simple rule: the argument to use or switch command should appear in the output of perlbrew list.
perlbrew list
Usage: perlbrew upgrade-perl
Minor Perl releases (ex. 5.x.*) are binary compatible with one another, so this command offers you the ability to upgrade older perlbrew environments in place.
It upgrades the currently activated perl to its latest released brothers. If you have a shell with 5.14.0 activated, it upgrades it to 5.14.2.
perlbrew download perl-5.14.2 perlbrew download perl-5.16.1 perlbrew download perl-5.17.3
Download the specified version of perl distribution tarball under $PERLBREW_ROOT/dists/ directory.
$PERLBREW_ROOT/dists/
Usage: perlbrew install-ack
Install the standalone version of ack program under $PERLBREW_ROOT/bin.
ack
List all installed cpan modules for the current perl.
This command can be used in conjunction with `perlbrew exec` to migrate your module installation to different perl. The following command re-installs all modules under perl-5.16.0:
perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
If you are upgrading perlbrew from 0.16 or ealier versions to a recent one (0.40-ish), you should do these steps to adjust your perl installations afterwards (you might need to change the value of PERLBREW_ROOT):
export PERLBREW_ROOT=${HOME}/perl5/perlbrew rm -f $PERLBREW_ROOT/perls/current rm -f `find $PERLBREW_ROOT/perls/bin -type l` perlbrew symlink-executables perlbrew init
Following the instructions on screen to tweak your shell a bit. Then it should be good.
App::perlbrew, App::cpanminus, Devel::PatchPerl
To install App::perlbrew, copy and paste the appropriate command in to your terminal.
cpanm App::perlbrew
CPAN shell
perl -MCPAN -e shell install App::perlbrew
For more information on module installation, please visit the detailed CPAN module installation guide.