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-cpm Install cpm, a faster but still friendly companion.
39 install-multiple Install multiple versions and flavors of perl
40 download Download the specified perl distribution tarball.
42 clean Purge tarballs and build directories
43 version Display version
44 help Read more detailed instructions
45 Generic command options:
47 -q --quiet Be quiet on informative output message.
49 -v --verbose Tell me more about it.
50 See `perlbrew help` for the full documentation of perlbrew, or
52 See `perlbrew help <command>` for detail description of the command.
54
56 PERLBREW_ROOT
57 By default, perlbrew builds and installs perls into
58 "$ENV{HOME}/perl5/perlbrew" directory. To use a different
59 directory, set this environment variable in your "bashrc" to the
60 directory in your shell RC before sourcing perlbrew's RC.
61 It is possible to share one perlbrew root with multiple user
63 account on the same machine. Therefore people do not have to
64 install the same version of perl over an over. Let's say
65 "/opt/perl5" is the directory we want to share. All users should be
66 able append this snippet to their bashrc to make it effective:
67 export PERLBREW_ROOT=/opt/perl5
69 source ${PERLBREW_ROOT}/etc/bashrc
70 After doing so, everyone's PATH should include "/opt/perl5/bin" and
72 "/opt/perl5/perls/${PERLBREW_PERL}/bin". Each user can invoke
73 "perlbrew switch" and "perlbrew use" to independently switch to
74 different perl environment of their choice. However, only the user
75 with write permission to $PERLBREW_ROOT may install CPAN modules.
76 This is both good and bad depending on the working convention of
77 your team.
78 If you wish to install CPAN modules only for yourself, you should
80 use the "lib" command to construct a personal local::lib
81 environment. local::lib environments are personal, and are not
82 shared between different users. For more detail, read "perlbrew
83 help lib" and the documentation of local::lib.
84 If you want even a cooler module isolation and wish to install CPAN
86 modules used for just one project, you should use carton for this
87 purpose.
88 It is also possible to set this variable before installing perlbrew
90 to make perlbrew install itself under the given PERLBREW_ROOT:
91 export PERLBREW_ROOT=/opt/perl5
93 curl -L https://install.perlbrew.pl | bash
94 After doing this, the perlbrew executable is installed as
96 "/opt/perl5/bin/perlbrew"
97 PERLBREW_HOME
99 By default, perlbrew stores per-user setting to
100 "$ENV{HOME}/.perlbrew" directory. To use a different directory, set
101 this environment variable in your shell RC before sourcing
102 perlbrew's RC.
103 In some cases, say, your home directory is on NFS and shared across
105 multiple machines, you may wish to have several different perlbrew
106 setting per-machine. To do so, you can use the "PERLBREW_HOME"
107 environment variable to tell perlbrew where to look for the
108 initialization file. Here's a brief bash snippet for the given
109 scenario.
110 if [ "$(hostname)" == "machine-a" ]; then
112 export PERLBREW_HOME=~/.perlbrew-a
113 elif [ "$(hostname)" == "machine-b" ]; then
114 export PERLBREW_HOME=~/.perlbrew-b
115 fi
116 source ~/perl5/perlbrew/etc/bashrc
118 PERLBREW_CONFIGURE_FLAGS
120 This environment variable specify the list of command like flags to
121 pass through to 'sh Configure'. By default it is '-de'.
122 PERLBREW_CPAN_MIRROR
124 The CPAN mirror url of your choice. By default,
125 "https://cpan.metacpan.org" is used.
126
128 Usage: perlbrew init
129 The "init" command should be manually invoked whenever you (the
131 perlbrew user) upgrade or reinstall perlbrew.
132 If the upgrade is done with "self-upgrade" command, or by running the
134 one-line installer manually, this command is invoked automatically.
135
137 info [module]
138 Usage: perlbrew info [ <module> ]
139 Display useful information about the perlbrew installation.
141 If a module is given the version and location of the module is
143 displayed.
144
146 Usage:
147 perlbrew install [options] <perl-release>
149 perlbrew install [options] /path/to/perl-5.14.0.tar.gz
150 perlbrew install [options] /path/to/perl/git/checkout/dir
151 perlbrew install [options] https://example.com/mirror/perl-5.12.3.tar.gz
152 Build and install the wanted perl. The last argument can be a short
154 string designating a specific version which can be known from the
155 output of "perlbrew available", a path to a pre-downloaded tarball, a
156 path to a git-checkout of perl5 repo, or a URL to a tarball.
157 The format of <perl-release> looks like:
159 perl-<version>
161 perl-stable
162 perl-blead
163 <version>
164 stable
165 blead
166 cperl-<version>
167 Version numbers usually look like "5.x.xx", or "perl-5.xx.x-RCx" for
169 release candidates.
170 Version "stable" is a special token that means whatever the latest
172 stable version is at the moment.
173 Version "blead" is also a special token that means whatever the latest
175 version in the repository, which is downloaded from this specific URL
176 regardless of mirror settings:
177 https://github.com/Perl/perl5/archive/blead.tar.gz
179 The specified perl is downloaded from the official CPAN website or from
181 the mirror site configured before.
182 Version number alone without the "perl-" prefix means the official
184 release provided by perl5 porters.
185 The prefix "cperl" is a special release provided not by perl5 porters,
187 but from the community. The cperl distributions are downloaded from:
188 https://github.com/perl11/cperl/releases
190 See https://perl11.org/cperl/ for more information about cperl
192 distribution.
193 Options for "install" command:
195 -f --force Force installation
197 -j $n Parallel building and testing. ex. C<perlbrew install -j 5 perl-5.14.2>
198 -n --notest Skip testing
199 --switch Automatically switch to this Perl once successfully
201 installed, as if with `perlbrew switch <version>`
202 --as Install the given version of perl by a name.
204 ex. C<perlbrew install perl-5.6.2 --as legacy-perl>
205 --noman Skip installation of manpages
207 --thread Build perl with usethreads enabled
209 --multi Build perl with usemultiplicity enabled
210 --64int Build perl with use64bitint enabled
211 --64all Build perl with use64bitall enabled
212 --ld Build perl with uselongdouble enabled
213 --debug Build perl with DEBUGGING enabled
214 --clang Build perl using the clang compiler
215 --no-patchperl
216 Skip calling patchperl
217 -D,-U,-A Switches passed to perl Configure script.
219 ex. C<perlbrew install perl-5.10.1 -D usemymalloc -U versiononly>
220 --destdir $path
222 Install perl as per 'make install DESTDIR=$path'
223 --sitecustomize $filename
225 Specify a file to be installed as sitecustomize.pl
226 --mirror $URL
228 Specify a CPAN-mirror URL. The default value of this is "https://www.cpan.org"
229 By default, all installations are configured after their name like
231 this:
232 sh Configure -de -Dprefix=$PERLBREW_ROOT/perls/<name>
234
236 Usage: perlbrew install-multiple [options] <perl-version-1>
237 <perl-version-2> ...
238 Build and install the given versions of perl.
240 "install-multiple" accepts the same set of options as the command
242 "install" plus the following ones:
243 --both $flavor Where $flavor is one of C<thread>, C<multi>, C<ld>,
245 C<64int>, C<64all>, C<debug> and C<clang>.
246 For every given perl version, install two
248 flavors, one with the flag C<--$flavor> set
249 and the other with out. C<--both> can be
250 passed multiple times with different values
251 and in that case, all the possible
252 combinations are generated.
253 --common-variations equivalent to C<--both thread --both ld --both 64int>
255 --all-variations generates all the possible flavor combinations
257 --append $string Appends the given string to the generated names
259 For instance:
261 perlbrew install-multiple 5.18.0 blead --both thread --both debug
263 Installs the following perls:
265 perl-blead
267 perl-blead-debug
268 perl-blead-thread-multi
269 perl-blead-thread-multi-debug
270 perl-5.18.0
271 perl-5.18.0-debug
272 perl-5.18.0-thread-multi
273 perl-5.18.0-thread-multi-debug
274 (note that the "multi" flavor is selected automatically because
276 "thread" requires it)
277 Another example using custom compilation flags:
279 perlbrew install-multiple 5.18.0 --both thread -Doptimize='-O3' --append='-O3'
281
283 Usage: perlbrew uninstall <name>
284 Uninstalls the given perl installation. The name is the installation
286 name as in the output of `perlbrew list`. This effectively deletes the
287 specified perl installation, and all libs associated with it.
288
290 Usage: perlbrew use [perl-<version> | <version> | <name>]
291 Use the given version perl in current shell. This will not effect newly
293 opened shells.
294 Without a parameter, shows the version of perl currently in use.
296
298 Usage: perlbrew switch [ <name> ]
299 Switch to the given version, and makes it the default for this and all
301 future terminal sessions.
302 Without a parameter, shows the version of perl currently selected.
304
306 Usage: perlbrew list
307 List all perl installations inside perlbrew root specified by
309 $PERLBREW_ROOT environment variable. By default, the value is
310 "~/perl5/perlbrew".
311 If there are libs associated to some perl installations, they will be
313 included as part of the name. The output items in this list can be the
314 argument in various other commands.
315
317 Usage: perlbrew available [--all]
318 List the recently available versions of perl on CPAN.
320 By default, the latest sub-version of each stable versions are listed.
322 To get a list of all perls ever released, inculding development and RC
324 versions, run the command with "--all" option.
325
327 Usage: perlbrew off
328 Temporarily disable perlbrew in the current shell. Effectively re-
330 enables the default system Perl, whatever that is.
331 This command works only if you add the statement of `source
333 $PERLBREW_ROOT/etc/bashrc` in your shell initialization (bashrc /
334 zshrc).
335
337 Usage: perlbrew switch-off
338 Permananently disable perlbrew. Use "switch" command to re-enable it.
340 Invoke "use" command to enable it only in the current shell.
341 Re-enables the default system Perl, whatever that is.
343
345 Usage: perlbrew alias [-f] create <name> <alias>
346 Create an alias for the installation named <name>.
348 Usage: perlbrew alias [-f] rename <old_alias> <new_alias>
350 Rename the alias to a new name.
352 Usage: perlbrew alias delete <alias>
354 Delete the given alias.
356
358 Usage: perlbrew exec [options] <command> <args...>
359 Options for "exec" command:
361 --with perl-version,... - only use these versions
363 --min n.nnnnn - minimum perl version
364 (format is the same as in 'use 5.012')
365 --max n.nnnnn - maximum perl version
366 --halt-on-error - stop on first nonzero exit status
367 Execute command for each perl installations, one by one.
369 For example, run a Hello program:
371 perlbrew exec perl -e 'print "Hello from $]\n"'
373 The output looks like this:
375 perl-5.12.2
377 ==========
378 Hello word from perl-5.012002
379 perl-5.13.10
381 ==========
382 Hello word from perl-5.013010
383 perl-5.14.0
385 ==========
386 Hello word from perl-5.014000
387 Notice that the command is not executed in parallel.
389 When "--with" argument is provided, the command will be only executed
391 with the specified perl installations. The following command install
392 Moose module into perl-5.12, regardless the current perl:
393 perlbrew exec --with perl-5.12 cpanm Moose
395 Multiple installation names can be provided:
397 perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo
399 They are split by either spaces or commas. When spaces are used, it is
401 required to quote the whole specification as one argument, but then
402 commas can be used in the installation names:
403 perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo
405 As demonstrated above, "perl-" prefix can be omitted, and lib names can
407 be specified too. Lib names can appear without a perl installation
408 name, in such cases it is assumed to be "current perl".
409 At the moment, any specified names that fails to be resolved as a real
411 installation names are silently ignored in the output. Also, the
412 command exit status are not populated back.
413
415 Usage: perlbrew env [ <name> ]
416 Low-level command. Invoke this command to see the list of environment
418 variables that are set by "perlbrew" itself for shell integration.
419 The output is something similar to this (if your shell is bash/zsh):
421 export PERLBREW_ROOT=/Users/gugod/perl5/perlbrew
423 export PERLBREW_VERSION=0.31
424 export PERLBREW_PATH=/Users/gugod/perl5/perlbrew/bin:/Users/gugod/perl5/perlbrew/perls/current/bin
425 export PERLBREW_PERL=perl-5.14.1
426 tcsh / csh users should see 'setenv' statements instead of `export`.
428
430 Usage: perlbrew symlink-executables [ <name> ]
431 Low-level command. This command is used to create the "perl" executable
433 symbolic link to, say, "perl5.13.6". This is only required for
434 development version of perls.
435 You don't need to do this unless you have been using old perlbrew to
437 install perls, and you find yourself confused because the perl that you
438 just installed appears to be missing after invoking `use` or `switch`.
439 perlbrew changes its installation layout since version 0.11, which
440 generates symlinks to executables in a better way.
441 If you just upgraded perlbrew (from 0.11 or earlier versions) and
443 "perlbrew switch" failed to work after you switch to a development
444 release of perl, say, perl-5.13.6, run this command:
445 perlbrew symlink-executables perl-5.13.6
447 This essentially creates this symlink:
449 ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl
451 -> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6
452 Newly installed perls, whether they are development versions or not,
454 does not need manually treatment with this command.
455
457 Usage: perlbrew install-cpanm
458 Install the "cpanm" standalone executable in "$PERLBREW_ROOT/bin".
460 For more rationale about the existence of this command, read
462 <https://perlbrew.pl/Perlbrew-and-Friends.html>
463 Usage: perlbrew install-cpm
465 Install the "cpm" standalone executable in "$PERLBREW_ROOT/bin".
467
469 Usage: perlbrew install-patchperl
470 Install the "patchperl" standalone executable in "$PERLBREW_ROOT/bin".
472 This is automatically invoked if your perlbrew installation is done
473 with the installer, but not with cpan.
474 For more rationale about the existence of this command, read
476 <https://perlbrew.pl/Perlbrew-and-Friends.html>
477
479 Usage: perlbrew self-upgrade
480 This command upgrades Perlbrew to its latest version.
482
484 Usage: perlbrew self-install
485 NOTICE: You should not need to run this command in your daily routine.
487 This command installs perlbrew itself to "$PERLBREW_ROOT/bin". It is
489 intended to be used by the perlbrew installer. However, you could
490 manually do the following to re-install only the "perlbrew" executable:
491 curl https://raw.githubusercontent.com/gugod/App-perlbrew/master/perlbrew -o perlbrew
493 perl ./perlbrew self-install
494 It is slightly different from running the perlbrew installer because
496 "patchperl" is not installed in this case.
497
499 Usage: perlbrew clean
500 Removes all previously downloaded Perl tarballs and build directories.
502
504 Usage: perlbrew version
505 Show the version of perlbrew.
507
509 Usage: perlbrew lib <action> <lib-name>
510 perlbrew lib list
512 perlbrew lib create <lib-name>
513 perlbrew lib delete <lib-name>
514 The `lib` command is used to manipulate local::lib roots inside perl
516 installations. Effectively it is similar to `perl
517 -Mlocal::lib=/path/to/lib-name`, but a little bit more than just that.
518 A lib name can be a short name, containing alphanumeric, like
520 'awesome', or a full name, prefixed by a perl installation name and a
521 '@' sign, for example, 'perl-5.14.2@awesome'.
522 Here are some a brief examples to invoke the `lib` command:
524 # Create lib perl-5.12.3@shizuka
526 perlbrew lib create perl-5.12.3@shizuka
527 # Create lib perl-5.14.2@nobita and perl-5.14.2@shizuka
529 perlbrew use perl-5.14.2
530 perlbrew lib create nobita
531 perlbrew lib create shizuka
532 # See the list of use/switch targets
534 perlbrew list
535 # Activate a lib in current shell
537 perlbrew use perl-5.12.3@shizuka
538 perlbrew use perl-5.14.2@nobita
539 perlbrew use perl-5.14.2@shizuka
540 # Activate a lib as default
542 perlbrew switch perl-5.12.3@shizuka
543 perlbrew switch perl-5.14.2@nobita
544 perlbrew switch perl-5.14.2@shizuka
545 # Delete lib perl-5.14.2@nobita and perl-5.14.2@shizuka
547 perlbrew use perl-5.14.2
548 perlbrew lib delete nobita
549 perlbrew lib delete shizuka
550 # Delete lib perl-5.12.3@shizuka
552 perlbrew lib delete perl-5.12.3@shizuka
553 Short lib names are local to current perl. A lib name 'nobita' can
555 refer to 'perl-5.12.3@nobita' or 'perl-5.14.2@nobita', whichever is
556 activated in the current shell.
557 When "use"ing or "switch"ing to a lib, always provide the long name. A
559 simple rule: the argument to "use" or "switch" command should appear in
560 the output of "perlbrew list".
561
563 Usage: perlbrew upgrade-perl
564 Running this command upgrades the currently activated perl to its
566 latest released brothers. If you have a shell with 5.32.0 activated, it
567 upgrades it to 5.32.1.
568 Minor Perl releases (ex. 5.x.*) are binary compatible with one another,
570 so this command offers you the ability to upgrade older perlbrew
571 environments in place.
572
574 Usage:
575 perlbrew download <perl-release>
576 Examples:
578 perlbrew download perl-5.14.2
579 perlbrew download perl-5.16.1
580 perlbrew download perl-5.17.3
581 Download the specified version of perl distribution tarball under the
583 directory "$PERLBREW_ROOT/dists/".
584 The argument "perl-release" should be one of the items from "perlbrew
586 available" command.
587
589 Usage:
590 perlbrew list-modules
591 List all installed cpan modules for the current perl.
593 This command can be used in conjunction with `perlbrew exec` to migrate
595 your module installation to different perl. The following command re-
596 installs all modules under perl-5.16.0:
597 perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
599 Note that this installs the latest versions of the Perl modules on the
601 new perl, which are not necessarily the same module versions you had
602 installed previously.
603
605 Usage:
606 perlbrew clone-modules [options] <destination>
608 perlbrew clone-modules [options] <source> <destination>
609 Options:
611 --notest Skip all module tests
613 This command re-installs all CPAN modules found from one installation
615 to another. For example, this list all modules under '5.26.1' and re-
616 install them under '5.27.7':
617 perlbrew clone-modules 5.26.1 5.27.7
619 The argument "source" is optional and is default to the current
621 activated one. However if none is activated (perlbrew is switched off),
622 it it an error.
623 Noted that this does not guarantee that the versions of modules stays
625 the same in the destination.
626
628 App::perlbrew, App::cpanminus, Devel::PatchPerl
629perl v5.36.0 2022-08-01 PERLBREW(1)