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 Execute programs with specified perl environments.
31 list-modules List installed CPAN modules for the current Perl version in use
33 clone-modules Re-installs all CPAN modules from one installation to another
34 self-install Install perlbrew itself under PERLBREW_ROOT/bin
36 self-upgrade Upgrade perlbrew itself.
37 install-patchperl Install patchperl
39 install-cpanm Install cpanm, a friendly companion.
40 install-cpm Install cpm, a faster but still friendly companion.
41 install-multiple Install multiple versions and flavors of perl
42 download Download the specified perl distribution tarball.
44 clean Purge tarballs and build directories
45 version Display version
46 help Read more detailed instructions
47 Generic command options:
49 -q --quiet Be quiet on informative output message.
51 -v --verbose Tell me more about it.
52 See `perlbrew help` for the full documentation of perlbrew, or
54 See `perlbrew help <command>` for detail description of the command.
56
58 PERLBREW_ROOT
59 By default, perlbrew builds and installs perls into
60 "$ENV{HOME}/perl5/perlbrew" directory. To use a different
61 directory, set this environment variable in your "bashrc" to the
62 directory in your shell RC before sourcing perlbrew's RC.
63 It is possible to share one perlbrew root with multiple user
65 account on the same machine. Therefore people do not have to
66 install the same version of perl over an over. Let's say
67 "/opt/perl5" is the directory we want to share. All users should be
68 able append this snippet to their bashrc to make it effective:
69 export PERLBREW_ROOT=/opt/perl5
71 source ${PERLBREW_ROOT}/etc/bashrc
72 After doing so, everyone's PATH should include "/opt/perl5/bin" and
74 "/opt/perl5/perls/${PERLBREW_PERL}/bin". Each user can invoke
75 "perlbrew switch" and "perlbrew use" to independently switch to
76 different perl environment of their choice. However, only the user
77 with write permission to $PERLBREW_ROOT may install CPAN modules.
78 This is both good and bad depending on the working convention of
79 your team.
80 If you wish to install CPAN modules only for yourself, you should
82 use the "lib" command to construct a personal local::lib
83 environment. local::lib environments are personal, and are not
84 shared between different users. For more detail, read "perlbrew
85 help lib" and the documentation of local::lib.
86 If you want even a cooler module isolation and wish to install CPAN
88 modules used for just one project, you should use carton for this
89 purpose.
90 It is also possible to set this variable before installing perlbrew
92 to make perlbrew install itself under the given PERLBREW_ROOT:
93 export PERLBREW_ROOT=/opt/perl5
95 curl -L https://install.perlbrew.pl | bash
96 After doing this, the perlbrew executable is installed as
98 "/opt/perl5/bin/perlbrew"
99 PERLBREW_HOME
101 By default, perlbrew stores per-user setting to
102 "$ENV{HOME}/.perlbrew" directory. To use a different directory, set
103 this environment variable in your shell RC before sourcing
104 perlbrew's RC.
105 In some cases, say, your home directory is on NFS and shared across
107 multiple machines, you may wish to have several different perlbrew
108 setting per-machine. To do so, you can use the "PERLBREW_HOME"
109 environment variable to tell perlbrew where to look for the
110 initialization file. Here's a brief bash snippet for the given
111 scenario.
112 if [ "$(hostname)" == "machine-a" ]; then
114 export PERLBREW_HOME=~/.perlbrew-a
115 elif [ "$(hostname)" == "machine-b" ]; then
116 export PERLBREW_HOME=~/.perlbrew-b
117 fi
118 source ~/perl5/perlbrew/etc/bashrc
120 PERLBREW_CONFIGURE_FLAGS
122 This environment variable specify the list of command like flags to
123 pass through to 'sh Configure'. By default it is '-de'.
124 PERLBREW_CPAN_MIRROR
126 The CPAN mirror url of your choice. By default,
127 "https://cpan.metacpan.org" is used.
128
130 Usage: perlbrew init
131 The "init" command should be manually invoked whenever you (the
133 perlbrew user) upgrade or reinstall perlbrew.
134 If the upgrade is done with "self-upgrade" command, or by running the
136 one-line installer manually, this command is invoked automatically.
137
139 info [module]
140 Usage: perlbrew info [ <module> ]
141 Display useful information about the perlbrew installation.
143 If a module is given the version and location of the module is
145 displayed.
146
148 Usage:
149 perlbrew install [options] <perl-release>
151 perlbrew install [options] /path/to/perl-5.14.0.tar.gz
152 perlbrew install [options] /path/to/perl/git/checkout/dir
153 perlbrew install [options] https://example.com/mirror/perl-5.12.3.tar.gz
154 Build and install the wanted perl. The last argument can be a short
156 string designating a specific version which can be known from the
157 output of "perlbrew available", a path to a pre-downloaded tarball, a
158 path to a git-checkout of perl5 repo, or a URL to a tarball.
159 The format of <perl-release> looks like:
161 perl-<version>
163 perl-stable
164 perl-blead
165 <version>
166 stable
167 blead
168 cperl-<version>
169 Version numbers usually look like "5.x.xx", or "perl-5.xx.x-RCx" for
171 release candidates.
172 Version "stable" is a special token that means whatever the latest
174 stable version is at the moment.
175 Version "blead" is also a special token that means whatever the latest
177 version in the repository, which is downloaded from this specific URL
178 regardless of mirror settings:
179 https://github.com/Perl/perl5/archive/blead.tar.gz
181 The specified perl is downloaded from the official CPAN website or from
183 the mirror site configured before.
184 Version number alone without the "perl-" prefix means the official
186 release provided by perl5 porters.
187 The prefix "cperl" is a special release provided not by perl5 porters,
189 but from the community. The cperl distributions are downloaded from:
190 https://github.com/perl11/cperl/releases
192 See https://perl11.org/cperl/ for more information about cperl
194 distribution.
195 Options for "install" command:
197 -f --force Force installation
199 -j $n Parallel building and testing. ex. C<perlbrew install -j 5 perl-5.14.2>
200 -n --notest Skip testing
201 --switch Automatically switch to this Perl once successfully
203 installed, as if with `perlbrew switch <version>`
204 --as Install the given version of perl by a name.
206 ex. C<perlbrew install perl-5.6.2 --as legacy-perl>
207 --noman Skip installation of manpages
209 --thread Build perl with usethreads enabled
211 --multi Build perl with usemultiplicity enabled
212 --64int Build perl with use64bitint enabled
213 --64all Build perl with use64bitall enabled
214 --ld Build perl with uselongdouble enabled
215 --debug Build perl with DEBUGGING enabled
216 --clang Build perl using the clang compiler
217 --no-patchperl
218 Skip calling patchperl
219 -D,-U,-A Switches passed to perl Configure script.
221 ex. C<perlbrew install perl-5.10.1 -D usemymalloc -U versiononly>
222 --destdir $path
224 Install perl as per 'make install DESTDIR=$path'
225 --sitecustomize $filename
227 Specify a file to be installed as sitecustomize.pl
228 --mirror $URL
230 Specify a CPAN-mirror URL. The default value of this is "https://www.cpan.org"
231 By default, all installations are configured after their name like
233 this:
234 sh Configure -de -Dprefix=$PERLBREW_ROOT/perls/<name>
236
238 Usage: perlbrew install-multiple [options] <perl-version-1>
239 <perl-version-2> ...
240 Build and install the given versions of perl.
242 "install-multiple" accepts the same set of options as the command
244 "install" plus the following ones:
245 --both $flavor Where $flavor is one of C<thread>, C<multi>, C<ld>,
247 C<64int>, C<64all>, C<debug> and C<clang>.
248 For every given perl version, install two
250 flavors, one with the flag C<--$flavor> set
251 and the other with out. C<--both> can be
252 passed multiple times with different values
253 and in that case, all the possible
254 combinations are generated.
255 --common-variations equivalent to C<--both thread --both ld --both 64int>
257 --all-variations generates all the possible flavor combinations
259 --append $string Appends the given string to the generated names
261 For instance:
263 perlbrew install-multiple 5.18.0 blead --both thread --both debug
265 Installs the following perls:
267 perl-blead
269 perl-blead-debug
270 perl-blead-thread-multi
271 perl-blead-thread-multi-debug
272 perl-5.18.0
273 perl-5.18.0-debug
274 perl-5.18.0-thread-multi
275 perl-5.18.0-thread-multi-debug
276 (note that the "multi" flavor is selected automatically because
278 "thread" requires it)
279 Another example using custom compilation flags:
281 perlbrew install-multiple 5.18.0 --both thread -Doptimize='-O3' --append='-O3'
283
285 Usage: perlbrew uninstall <name>
286 Uninstalls the given perl installation. The name is the installation
288 name as in the output of `perlbrew list`. This effectively deletes the
289 specified perl installation, and all libs associated with it.
290
292 Usage: perlbrew use [perl-<version> | <version> | <name>]
293 Use the given version perl in current shell. This will not effect newly
295 opened shells.
296 Without a parameter, shows the version of perl currently in use.
298
300 Usage: perlbrew switch [ <name> ]
301 Switch to the given version, and makes it the default for this and all
303 future terminal sessions.
304 Without a parameter, shows the version of perl currently selected.
306
308 Usage: perlbrew list
309 List all perl installations inside perlbrew root specified by
311 $PERLBREW_ROOT environment variable. By default, the value is
312 "~/perl5/perlbrew".
313 If there are libs associated to some perl installations, they will be
315 included as part of the name. The output items in this list can be the
316 argument in various other commands.
317
319 Usage: perlbrew available [--all]
320 List the recently available versions of perl on CPAN.
322 By default, the latest sub-version of each stable versions are listed.
324 To get a list of all perls ever released, inculding development and RC
326 versions, run the command with "--all" option.
327
329 Usage: perlbrew off
330 Temporarily disable perlbrew in the current shell. Effectively re-
332 enables the default system Perl, whatever that is.
333 This command works only if you add the statement of `source
335 $PERLBREW_ROOT/etc/bashrc` in your shell initialization (bashrc /
336 zshrc).
337
339 Usage: perlbrew switch-off
340 Permananently disable perlbrew. Use "switch" command to re-enable it.
342 Invoke "use" command to enable it only in the current shell.
343 Re-enables the default system Perl, whatever that is.
345
347 Usage: perlbrew alias [-f] create <name> <alias>
348 Create an alias for the installation named <name>.
350 Usage: perlbrew alias [-f] rename <old_alias> <new_alias>
352 Rename the alias to a new name.
354 Usage: perlbrew alias delete <alias>
356 Delete the given alias.
358
360 Usage: perlbrew exec [options] <command> <args...>
361 Options for "exec" command:
363 --with perl-version,... - only use these versions
365 --min n.nnnnn - minimum perl version
366 (format is the same as in 'use 5.012')
367 --max n.nnnnn - maximum perl version
368 --halt-on-error - stop on first nonzero exit status
369 Execute command for each perl installations, one by one.
371 For example, run a Hello program:
373 perlbrew exec perl -e 'print "Hello from $]\n"'
375 The output looks like this:
377 perl-5.12.2
379 ==========
380 Hello word from perl-5.012002
381 perl-5.13.10
383 ==========
384 Hello word from perl-5.013010
385 perl-5.14.0
387 ==========
388 Hello word from perl-5.014000
389 Notice that the command is not executed in parallel.
391 When "--with" argument is provided, the command will be only executed
393 with the specified perl installations. The following command install
394 Moose module into perl-5.12, regardless the current perl:
395 perlbrew exec --with perl-5.12 cpanm Moose
397 Multiple installation names can be provided:
399 perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo
401 They are split by either spaces or commas. When spaces are used, it is
403 required to quote the whole specification as one argument, but then
404 commas can be used in the installation names:
405 perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo
407 As demonstrated above, "perl-" prefix can be omitted, and lib names can
409 be specified too. Lib names can appear without a perl installation
410 name, in such cases it is assumed to be "current perl".
411 At the moment, any specified names that fails to be resolved as a real
413 installation names are silently ignored in the output. Also, the
414 command exit status are not populated back.
415
417 Usage: perlbrew env [ <name> ]
418 Low-level command. Invoke this command to see the list of environment
420 variables that are set by "perlbrew" itself for shell integration.
421 The output is something similar to this (if your shell is bash/zsh):
423 export PERLBREW_ROOT=/Users/gugod/perl5/perlbrew
425 export PERLBREW_VERSION=0.31
426 export PERLBREW_PATH=/Users/gugod/perl5/perlbrew/bin:/Users/gugod/perl5/perlbrew/perls/current/bin
427 export PERLBREW_PERL=perl-5.14.1
428 tcsh / csh users should see 'setenv' statements instead of `export`.
430
432 Usage: perlbrew symlink-executables [ <name> ]
433 Low-level command. This command is used to create the "perl" executable
435 symbolic link to, say, "perl5.13.6". This is only required for
436 development version of perls.
437 You don't need to do this unless you have been using old perlbrew to
439 install perls, and you find yourself confused because the perl that you
440 just installed appears to be missing after invoking `use` or `switch`.
441 perlbrew changes its installation layout since version 0.11, which
442 generates symlinks to executables in a better way.
443 If you just upgraded perlbrew (from 0.11 or earlier versions) and
445 "perlbrew switch" failed to work after you switch to a development
446 release of perl, say, perl-5.13.6, run this command:
447 perlbrew symlink-executables perl-5.13.6
449 This essentially creates this symlink:
451 ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl
453 -> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6
454 Newly installed perls, whether they are development versions or not,
456 does not need manually treatment with this command.
457
459 Usage: perlbrew install-cpanm
460 Install the "cpanm" standalone executable in "$PERLBREW_ROOT/bin".
462 For more rationale about the existence of this command, read
464 <https://perlbrew.pl/Perlbrew-and-Friends.html>
465 Usage: perlbrew install-cpm
467 Install the "cpm" standalone executable in "$PERLBREW_ROOT/bin".
469
471 Usage: perlbrew install-patchperl
472 Install the "patchperl" standalone executable in "$PERLBREW_ROOT/bin".
474 This is automatically invoked if your perlbrew installation is done
475 with the installer, but not with cpan.
476 For more rationale about the existence of this command, read
478 <https://perlbrew.pl/Perlbrew-and-Friends.html>
479
481 Usage: perlbrew self-upgrade
482 This command upgrades Perlbrew to its latest version.
484
486 Usage: perlbrew self-install
487 NOTICE: You should not need to run this command in your daily routine.
489 This command installs perlbrew itself to "$PERLBREW_ROOT/bin". It is
491 intended to be used by the perlbrew installer. However, you could
492 manually do the following to re-install only the "perlbrew" executable:
493 curl https://raw.githubusercontent.com/gugod/App-perlbrew/master/perlbrew -o perlbrew
495 perl ./perlbrew self-install
496 It is slightly different from running the perlbrew installer because
498 "patchperl" is not installed in this case.
499
501 Usage: perlbrew clean
502 Removes all previously downloaded Perl tarballs and build directories.
504
506 Usage: perlbrew version
507 Show the version of perlbrew.
509
511 Usage: perlbrew lib <action> <lib-name>
512 perlbrew lib list
514 perlbrew lib create <lib-name>
515 perlbrew lib delete <lib-name>
516 The `lib` command is used to manipulate local::lib roots inside perl
518 installations. Effectively it is similar to `perl
519 -Mlocal::lib=/path/to/lib-name`, but a little bit more than just that.
520 A lib name can be a short name, containing alphanumeric, like
522 'awesome', or a full name, prefixed by a perl installation name and a
523 '@' sign, for example, 'perl-5.14.2@awesome'.
524 Here are some a brief examples to invoke the `lib` command:
526 # Create lib perl-5.12.3@shizuka
528 perlbrew lib create perl-5.12.3@shizuka
529 # Create lib perl-5.14.2@nobita and perl-5.14.2@shizuka
531 perlbrew use perl-5.14.2
532 perlbrew lib create nobita
533 perlbrew lib create shizuka
534 # See the list of use/switch targets
536 perlbrew list
537 # Activate a lib in current shell
539 perlbrew use perl-5.12.3@shizuka
540 perlbrew use perl-5.14.2@nobita
541 perlbrew use perl-5.14.2@shizuka
542 # Activate a lib as default
544 perlbrew switch perl-5.12.3@shizuka
545 perlbrew switch perl-5.14.2@nobita
546 perlbrew switch perl-5.14.2@shizuka
547 # Delete lib perl-5.14.2@nobita and perl-5.14.2@shizuka
549 perlbrew use perl-5.14.2
550 perlbrew lib delete nobita
551 perlbrew lib delete shizuka
552 # Delete lib perl-5.12.3@shizuka
554 perlbrew lib delete perl-5.12.3@shizuka
555 Short lib names are local to current perl. A lib name 'nobita' can
557 refer to 'perl-5.12.3@nobita' or 'perl-5.14.2@nobita', whichever is
558 activated in the current shell.
559 When "use"ing or "switch"ing to a lib, always provide the long name. A
561 simple rule: the argument to "use" or "switch" command should appear in
562 the output of "perlbrew list".
563
565 Usage: perlbrew upgrade-perl
566 Running this command upgrades the currently activated perl to its
568 latest released brothers. If you have a shell with 5.32.0 activated, it
569 upgrades it to 5.32.1.
570 Minor Perl releases (ex. 5.x.*) are binary compatible with one another,
572 so this command offers you the ability to upgrade older perlbrew
573 environments in place.
574
576 Usage:
577 perlbrew download <perl-release>
578 Examples:
580 perlbrew download perl-5.14.2
581 perlbrew download perl-5.16.1
582 perlbrew download perl-5.17.3
583 Download the specified version of perl distribution tarball under the
585 directory "$PERLBREW_ROOT/dists/".
586 The argument "perl-release" should be one of the items from "perlbrew
588 available" command.
589
591 Usage:
592 perlbrew list-modules
593 List all installed cpan modules for the current perl.
595 This command can be used in conjunction with `perlbrew exec` to migrate
597 your module installation to different perl. The following command re-
598 installs all modules under perl-5.16.0:
599 perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
601 Note that this installs the latest versions of the Perl modules on the
603 new perl, which are not necessarily the same module versions you had
604 installed previously.
605
607 Usage:
608 perlbrew clone-modules [options] <destination>
610 perlbrew clone-modules [options] <source> <destination>
611 Options:
613 --notest Skip all module tests
615 This command re-installs all CPAN modules found from one installation
617 to another. For example, this lists all modules under '5.26.1' and re-
618 installs them under '5.27.7':
619 perlbrew clone-modules 5.26.1 5.27.7
621 The argument "source" is optional and defaults to the currently
623 activated one. However if none is activated (perlbrew is switched off),
624 it it an error.
625 Note that this does not guarantee that the versions of modules stay the
627 same in the destination.
628
630 App::perlbrew, App::cpanminus, Devel::PatchPerl
631perl v5.38.0 2023-07-21 PERLBREW(1)