1PERLBREW(1)           User Contributed Perl Documentation          PERLBREW(1)
2
3
4

NAME

6       perlbrew - Perl environment manager.
7

SYNOPSIS

9       perlbrew command syntax:
10
11           perlbrew <command> [options] [arguments]
12
13       Commands:
14
15           init           Initialize perlbrew environment.
16           info           Show useful information about the perlbrew installation
17
18           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
25           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
33           self-install       Install perlbrew itself under PERLBREW_ROOT/bin
34           self-upgrade       Upgrade perlbrew itself.
35
36           install-patchperl  Install patchperl
37           install-cpanm      Install cpanm, a friendly companion.
38           install-multiple   Install multiple versions and flavors of perl
39
40           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
45       Generic command options:
46
47           -q --quiet     Be quiet on informative output message.
48           -v --verbose   Tell me more about it.
49
50       See `perlbrew help` for the full documentation of perlbrew, or
51
52       See `perlbrew help <command>` for detail description of the command.
53

CONFIGURATION

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
61           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
67               export PERLBREW_ROOT=/opt/perl5
68               source ${PERLBREW_ROOT}/etc/bashrc
69
70           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
78           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
84           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
88           It is also possible to set this variable before installing perlbrew
89           to make perlbrew install itself under the given PERLBREW_ROOT:
90
91               export PERLBREW_ROOT=/opt/perl5
92               curl -L http://install.perlbrew.pl | bash
93
94           After doing this, the perlbrew executable is installed as
95           "/opt/perl5/bin/perlbrew"
96
97       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
103           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
110               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
116               source ~/perl5/perlbrew/etc/bashrc
117
118       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
122       PERLBREW_CPAN_MIRROR
123           The CPAN mirror url of your choice. The default value is
124           "http://www.cpan.org"
125

COMMAND: INIT

127       Usage: perlbrew init
128
129       The "init" command should be manually invoked whenever you (the
130       perlbrew user) upgrade or reinstall perlbrew.
131
132       If the upgrade is done with "self-upgrade" command, or by running the
133       one-line installer manually, this command is invoked automatically.
134

COMMAND: INFO

136       info [module]
137           Usage: perlbrew info [ <module> ]
138
139           Display useful information about the perlbrew installation.
140
141           If a module is given the version and location of the module is
142           displayed.
143

COMMAND: INSTALL

145       Usage:
146
147           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
152       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
157       The format of <perl-release> looks like:
158
159       perl-<version>
160       perl-stable
161       perl-blead
162       <version>
163       stable
164       blead
165       cperl-<version>
166
167       Version numbers usually look like "5.x.xx", or "perl-5.xx.x-RCx" for
168       release candidates.
169
170       Version "stable" is a special token that means whatever the latest
171       stable version is at the moment.
172
173       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
177           https://github.com/Perl/perl5/archive/blead.tar.gz
178
179       The specified perl is downloaded from the official CPAN website or from
180       the mirror site configured before.
181
182       Version number alone without the "perl-" prefix means the official
183       release provided by perl5 porters.
184
185       The prefix "cperl" is a special release provided not by perl5 porters,
186       but from the community. The cperl distributions are downloaded from:
187
188           https://github.com/perl11/cperl/releases
189
190       See http://perl11.org/cperl/ for more information about cperl
191       distribution.
192
193       Options for "install" command:
194
195           -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
199              --switch    Automatically switch to this Perl once successfully
200                          installed, as if with `perlbrew switch <version>`
201
202              --as        Install the given version of perl by a name.
203                          ex. C<perlbrew install perl-5.6.2 --as legacy-perl>
204
205              --noman     Skip installation of manpages
206
207              --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
217           -D,-U,-A       Switches passed to perl Configure script.
218                          ex. C<perlbrew install perl-5.10.1 -D usemymalloc -U versiononly>
219
220           --destdir $path
221                          Install perl as per 'make install DESTDIR=$path'
222
223           --sitecustomize $filename
224                          Specify a file to be installed as sitecustomize.pl
225
226           --mirror $URL
227               Specify a CPAN-mirror URL. The default value of this is "https://www.cpan.org"
228
229       By default, all installations are configured after their name like
230       this:
231
232           sh Configure -de -Dprefix=$PERLBREW_ROOT/perls/<name>
233

COMMAND: INSTALL-MULTIPLE

235       Usage: perlbrew install-multiple [options] <perl-version-1>
236       <perl-version-2> ...
237
238       Build and install the given versions of perl.
239
240       "install-multiple" accepts the same set of options as the command
241       "install" plus the following ones:
242
243           --both $flavor       Where $flavor is one of C<thread>, C<multi>, C<ld>,
244                                C<64int>, C<64all>, C<debug> and C<clang>.
245
246                                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
253           --common-variations  equivalent to C<--both thread --both ld --both 64int>
254
255           --all-variations     generates all the possible flavor combinations
256
257           --append $string     Appends the given string to the generated names
258
259       For instance:
260
261           perlbrew install-multiple 5.18.0 blead --both thread --both debug
262
263       Installs the following perls:
264
265           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
274       (note that the "multi" flavor is selected automatically because
275       "thread" requires it)
276
277       Another example using custom compilation flags:
278
279           perlbrew install-multiple 5.18.0 --both thread -Doptimize='-O3' --append='-O3'
280

COMMAND: UNINSTALL

282       Usage: perlbrew uninstall <name>
283
284       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

COMMAND: USE

289       Usage: perlbrew use [perl-<version> | <version> | <name>]
290
291       Use the given version perl in current shell. This will not effect newly
292       opened shells.
293
294       Without a parameter, shows the version of perl currently in use.
295

COMMAND: SWITCH

297       Usage: perlbrew switch [ <name> ]
298
299       Switch to the given version, and makes it the default for this and all
300       future terminal sessions.
301
302       Without a parameter, shows the version of perl currently selected.
303

COMMAND: LIST

305       Usage: perlbrew list
306
307       List all perl installations inside perlbrew root specified by
308       $PERLBREW_ROOT environment variable. By default, the value is
309       "~/perl5/perlbrew".
310
311       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

COMMAND: AVAILABLE

316       Usage: perlbrew available [--all]
317
318       List the recently available versions of perl on CPAN.
319
320       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
324       To get a list of all perls ever released, use the "--all" option.
325
326       NOTICE: This command might be gone in the future and become an option
327       of 'list' command.
328

COMMAND: OFF

330       Usage: perlbrew off
331
332       Temporarily disable perlbrew in the current shell. Effectively re-
333       enables the default system Perl, whatever that is.
334
335       This command works only if you add the statement of `source
336       $PERLBREW_ROOT/etc/bashrc` in your shell initialization (bashrc /
337       zshrc).
338

COMMAND: SWITCH-OFF

340       Usage: perlbrew switch-off
341
342       Permananently disable perlbrew. Use "switch" command to re-enable it.
343       Invoke "use" command to enable it only in the current shell.
344
345       Re-enables the default system Perl, whatever that is.
346

COMMAND: ALIAS

348       Usage: perlbrew alias [-f] create <name> <alias>
349
350           Create an alias for the installation named <name>.
351
352       Usage: perlbrew alias [-f] rename <old_alias> <new_alias>
353
354           Rename the alias to a new name.
355
356       Usage: perlbrew alias delete <alias>
357
358           Delete the given alias.
359

COMMAND: EXEC

361       Usage: perlbrew exec [options] <command> <args...>
362
363       Options for "exec" command:
364
365           --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
371       Execute command for each perl installations, one by one.
372
373       For example, run a Hello program:
374
375           perlbrew exec perl -e 'print "Hello from $]\n"'
376
377       The output looks like this:
378
379           perl-5.12.2
380           ==========
381           Hello word from perl-5.012002
382
383           perl-5.13.10
384           ==========
385           Hello word from perl-5.013010
386
387           perl-5.14.0
388           ==========
389           Hello word from perl-5.014000
390
391       Notice that the command is not executed in parallel.
392
393       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
397           perlbrew exec --with perl-5.12 cpanm Moose
398
399       Multiple installation names can be provided:
400
401           perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo
402
403       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
407           perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo
408
409       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
413       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

COMMAND: ENV

418       Usage: perlbrew env [ <name> ]
419
420       Low-level command. Invoke this command to see the list of environment
421       variables that are set by "perlbrew" itself for shell integration.
422
423       The output is something similar to this (if your shell is bash/zsh):
424
425           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
430       tcsh / csh users should see 'setenv' statements instead of `export`.
431
433       Usage: perlbrew symlink-executables [ <name> ]
434
435       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
439       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
445       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
449           perlbrew symlink-executables perl-5.13.6
450
451       This essentially creates this symlink:
452
453          ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl
454          -> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6
455
456       Newly installed perls, whether they are development versions or not,
457       does not need manually treatment with this command.
458

COMMAND: INSTALL-CPANM

460       Usage: perlbrew install-cpanm
461
462       Install the "cpanm" standalone executable in "$PERLBREW_ROOT/bin".
463
464       For more rationale about the existence of this command, read
465       <http://perlbrew.pl/Perlbrew-and-Friends.html>
466

COMMAND: INSTALL-PATCHPERL

468       Usage: perlbrew install-patchperl
469
470       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
474       For more rationale about the existence of this command, read
475       <http://perlbrew.pl/Perlbrew-and-Friends.html>
476

COMMAND: SELF-UPGRADE

478       Usage: perlbrew self-upgrade
479
480       This command upgrades Perlbrew to its latest version.
481

COMMAND: SELF-INSTALL

483       Usage: perlbrew self-install
484
485       NOTICE: You should not need to run this command in your daily routine.
486
487       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
491           curl https://raw.githubusercontent.com/gugod/App-perlbrew/master/perlbrew -o perlbrew
492           perl ./perlbrew self-install
493
494       It is slightly different from running the perlbrew installer because
495       "patchperl" is not installed in this case.
496

COMMAND: CLEAN

498       Usage: perlbrew clean
499
500       Removes all previously downloaded Perl tarballs and build directories.
501

COMMAND: VERSION

503       Usage: perlbrew version
504
505       Show the version of perlbrew.
506

COMMAND: LIB

508       Usage: perlbrew lib <action> <lib-name>
509
510           perlbrew lib list
511           perlbrew lib create <lib-name>
512           perlbrew lib delete <lib-name>
513
514       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
518       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
522       Here are some a brief examples to invoke the `lib` command:
523
524           # Create lib perl-5.12.3@shizuka
525           perlbrew lib create perl-5.12.3@shizuka
526
527           # 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
532           # See the list of use/switch targets
533           perlbrew list
534
535           # 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
540           # 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
545           # 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
550           # Delete lib perl-5.12.3@shizuka
551           perlbrew lib delete perl-5.12.3@shizuka
552
553       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
557       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

COMMAND: UPGRADE-PERL

562       Usage: perlbrew upgrade-perl
563
564       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
568       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

COMMAND: DOWNLOAD

573       Usage:
574           perlbrew download <perl-release>
575
576       Examples:
577           perlbrew download perl-5.14.2
578           perlbrew download perl-5.16.1
579           perlbrew download perl-5.17.3
580
581       Download the specified version of perl distribution tarball under the
582       directory "$PERLBREW_ROOT/dists/".
583
584       The argument "perl-release" should be one of the items from "perlbrew
585       available" command.
586

COMMAND: LIST-MODULES

588       Usage:
589           perlbrew list-modules
590
591       List all installed cpan modules for the current perl.
592
593       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
597           perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
598
599       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

COMMAND: CLONE-MODULES

604       Usage:
605
606           perlbrew clone-modules [options] <destination>
607           perlbrew clone-modules [options] <source> <destination>
608
609       Options:
610
611           --notest    Skip all module tests
612
613       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
617           perlbrew clone-modules 5.26.1 5.27.7
618
619       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
623       Noted that this does not guarantee that the versions of modules stays
624       the same in the destination.
625

SEE ALSO

627       App::perlbrew, App::cpanminus, Devel::PatchPerl
628
629
630
631perl v5.34.0                      2021-11-24                       PERLBREW(1)
Impressum