PERLBREW(1p)						User Contributed Perl Documentation					      PERLBREW(1p)

NAME

       perlbrew - Perl environment manager.

SYNOPSIS

       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

	   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)

	   self-upgrade       Upgrade perlbrew itself.
	   install-cpanm      Install cpanm, a friendly companion.
	   install-patchperl  Install patchperl

	   mirror	  Pick a preferred mirror site
	   version	  Display version
	   help 	  Read more detailed instructions

       Options for "install" command:

	   -f --force	  Force installation
	   -j $n	  Parallel buildng and testing. ex. C<perlbrew install -j 5 perl-5.14.2>
	   -n --notest	  Skip testing

	      --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

       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.

INSTALLATION

       It is the simpleist to use the perlbrew installer, just paste this statement to your terminal:

	   curl -kL http://install.perlbrew.pl | bash

       Or this one, if you have "fetch" (default on FreeBSD):

	   fetch -o- http://install.perlbrew.pl | sh

       After that, "perlbrew" installs itself to "~/perl5/perlbrew/bin", and you should follow the instruction on screen to modify your shell rc
       file to put it in your PATH.

       The installed perlbrew command is a standalone executable that can be run with system perl. The minimun system perl version requirement is
       5.8.0, which should be good enough for most of the OSes these days.

       A packed version of "patchperl" to "~/perl5/perlbrew/bin", which is required to build old perls.

       The directory "~/perl5/perlbrew" will contain all install perl executables, libraries, documentations, lib, site_libs. In the
       documentation, that directory is referred as "perlbrew root". If you need to set it to somewhere else because, say, your HOME has limited
       quota, you can do that by setting "PERLBREW_ROOT" environment variable before running the installer:

	   export PERLBREW_ROOT=/opt/perl5
	   curl -kL http://install.perlbrew.pl | bash

       You may also install perlbrew from CPAN:

	   cpan App::perlbrew

       In this case, the perlbrew command is installed as "/usr/bin/perlbrew" or "/usr/local/bin/perlbrew" or others, depending on the location of
       your system perl installation.

       Please make sure not to run this with one of the perls brewed with perlbrew. It's the best to turn perlbrew off before you run that, if
       you're upgrading.

	   perlbrew off
	   cpan App::perlbrew

       You should always use system cpan (like /usr/bin/cpan) to install "App::perlbrew" because it will be installed under a system PATH like
       "/usr/bin", which is not affected by perlbrew "switch" or "use" command.

       The "self-upgrade" command will not upgrade the perlbrew installed by cpan command, but it is also easy to upgrade perlbrew by running
       `cpan App::perlbrew` again.

CONFIGURATION

       PERLBREW_ROOT
	   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.

	   It is possible to share one perlbrew root with multilpe 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:

	       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.

	   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.

	   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"

       PERLBREW_HOME
	   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.

	   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.

	       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

COMMAND
: INIT
       The "init" command should be manually invoked whenever you (the perlbrew user) upgrade perlbrew.

       However, if the upgrade is done with "self-upgrade" command, or by running the one-line installer manually, this command is invoked
       automatically.

COMMAND
: INSTALL
       install [ perl-<version> | <version> ]
	   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.

       install [ perl-blead | blead ]
	   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

       install /path/to/perl/git/checkout/dir
	   Build and install from the given git checkout dir.

       install /path/to/perl-5.14.0.tar.gz
	   Build and install from the given archive file.

       install http://example.com/mirror/perl-5.12.3.tar.gz
	   Build and install from the given URL. Supported URL schemes are "http://", "https://", "ftp://" and "file://".

COMMAND
: UNINSTALL
       Usage: perlbrew uninstall <name>

       Uninstalls the given perl installation.

COMMAND
: USE
       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.

COMMAND
: SWITCH
       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.

COMMAND
: LIST
       Usage: perlbrew list

       List the installed versions of perl.

COMMAND
: AVAILABLE
       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 releasesed
       in the past.

       NOTICE: This command might be gone in the future and becomes an option of 'list' command.

COMMAND
: OFF
       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).

COMMAND
: SWITCH-OFF
       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.

       Re-enables the default system Perl, whatever that is.

COMMAND
: ALIAS
       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.

COMMAND
: MIRROR
       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.

COMMAND
: EXEC
       Usage: perlbrew exec <command> <args...>

       Execute command for all perls, one by one.

       For example, run a Hello program:

	   perlbrew exec perl -e 'print "Hello from $]
"'

       The output depends on your perl installations, and looks like this:

	   perl-5.12.2
	   ==========
	   Hello word from perl-5.012002

	   perl-5.12.3
	   ==========
	   Hello word from perl-5.012003

	   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.

COMMAND
: ENV
       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.

       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`.

COMMAND
: SYMLINK-EXECUTABLES
       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.

       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.

COMMAND
: INSTALL-CPANM
       Usage: perlbrew install-cpanm

       Install the "cpanm" standalone executable in "$PERLBREW_ROOT/bin".

       For more rationale about the existence of this command, read <http://www.perlbrew.pl/Perlbrew-and-Friends.html>

COMMAND
: INSTALL-PATCHPERL
       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.

       For more rationale about the existence of this command, read <http://www.perlbrew.pl/Perlbrew-and-Friends.html>

COMMAND
: SELF-UPGRADE
       Usage: perlbrew self-upgrade

       This command upgrades Perlbrew to its latest version.

COMMAND
: SELF-INSTALL
       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 install

       It is slightly different from running the perlbrew installer because "patchperl" is not installed in this case.

COMMAND
: VERSION
       Usage: perlbrew version

       Show the version of perlbrew.

COMMAND
: LIB
       Usage:

	   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 "use"ing or "switch"ing to a lib, always provide the long name. A simple rule: the argument to "use" or "siwtch" command should appear
       in the output of "perlbrew list".

UPGRADE NOTES

       If you plan to upgrade "perlbrew" from version 0.16 or order to a recent version, you should do these steps to adjust your perl
       installations:

	   1. remove $PERLBREW_ROOT/perls/current if it exists
	   2. remove symlinks under $PERLBREW_ROOT/perls/bin
	   3. run C<perlbrew symlink-executables>
	   4. run C<perlbrew init>
	   5. run C<perlbrew switch $something> to set your default perl.

       Or simply run these statements to do so (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
	   perlbrew switch perl-5.14.2 # or other ones.

       Finally, you should add this line to the end of your "~/.bash_profile" or "~/.zshenv" file:

	   source "$HOME/perl5/perlbrew/etc/bashrc"

       Or if you have differnt PERLBREW_ROOT at, say, "/opt/perl5", add:

	   export PERLBREW_ROOT=/opt/perl5
	   source "$PERLBREW_ROOT/etc/bashrc"

       After doing that, you will be good to go.

SEE ALSO

       App::perlbrew, App::cpanminus, Devel::PatchPerl

perl v5.14.2							    2012-05-27							      PERLBREW(1p)