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           Execute programs with specified perl environments.
31
32           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
35           self-install       Install perlbrew itself under PERLBREW_ROOT/bin
36           self-upgrade       Upgrade perlbrew itself.
37
38           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
43           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
48       Generic command options:
49
50           -q --quiet     Be quiet on informative output message.
51           -v --verbose   Tell me more about it.
52
53       See `perlbrew help` for the full documentation of perlbrew, or
54
55       See `perlbrew help <command>` for detail description of the command.
56

CONFIGURATION

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
64           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
70               export PERLBREW_ROOT=/opt/perl5
71               source ${PERLBREW_ROOT}/etc/bashrc
72
73           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
81           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
87           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
91           It is also possible to set this variable before installing perlbrew
92           to make perlbrew install itself under the given PERLBREW_ROOT:
93
94               export PERLBREW_ROOT=/opt/perl5
95               curl -L https://install.perlbrew.pl | bash
96
97           After doing this, the perlbrew executable is installed as
98           "/opt/perl5/bin/perlbrew"
99
100       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
106           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
113               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
119               source ~/perl5/perlbrew/etc/bashrc
120
121       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
125       PERLBREW_CPAN_MIRROR
126           The CPAN mirror url of your choice. By default,
127           "https://cpan.metacpan.org" is used.
128

COMMAND: INIT

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

COMMAND: INFO

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

COMMAND: INSTALL

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

COMMAND: INSTALL-MULTIPLE

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

COMMAND: UNINSTALL

285       Usage: perlbrew uninstall <name>
286
287       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

COMMAND: USE

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

COMMAND: SWITCH

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

COMMAND: LIST

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

COMMAND: AVAILABLE

319       Usage: perlbrew available [--all]
320
321       List the recently available versions of perl on CPAN.
322
323       By default, the latest sub-version of each stable versions are listed.
324
325       To get a list of all perls ever released, inculding development and RC
326       versions, run the command with "--all" option.
327

COMMAND: OFF

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

COMMAND: SWITCH-OFF

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

COMMAND: ALIAS

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

COMMAND: EXEC

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

COMMAND: ENV

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

COMMAND: INSTALL-CPANM

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

COMMAND: INSTALL-PATCHPERL

471       Usage: perlbrew install-patchperl
472
473       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
477       For more rationale about the existence of this command, read
478       <https://perlbrew.pl/Perlbrew-and-Friends.html>
479

COMMAND: SELF-UPGRADE

481       Usage: perlbrew self-upgrade
482
483       This command upgrades Perlbrew to its latest version.
484

COMMAND: SELF-INSTALL

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

COMMAND: CLEAN

501       Usage: perlbrew clean
502
503       Removes all previously downloaded Perl tarballs and build directories.
504

COMMAND: VERSION

506       Usage: perlbrew version
507
508       Show the version of perlbrew.
509

COMMAND: LIB

511       Usage: perlbrew lib <action> <lib-name>
512
513           perlbrew lib list
514           perlbrew lib create <lib-name>
515           perlbrew lib delete <lib-name>
516
517       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
521       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
525       Here are some a brief examples to invoke the `lib` command:
526
527           # Create lib perl-5.12.3@shizuka
528           perlbrew lib create perl-5.12.3@shizuka
529
530           # 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
535           # See the list of use/switch targets
536           perlbrew list
537
538           # 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
543           # 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
548           # 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
553           # Delete lib perl-5.12.3@shizuka
554           perlbrew lib delete perl-5.12.3@shizuka
555
556       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
560       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

COMMAND: UPGRADE-PERL

565       Usage: perlbrew upgrade-perl
566
567       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
571       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

COMMAND: DOWNLOAD

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

COMMAND: LIST-MODULES

591       Usage:
592           perlbrew list-modules
593
594       List all installed cpan modules for the current perl.
595
596       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
600           perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
601
602       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

COMMAND: CLONE-MODULES

607       Usage:
608
609           perlbrew clone-modules [options] <destination>
610           perlbrew clone-modules [options] <source> <destination>
611
612       Options:
613
614           --notest    Skip all module tests
615
616       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
620           perlbrew clone-modules 5.26.1 5.27.7
621
622       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
626       Note that this does not guarantee that the versions of modules stay the
627       same in the destination.
628

SEE ALSO

630       App::perlbrew, App::cpanminus, Devel::PatchPerl
631
632
633
634perl v5.38.0                      2023-07-21                       PERLBREW(1)
Impressum