1PERLBREW(1) User Contributed Perl Documentation PERLBREW(1)
2
6 perlbrew - Perl environment manager.
7
9 perlbrew command syntax:
10 perlbrew <command> [options] [arguments]
12 Commands:
14 init Initialize perlbrew environment.
16 info Show useful information about the perlbrew installation
17 install Install perl
19 uninstall Uninstall the given installation
20 available List perls available to install
21 lib Manage local::lib directories.
22 alias Give perl installations a new name
23 upgrade-perl Upgrade the current perl
24 list List perl installations
26 use Use the specified perl in current shell
27 off Turn off perlbrew in current shell
28 switch Permanently use the specified perl as default
29 switch-off Permanently turn off perlbrew (revert to system perl)
30 exec exec programs with specified perl environments.
31 clone-modules re-installs all CPAN modules from one installation to another
32 self-install Install perlbrew itself under PERLBREW_ROOT/bin
34 self-upgrade Upgrade perlbrew itself.
35 install-patchperl Install patchperl
37 install-cpanm Install cpanm, a friendly companion.
38 install-multiple Install multiple versions and flavors of perl
39 download Download the specified perl distribution tarball.
41 clean Purge tarballs and build directories
42 version Display version
43 help Read more detailed instructions
44 Generic command options:
46 -q --quiet Be quiet on informative output message.
48 -v --verbose Tell me more about it.
49 See `perlbrew help` for the full documentation of perlbrew, or
51 See `perlbrew help <command>` for detail description of the command.
53
55 PERLBREW_ROOT
56 By default, perlbrew builds and installs perls into
57 "$ENV{HOME}/perl5/perlbrew" directory. To use a different
58 directory, set this environment variable in your "bashrc" to the
59 directory in your shell RC before sourcing perlbrew's RC.
60 It is possible to share one perlbrew root with multiple user
62 account on the same machine. Therefore people do not have to
63 install the same version of perl over an over. Let's say
64 "/opt/perl5" is the directory we want to share. All users should be
65 able append this snippet to their bashrc to make it effective:
66 export PERLBREW_ROOT=/opt/perl5
68 source ${PERLBREW_ROOT}/etc/bashrc
69 After doing so, everyone's PATH should include "/opt/perl5/bin" and
71 "/opt/perl5/perls/${PERLBREW_PERL}/bin". Each user can invoke
72 "perlbrew switch" and "perlbrew use" to independently switch to
73 different perl environment of their choice. However, only the user
74 with write permission to $PERLBREW_ROOT may install CPAN modules.
75 This is both good and bad depending on the working convention of
76 your team.
77 If you wish to install CPAN modules only for yourself, you should
79 use the "lib" command to construct a personal local::lib
80 environment. local::lib environments are personal, and are not
81 shared between different users. For more detail, read "perlbrew
82 help lib" and the documentation of local::lib.
83 If you want even a cooler module isolation and wish to install CPAN
85 modules used for just one project, you should use carton for this
86 purpose.
87 It is also possible to set this variable before installing perlbrew
89 to make perlbrew install itself under the given PERLBREW_ROOT:
90 export PERLBREW_ROOT=/opt/perl5
92 curl -L http://install.perlbrew.pl | bash
93 After doing this, the perlbrew executable is installed as
95 "/opt/perl5/bin/perlbrew"
96 PERLBREW_HOME
98 By default, perlbrew stores per-user setting to
99 "$ENV{HOME}/.perlbrew" directory. To use a different directory, set
100 this environment variable in your shell RC before sourcing
101 perlbrew's RC.
102 In some cases, say, your home directory is on NFS and shared across
104 multiple machines, you may wish to have several different perlbrew
105 setting per-machine. To do so, you can use the "PERLBREW_HOME"
106 environment variable to tell perlbrew where to look for the
107 initialization file. Here's a brief bash snippet for the given
108 scenario.
109 if [ "$(hostname)" == "machine-a" ]; then
111 export PERLBREW_HOME=~/.perlbrew-a
112 elif [ "$(hostname)" == "machine-b" ]; then
113 export PERLBREW_HOME=~/.perlbrew-b
114 fi
115 source ~/perl5/perlbrew/etc/bashrc
117 PERLBREW_CONFIGURE_FLAGS
119 This environment variable specify the list of command like flags to
120 pass through to 'sh Configure'. By default it is '-de'.
121 PERLBREW_CPAN_MIRROR
123 The CPAN mirror url of your choice. The default value is
124 "http://www.cpan.org"
125
127 Usage: perlbrew init
128 The "init" command should be manually invoked whenever you (the
130 perlbrew user) upgrade or reinstall perlbrew.
131 If the upgrade is done with "self-upgrade" command, or by running the
133 one-line installer manually, this command is invoked automatically.
134
136 info [module]
137 Usage: perlbrew info [ <module> ]
138 Display useful information about the perlbrew installation.
140 If a module is given the version and location of the module is
142 displayed.
143
145 Usage:
146 perlbrew install [options] <perl-release>
148 perlbrew install [options] /path/to/perl-5.14.0.tar.gz
149 perlbrew install [options] /path/to/perl/git/checkout/dir
150 perlbrew install [options] http://example.com/mirror/perl-5.12.3.tar.gz
151 Build and install the wanted perl. The last argument can be a short
153 string designating a specific version which can be known from the
154 output of "perlbrew available", a path to a pre-downloaded tarball, a
155 path to a git-checkout of perl5 repo, or a URL to a tarball.
156 The format of <perl-release> looks like:
158 perl-<version>
160 perl-stable
161 perl-blead
162 <version>
163 stable
164 blead
165 cperl-<version>
166 Version numbers usually look like "5.x.xx", or "perl-5.xx.x-RCx" for
168 release candidates.
169 Version "stable" is a special token that means whatever the latest
171 stable version is at the moment.
172 Version "blead" is also a special token that means whatever the latest
174 version in the repository, which is downloaded from this specific URL
175 regardless of mirror settings:
176 https://github.com/Perl/perl5/archive/blead.tar.gz
178 The specified perl is downloaded from the official CPAN website or from
180 the mirror site configured before.
181 Version number alone without the "perl-" prefix means the official
183 release provided by perl5 porters.
184 The prefix "cperl" is a special release provided not by perl5 porters,
186 but from the community. The cperl distributions are downloaded from:
187 https://github.com/perl11/cperl/releases
189 See http://perl11.org/cperl/ for more information about cperl
191 distribution.
192 Options for "install" command:
194 -f --force Force installation
196 -j $n Parallel building and testing. ex. C<perlbrew install -j 5 perl-5.14.2>
197 -n --notest Skip testing
198 --switch Automatically switch to this Perl once successfully
200 installed, as if with `perlbrew switch <version>`
201 --as Install the given version of perl by a name.
203 ex. C<perlbrew install perl-5.6.2 --as legacy-perl>
204 --noman Skip installation of manpages
206 --thread Build perl with usethreads enabled
208 --multi Build perl with usemultiplicity enabled
209 --64int Build perl with use64bitint enabled
210 --64all Build perl with use64bitall enabled
211 --ld Build perl with uselongdouble enabled
212 --debug Build perl with DEBUGGING enabled
213 --clang Build perl using the clang compiler
214 --no-patchperl
215 Skip calling patchperl
216 -D,-U,-A Switches passed to perl Configure script.
218 ex. C<perlbrew install perl-5.10.1 -D usemymalloc -U versiononly>
219 --destdir $path
221 Install perl as per 'make install DESTDIR=$path'
222 --sitecustomize $filename
224 Specify a file to be installed as sitecustomize.pl
225 --mirror $URL
227 Specify a CPAN-mirror URL. The default value of this is "https://www.cpan.org"
228 By default, all installations are configured after their name like
230 this:
231 sh Configure -de -Dprefix=$PERLBREW_ROOT/perls/<name>
233
235 Usage: perlbrew install-multiple [options] <perl-version-1>
236 <perl-version-2> ...
237 Build and install the given versions of perl.
239 "install-multiple" accepts the same set of options as the command
241 "install" plus the following ones:
242 --both $flavor Where $flavor is one of C<thread>, C<multi>, C<ld>,
244 C<64int>, C<64all>, C<debug> and C<clang>.
245 For every given perl version, install two
247 flavors, one with the flag C<--$flavor> set
248 and the other with out. C<--both> can be
249 passed multiple times with different values
250 and in that case, all the possible
251 combinations are generated.
252 --common-variations equivalent to C<--both thread --both ld --both 64int>
254 --all-variations generates all the possible flavor combinations
256 --append $string Appends the given string to the generated names
258 For instance:
260 perlbrew install-multiple 5.18.0 blead --both thread --both debug
262 Installs the following perls:
264 perl-blead
266 perl-blead-debug
267 perl-blead-thread-multi
268 perl-blead-thread-multi-debug
269 perl-5.18.0
270 perl-5.18.0-debug
271 perl-5.18.0-thread-multi
272 perl-5.18.0-thread-multi-debug
273 (note that the "multi" flavor is selected automatically because
275 "thread" requires it)
276 Another example using custom compilation flags:
278 perlbrew install-multiple 5.18.0 --both thread -Doptimize='-O3' --append='-O3'
280
282 Usage: perlbrew uninstall <name>
283 Uninstalls the given perl installation. The name is the installation
285 name as in the output of `perlbrew list`. This effectively deletes the
286 specified perl installation, and all libs associated with it.
287
289 Usage: perlbrew use [perl-<version> | <version> | <name>]
290 Use the given version perl in current shell. This will not effect newly
292 opened shells.
293 Without a parameter, shows the version of perl currently in use.
295
297 Usage: perlbrew switch [ <name> ]
298 Switch to the given version, and makes it the default for this and all
300 future terminal sessions.
301 Without a parameter, shows the version of perl currently selected.
303
305 Usage: perlbrew list
306 List all perl installations inside perlbrew root specified by
308 $PERLBREW_ROOT environment variable. By default, the value is
309 "~/perl5/perlbrew".
310 If there are libs associated to some perl installations, they will be
312 included as part of the name. The output items in this list can be the
313 argument in various other commands.
314
316 Usage: perlbrew available [--all]
317 List the recently available versions of perl on CPAN.
319 The list is retrieved from the web page
321 <http://www.cpan.org/src/README.html>, and is not the list of *all*
322 perl versions ever released in the past.
323 To get a list of all perls ever released, use the "--all" option.
325 NOTICE: This command might be gone in the future and become an option
327 of 'list' command.
328
330 Usage: perlbrew off
331 Temporarily disable perlbrew in the current shell. Effectively re-
333 enables the default system Perl, whatever that is.
334 This command works only if you add the statement of `source
336 $PERLBREW_ROOT/etc/bashrc` in your shell initialization (bashrc /
337 zshrc).
338
340 Usage: perlbrew switch-off
341 Permananently disable perlbrew. Use "switch" command to re-enable it.
343 Invoke "use" command to enable it only in the current shell.
344 Re-enables the default system Perl, whatever that is.
346
348 Usage: perlbrew alias [-f] create <name> <alias>
349 Create an alias for the installation named <name>.
351 Usage: perlbrew alias [-f] rename <old_alias> <new_alias>
353 Rename the alias to a new name.
355 Usage: perlbrew alias delete <alias>
357 Delete the given alias.
359
361 Usage: perlbrew exec [options] <command> <args...>
362 Options for "exec" command:
364 --with perl-version,... - only use these versions
366 --min n.nnnnn - minimum perl version
367 (format is the same as in 'use 5.012')
368 --max n.nnnnn - maximum perl version
369 --halt-on-error - stop on first nonzero exit status
370 Execute command for each perl installations, one by one.
372 For example, run a Hello program:
374 perlbrew exec perl -e 'print "Hello from $]\n"'
376 The output looks like this:
378 perl-5.12.2
380 ==========
381 Hello word from perl-5.012002
382 perl-5.13.10
384 ==========
385 Hello word from perl-5.013010
386 perl-5.14.0
388 ==========
389 Hello word from perl-5.014000
390 Notice that the command is not executed in parallel.
392 When "--with" argument is provided, the command will be only executed
394 with the specified perl installations. The following command install
395 Moose module into perl-5.12, regardless the current perl:
396 perlbrew exec --with perl-5.12 cpanm Moose
398 Multiple installation names can be provided:
400 perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo
402 They are split by either spaces or commas. When spaces are used, it is
404 required to quote the whole specification as one argument, but then
405 commas can be used in the installation names:
406 perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo
408 As demonstrated above, "perl-" prefix can be omitted, and lib names can
410 be specified too. Lib names can appear without a perl installation
411 name, in such cases it is assumed to be "current perl".
412 At the moment, any specified names that fails to be resolved as a real
414 installation names are silently ignored in the output. Also, the
415 command exit status are not populated back.
416
418 Usage: perlbrew env [ <name> ]
419 Low-level command. Invoke this command to see the list of environment
421 variables that are set by "perlbrew" itself for shell integration.
422 The output is something similar to this (if your shell is bash/zsh):
424 export PERLBREW_ROOT=/Users/gugod/perl5/perlbrew
426 export PERLBREW_VERSION=0.31
427 export PERLBREW_PATH=/Users/gugod/perl5/perlbrew/bin:/Users/gugod/perl5/perlbrew/perls/current/bin
428 export PERLBREW_PERL=perl-5.14.1
429 tcsh / csh users should see 'setenv' statements instead of `export`.
431
433 Usage: perlbrew symlink-executables [ <name> ]
434 Low-level command. This command is used to create the "perl" executable
436 symbolic link to, say, "perl5.13.6". This is only required for
437 development version of perls.
438 You don't need to do this unless you have been using old perlbrew to
440 install perls, and you find yourself confused because the perl that you
441 just installed appears to be missing after invoking `use` or `switch`.
442 perlbrew changes its installation layout since version 0.11, which
443 generates symlinks to executables in a better way.
444 If you just upgraded perlbrew (from 0.11 or earlier versions) and
446 "perlbrew switch" failed to work after you switch to a development
447 release of perl, say, perl-5.13.6, run this command:
448 perlbrew symlink-executables perl-5.13.6
450 This essentially creates this symlink:
452 ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl
454 -> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6
455 Newly installed perls, whether they are development versions or not,
457 does not need manually treatment with this command.
458
460 Usage: perlbrew install-cpanm
461 Install the "cpanm" standalone executable in "$PERLBREW_ROOT/bin".
463 For more rationale about the existence of this command, read
465 <http://perlbrew.pl/Perlbrew-and-Friends.html>
466
468 Usage: perlbrew install-patchperl
469 Install the "patchperl" standalone executable in "$PERLBREW_ROOT/bin".
471 This is automatically invoked if your perlbrew installation is done
472 with the installer, but not with cpan.
473 For more rationale about the existence of this command, read
475 <http://perlbrew.pl/Perlbrew-and-Friends.html>
476
478 Usage: perlbrew self-upgrade
479 This command upgrades Perlbrew to its latest version.
481
483 Usage: perlbrew self-install
484 NOTICE: You should not need to run this command in your daily routine.
486 This command installs perlbrew itself to "$PERLBREW_ROOT/bin". It is
488 intended to be used by the perlbrew installer. However, you could
489 manually do the following to re-install only the "perlbrew" executable:
490 curl https://raw.githubusercontent.com/gugod/App-perlbrew/master/perlbrew -o perlbrew
492 perl ./perlbrew self-install
493 It is slightly different from running the perlbrew installer because
495 "patchperl" is not installed in this case.
496
498 Usage: perlbrew clean
499 Removes all previously downloaded Perl tarballs and build directories.
501
503 Usage: perlbrew version
504 Show the version of perlbrew.
506
508 Usage: perlbrew lib <action> <lib-name>
509 perlbrew lib list
511 perlbrew lib create <lib-name>
512 perlbrew lib delete <lib-name>
513 The `lib` command is used to manipulate local::lib roots inside perl
515 installations. Effectively it is similar to `perl
516 -Mlocal::lib=/path/to/lib-name`, but a little bit more than just that.
517 A lib name can be a short name, containing alphanumeric, like
519 'awesome', or a full name, prefixed by a perl installation name and a
520 '@' sign, for example, 'perl-5.14.2@awesome'.
521 Here are some a brief examples to invoke the `lib` command:
523 # Create lib perl-5.12.3@shizuka
525 perlbrew lib create perl-5.12.3@shizuka
526 # Create lib perl-5.14.2@nobita and perl-5.14.2@shizuka
528 perlbrew use perl-5.14.2
529 perlbrew lib create nobita
530 perlbrew lib create shizuka
531 # See the list of use/switch targets
533 perlbrew list
534 # Activate a lib in current shell
536 perlbrew use perl-5.12.3@shizuka
537 perlbrew use perl-5.14.2@nobita
538 perlbrew use perl-5.14.2@shizuka
539 # Activate a lib as default
541 perlbrew switch perl-5.12.3@shizuka
542 perlbrew switch perl-5.14.2@nobita
543 perlbrew switch perl-5.14.2@shizuka
544 # Delete lib perl-5.14.2@nobita and perl-5.14.2@shizuka
546 perlbrew use perl-5.14.2
547 perlbrew lib delete nobita
548 perlbrew lib delete shizuka
549 # Delete lib perl-5.12.3@shizuka
551 perlbrew lib delete perl-5.12.3@shizuka
552 Short lib names are local to current perl. A lib name 'nobita' can
554 refer to 'perl-5.12.3@nobita' or 'perl-5.14.2@nobita', whichever is
555 activated in the current shell.
556 When "use"ing or "switch"ing to a lib, always provide the long name. A
558 simple rule: the argument to "use" or "switch" command should appear in
559 the output of "perlbrew list".
560
562 Usage: perlbrew upgrade-perl
563 Running this command upgrades the currently activated perl to its
565 latest released brothers. If you have a shell with 5.32.0 activated, it
566 upgrades it to 5.32.1.
567 Minor Perl releases (ex. 5.x.*) are binary compatible with one another,
569 so this command offers you the ability to upgrade older perlbrew
570 environments in place.
571
573 Usage:
574 perlbrew download <perl-release>
575 Examples:
577 perlbrew download perl-5.14.2
578 perlbrew download perl-5.16.1
579 perlbrew download perl-5.17.3
580 Download the specified version of perl distribution tarball under the
582 directory "$PERLBREW_ROOT/dists/".
583 The argument "perl-release" should be one of the items from "perlbrew
585 available" command.
586
588 Usage:
589 perlbrew list-modules
590 List all installed cpan modules for the current perl.
592 This command can be used in conjunction with `perlbrew exec` to migrate
594 your module installation to different perl. The following command re-
595 installs all modules under perl-5.16.0:
596 perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
598 Note that this installs the latest versions of the Perl modules on the
600 new perl, which are not necessarily the same module versions you had
601 installed previously.
602
604 Usage:
605 perlbrew clone-modules [options] <destination>
607 perlbrew clone-modules [options] <source> <destination>
608 Options:
610 --notest Skip all module tests
612 This command re-installs all CPAN modules found from one installation
614 to another. For example, this list all modules under '5.26.1' and re-
615 install them under '5.27.7':
616 perlbrew clone-modules 5.26.1 5.27.7
618 The argument "source" is optional and is default to the current
620 activated one. However if none is activated (perlbrew is switched off),
621 it it an error.
622 Noted that this does not guarantee that the versions of modules stays
624 the same in the destination.
625
627 App::perlbrew, App::cpanminus, Devel::PatchPerl
628perl v5.34.0 2021-11-24 PERLBREW(1)