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       install [options] perl-<version>
146       install [options] <version>
147           Build and install the given version of perl.
148
149           Version numbers usually look like "5.x.xx", or "perl-5.xx.x-RCx"
150           for release candidates.
151
152           The specified perl is downloaded from the official CPAN website or
153           from the mirror site configured before.
154
155           Add '--mirror $URL' to specify the URL of mirror site.
156
157       install [options] cperl-<version>
158           Install the cperl distribution released from:
159
160               https://github.com/perl11/cperl/releases
161
162           See  http://perl11.org/cperl/ for more information about cperl
163           distribution.
164
165       install [options]  perl-stable
166       install [options]  stable
167           A convenient way to install the most recent stable version of Perl,
168           of those that are available.
169
170       install [options]  perl-blead
171       install [options]  blead
172           A special way to install the blead version of perl, which is
173           downloaded from this specific URL regardless of mirror settings:
174
175               http://perl5.git.perl.org/perl.git/snapshot/blead.tar.gz
176
177       install  [options] /path/to/perl/git/checkout/dir
178           Build and install from the given git checkout dir.
179
180       install  [options] /path/to/perl-5.14.0.tar.gz
181           Build and install from the given archive file.
182
183       install  [options] http://example.com/mirror/perl-5.12.3.tar.gz
184           Build and install from the given URL. Supported URL schemes are
185           "http://", "https://", "ftp://" and "file://".
186
187       Options for "install" command:
188
189           -f --force     Force installation
190           -j $n          Parallel building and testing. ex. C<perlbrew install -j 5 perl-5.14.2>
191           -n --notest    Skip testing
192
193              --switch    Automatically switch to this Perl once successfully
194                          installed, as if with `perlbrew switch <version>`
195
196              --as        Install the given version of perl by a name.
197                          ex. C<perlbrew install perl-5.6.2 --as legacy-perl>
198
199              --noman     Skip installation of manpages
200
201              --thread    Build perl with usethreads enabled
202              --multi     Build perl with usemultiplicity enabled
203              --64int     Build perl with use64bitint enabled
204              --64all     Build perl with use64bitall enabled
205              --ld        Build perl with uselongdouble enabled
206              --debug     Build perl with DEBUGGING enabled
207              --clang     Build perl using the clang compiler
208              --no-patchperl
209                          Skip calling patchperl
210
211           -D,-U,-A       Switches passed to perl Configure script.
212                          ex. C<perlbrew install perl-5.10.1 -D usemymalloc -U versiononly>
213
214           --destdir $path
215                          Install perl as per 'make install DESTDIR=$path'
216
217           --sitecustomize $filename
218                          Specify a file to be installed as sitecustomize.pl
219
220       By default, all installations are configured after their name like
221       this:
222
223           sh Configure -de -Dprefix=$PERLBREW_ROOT/perls/<name>
224

COMMAND: INSTALL-MULTIPLE

226       Usage: perlbrew install-multiple [options] <perl-version-1>
227       <perl-version-2> ...
228
229       Build and install the given versions of perl.
230
231       "install-multiple" accepts the same set of options as the command
232       "install" plus the following ones:
233
234           --both $flavor       Where $flavor is one of C<thread>, C<multi>, C<ld>,
235                                C<64int>, C<64all>, C<debug> and C<clang>.
236
237                                For every given perl version, install two
238                                flavors, one with the flag C<--$flavor> set
239                                and the other with out. C<--both> can be
240                                passed multiple times with different values
241                                and in that case, all the possible
242                                combinations are generated.
243
244           --common-variations  equivalent to C<--both thread --both ld --both 64int>
245
246           --all-variations     generates all the possible flavor combinations
247
248           --append $string     Appends the given string to the generated names
249
250       For instance:
251
252           perlbrew install-multiple 5.18.0 blead --both thread --both debug
253
254       Installs the following perls:
255
256           perl-blead
257           perl-blead-debug
258           perl-blead-thread-multi
259           perl-blead-thread-multi-debug
260           perl-5.18.0
261           perl-5.18.0-debug
262           perl-5.18.0-thread-multi
263           perl-5.18.0-thread-multi-debug
264
265       (note that the "multi" flavor is selected automatically because
266       "thread" requires it)
267
268       Another example using custom compilation flags:
269
270           perlbrew install-multiple 5.18.0 --both thread -Doptimize='-O3' --append='-O3'
271

COMMAND: UNINSTALL

273       Usage: perlbrew uninstall <name>
274
275       Uninstalls the given perl installation. The name is the installation
276       name as in the output of `perlbrew list`. This effectively deletes the
277       specified perl installation, and all libs associated with it.
278

COMMAND: USE

280       Usage: perlbrew use [perl-<version> | <version> | <name>]
281
282       Use the given version perl in current shell. This will not effect newly
283       opened shells.
284
285       Without a parameter, shows the version of perl currently in use.
286

COMMAND: SWITCH

288       Usage: perlbrew switch [ <name> ]
289
290       Switch to the given version, and makes it the default for this and all
291       future terminal sessions.
292
293       Without a parameter, shows the version of perl currently selected.
294

COMMAND: LIST

296       Usage: perlbrew list
297
298       List all perl installations inside perlbrew root specified by
299       $PERLBREW_ROOT environment variable. By default, the value is
300       "~/perl5/perlbrew".
301
302       If there are libs associated to some perl installations, they will be
303       included as part of the name. The output items in this list can be the
304       argument in various other commands.
305

COMMAND: AVAILABLE

307       Usage: perlbrew available [--all]
308
309       List the recently available versions of perl on CPAN.
310
311       The list is retrieved from the web page
312       <http://www.cpan.org/src/README.html>, and is not the list of *all*
313       perl versions ever released in the past.
314
315       To get a list of all perls ever released, use the "--all" option.
316
317       NOTICE: This command might be gone in the future and becomes an option
318       of 'list' command.
319

COMMAND: OFF

321       Usage: perlbrew off
322
323       Temporarily disable perlbrew in the current shell. Effectively re-
324       enables the default system Perl, whatever that is.
325
326       This command works only if you add the statement of `source
327       $PERLBREW_ROOT/etc/bashrc` in your shell initialization (bashrc /
328       zshrc).
329

COMMAND: SWITCH-OFF

331       Usage: perlbrew switch-off
332
333       Permananently disable perlbrew. Use "switch" command to re-enable it.
334       Invoke "use" command to enable it only in the current shell.
335
336       Re-enables the default system Perl, whatever that is.
337

COMMAND: ALIAS

339       Usage: perlbrew alias [-f] create <name> <alias>
340
341           Create an alias for the installation named <name>.
342
343       Usage: perlbrew alias [-f] rename <old_alias> <new_alias>
344
345           Rename the alias to a new name.
346
347       Usage: perlbrew alias delete <alias>
348
349           Delete the given alias.
350

COMMAND: EXEC

352       Usage: perlbrew exec [--with perl-name[,perl-name...]] <command>
353       <args...>
354
355       Execute command for each perl installations, one by one.
356
357       For example, run a Hello program:
358
359           perlbrew exec perl -e 'print "Hello from $]\n"'
360
361       The output looks like this:
362
363           perl-5.12.2
364           ==========
365           Hello word from perl-5.012002
366
367           perl-5.13.10
368           ==========
369           Hello word from perl-5.013010
370
371           perl-5.14.0
372           ==========
373           Hello word from perl-5.014000
374
375       Notice that the command is not executed in parallel.
376
377       When "--with" argument is provided, the command will be only executed
378       with the specified perl installations. The following command install
379       Moose module into perl-5.12, regardless the current perl:
380
381           perlbrew exec --with perl-5.12 cpanm Moose
382
383       Multiple installation names can be provided:
384
385           perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo
386
387       They are split by either spaces or commas. When spaces are used, it is
388       required to quote the whole specification as one argument, but then
389       commas can be used in the installation names:
390
391           perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo
392
393       As demonstrated above, "perl-" prefix can be omitted, and lib names can
394       be specified too. Lib names can appear without a perl installation
395       name, in such cases it is assumed to be "current perl".
396
397       At the moment, any specified names that fails to be resolved as a real
398       installation names are silently ignored in the output. Also, the
399       command exit status are not populated back.
400

COMMAND: ENV

402       Usage: perlbrew env [ <name> ]
403
404       Low-level command. Invoke this command to see the list of environment
405       variables that are set by "perlbrew" itself for shell integration.
406
407       The output is something similar to this (if your shell is bash/zsh):
408
409           export PERLBREW_ROOT=/Users/gugod/perl5/perlbrew
410           export PERLBREW_VERSION=0.31
411           export PERLBREW_PATH=/Users/gugod/perl5/perlbrew/bin:/Users/gugod/perl5/perlbrew/perls/current/bin
412           export PERLBREW_PERL=perl-5.14.1
413
414       tcsh / csh users should see 'setenv' statements instead of `export`.
415
417       Usage: perlbrew symlink-executables [ <name> ]
418
419       Low-level command. This command is used to create the "perl" executable
420       symbolic link to, say, "perl5.13.6". This is only required for
421       development version of perls.
422
423       You don't need to do this unless you have been using old perlbrew to
424       install perls, and you find yourself confused because the perl that you
425       just installed appears to be missing after invoking `use` or `switch`.
426       perlbrew changes its installation layout since version 0.11, which
427       generates symlinks to executables in a better way.
428
429       If you just upgraded perlbrew (from 0.11 or earlier versions) and
430       "perlbrew switch" failed to work after you switch to a development
431       release of perl, say, perl-5.13.6, run this command:
432
433           perlbrew symlink-executables perl-5.13.6
434
435       This essentially creates this symlink:
436
437          ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl
438          -> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6
439
440       Newly installed perls, whether they are development versions or not,
441       does not need manually treatment with this command.
442

COMMAND: INSTALL-CPANM

444       Usage: perlbrew install-cpanm
445
446       Install the "cpanm" standalone executable in "$PERLBREW_ROOT/bin".
447
448       For more rationale about the existence of this command, read
449       <http://perlbrew.pl/Perlbrew-and-Friends.html>
450

COMMAND: INSTALL-PATCHPERL

452       Usage: perlbrew install-patchperl
453
454       Install the "patchperl" standalone executable in "$PERLBREW_ROOT/bin".
455       This is automatically invoked if your perlbrew installation is done
456       with the installer, but not with cpan.
457
458       For more rationale about the existence of this command, read
459       <http://perlbrew.pl/Perlbrew-and-Friends.html>
460

COMMAND: SELF-UPGRADE

462       Usage: perlbrew self-upgrade
463
464       This command upgrades Perlbrew to its latest version.
465

COMMAND: SELF-INSTALL

467       Usage: perlbrew self-install
468
469       NOTICE: You should not need to run this command in your daily routine.
470
471       This command install perlbrew itself to "$PERLBREW_ROOT/bin". It is
472       intended to be used by the perlbrew installer. However, you could
473       manually do the following to re-install only the "perlbrew" executable:
474
475           curl https://raw.githubusercontent.com/gugod/App-perlbrew/master/perlbrew -o perlbrew
476           perl ./perlbrew self-install
477
478       It is slightly different from running the perlbrew installer because
479       "patchperl" is not installed in this case.
480

COMMAND: CLEAN

482       Usage: perlbrew clean
483
484       Removes all previously downloaded Perl tarballs and build directories.
485

COMMAND: VERSION

487       Usage: perlbrew version
488
489       Show the version of perlbrew.
490

COMMAND: LIB

492       Usage: perlbrew lib <action> <lib-name>
493
494           perlbrew lib list
495           perlbrew lib create <lib-name>
496           perlbrew lib delete <lib-name>
497
498       The `lib` command is used to manipulate local::lib roots inside perl
499       installations. Effectively it is similar to `perl
500       -Mlocal::lib=/path/to/lib-name`, but a little bit more than just that.
501
502       A lib name can be a short name, containing alphanumeric, like
503       'awesome', or a full name, prefixed by a perl installation name and a
504       '@' sign, for example, 'perl-5.14.2@awesome'.
505
506       Here are some a brief examples to invoke the `lib` command:
507
508           # Create lib perl-5.12.3@shizuka
509           perlbrew lib create perl-5.12.3@shizuka
510
511           # Create lib perl-5.14.2@nobita and perl-5.14.2@shizuka
512           perlbrew use perl-5.14.2
513           perlbrew lib create nobita
514           perlbrew lib create shizuka
515
516           # See the list of use/switch targets
517           perlbrew list
518
519           # Activate a lib in current shell
520           perlbrew use perl-5.12.3@shizuka
521           perlbrew use perl-5.14.2@nobita
522           perlbrew use perl-5.14.2@shizuka
523
524           # Activate a lib as default
525           perlbrew switch perl-5.12.3@shizuka
526           perlbrew switch perl-5.14.2@nobita
527           perlbrew switch perl-5.14.2@shizuka
528
529           # Delete lib perl-5.14.2@nobita and perl-5.14.2@shizuka
530           perlbrew use perl-5.14.2
531           perlbrew lib delete nobita
532           perlbrew lib delete shizuka
533
534           # Delete lib perl-5.12.3@shizuka
535           perlbrew lib delete perl-5.12.3@shizuka
536
537       Short lib names are local to current perl. A lib name 'nobita' can
538       refer to 'perl-5.12.3@nobita' or 'perl-5.14.2@nobita', depending on
539       your current perl.
540
541       When "use"ing or "switch"ing to a lib, always provide the long name. A
542       simple rule: the argument to "use" or "switch" command should appear in
543       the output of "perlbrew list".
544

COMMAND: UPGRADE-PERL

546       Usage: perlbrew upgrade-perl
547
548       Minor Perl releases (ex. 5.x.*) are binary compatible with one another,
549       so this command offers you the ability to upgrade older perlbrew
550       environments in place.
551
552       It upgrades the currently activated perl to its latest released
553       brothers. If you have a shell with 5.14.0 activated, it upgrades it to
554       5.14.2.
555

COMMAND: DOWNLOAD

557       Usage:
558
559           perlbrew download perl-5.14.2
560           perlbrew download perl-5.16.1
561           perlbrew download perl-5.17.3
562
563       Download the specified version of perl distribution tarball under
564       "$PERLBREW_ROOT/dists/" directory.
565

COMMAND: LIST-MODULES

567       List all installed cpan modules for the current perl.
568
569       This command can be used in conjunction with `perlbrew exec` to migrate
570       your module installation to different perl. The following command re-
571       installs all modules under perl-5.16.0:
572
573           perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
574
575       Note that this installs the latest versions of the Perl modules on the
576       new perl, which are not necessarily the same module versions you had
577       installed previously.
578

COMMAND: CLONE-MODULES

580       This command re-installs all CPAN modules found from one installation
581       to another.
582
583       Usage:
584           perlbrew clone-modules <src_version> <dst_version>
585
586       for example
587
588           perlbrew clone-modules 5.26.1 5.27.7
589

SEE ALSO

591       App::perlbrew, App::cpanminus, Devel::PatchPerl
592
593
594
595perl v5.28.1                      2019-01-19                       PERLBREW(1)
Impressum