1PERLBREW(1) User Contributed Perl Documentation PERLBREW(1)
2
3
4
6 perlbrew - Perl environment manager.
7
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
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
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
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
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
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
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
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
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
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
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 become an option
318 of 'list' command.
319
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
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
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
352 Usage: perlbrew exec [options] <command> <args...>
353
354 Options for "exec" command:
355
356 --with perl-version,... - only use these versions
357 --min n.nnnnn - minimum perl version
358 (format is the same as in 'use 5.012')
359 --max n.nnnnn - maximum perl version
360 --halt-on-error - stop on first nonzero exit status
361
362 Execute command for each perl installations, one by one.
363
364 For example, run a Hello program:
365
366 perlbrew exec perl -e 'print "Hello from $]\n"'
367
368 The output looks like this:
369
370 perl-5.12.2
371 ==========
372 Hello word from perl-5.012002
373
374 perl-5.13.10
375 ==========
376 Hello word from perl-5.013010
377
378 perl-5.14.0
379 ==========
380 Hello word from perl-5.014000
381
382 Notice that the command is not executed in parallel.
383
384 When "--with" argument is provided, the command will be only executed
385 with the specified perl installations. The following command install
386 Moose module into perl-5.12, regardless the current perl:
387
388 perlbrew exec --with perl-5.12 cpanm Moose
389
390 Multiple installation names can be provided:
391
392 perlbrew exec --with perl-5.12,perl-5.12-debug,perl-5.14.2 cpanm Moo
393
394 They are split by either spaces or commas. When spaces are used, it is
395 required to quote the whole specification as one argument, but then
396 commas can be used in the installation names:
397
398 perlbrew exec --with '5.12 5.12,debug 5.14.2@nobita @shizuka' cpanm Moo
399
400 As demonstrated above, "perl-" prefix can be omitted, and lib names can
401 be specified too. Lib names can appear without a perl installation
402 name, in such cases it is assumed to be "current perl".
403
404 At the moment, any specified names that fails to be resolved as a real
405 installation names are silently ignored in the output. Also, the
406 command exit status are not populated back.
407
409 Usage: perlbrew env [ <name> ]
410
411 Low-level command. Invoke this command to see the list of environment
412 variables that are set by "perlbrew" itself for shell integration.
413
414 The output is something similar to this (if your shell is bash/zsh):
415
416 export PERLBREW_ROOT=/Users/gugod/perl5/perlbrew
417 export PERLBREW_VERSION=0.31
418 export PERLBREW_PATH=/Users/gugod/perl5/perlbrew/bin:/Users/gugod/perl5/perlbrew/perls/current/bin
419 export PERLBREW_PERL=perl-5.14.1
420
421 tcsh / csh users should see 'setenv' statements instead of `export`.
422
424 Usage: perlbrew symlink-executables [ <name> ]
425
426 Low-level command. This command is used to create the "perl" executable
427 symbolic link to, say, "perl5.13.6". This is only required for
428 development version of perls.
429
430 You don't need to do this unless you have been using old perlbrew to
431 install perls, and you find yourself confused because the perl that you
432 just installed appears to be missing after invoking `use` or `switch`.
433 perlbrew changes its installation layout since version 0.11, which
434 generates symlinks to executables in a better way.
435
436 If you just upgraded perlbrew (from 0.11 or earlier versions) and
437 "perlbrew switch" failed to work after you switch to a development
438 release of perl, say, perl-5.13.6, run this command:
439
440 perlbrew symlink-executables perl-5.13.6
441
442 This essentially creates this symlink:
443
444 ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl
445 -> ${PERLBREW_ROOT}/perls/perl-5.13.6/bin/perl5.13.6
446
447 Newly installed perls, whether they are development versions or not,
448 does not need manually treatment with this command.
449
451 Usage: perlbrew install-cpanm
452
453 Install the "cpanm" standalone executable in "$PERLBREW_ROOT/bin".
454
455 For more rationale about the existence of this command, read
456 <http://perlbrew.pl/Perlbrew-and-Friends.html>
457
459 Usage: perlbrew install-patchperl
460
461 Install the "patchperl" standalone executable in "$PERLBREW_ROOT/bin".
462 This is automatically invoked if your perlbrew installation is done
463 with the installer, but not with cpan.
464
465 For more rationale about the existence of this command, read
466 <http://perlbrew.pl/Perlbrew-and-Friends.html>
467
469 Usage: perlbrew self-upgrade
470
471 This command upgrades Perlbrew to its latest version.
472
474 Usage: perlbrew self-install
475
476 NOTICE: You should not need to run this command in your daily routine.
477
478 This command installs perlbrew itself to "$PERLBREW_ROOT/bin". It is
479 intended to be used by the perlbrew installer. However, you could
480 manually do the following to re-install only the "perlbrew" executable:
481
482 curl https://raw.githubusercontent.com/gugod/App-perlbrew/master/perlbrew -o perlbrew
483 perl ./perlbrew self-install
484
485 It is slightly different from running the perlbrew installer because
486 "patchperl" is not installed in this case.
487
489 Usage: perlbrew clean
490
491 Removes all previously downloaded Perl tarballs and build directories.
492
494 Usage: perlbrew version
495
496 Show the version of perlbrew.
497
499 Usage: perlbrew lib <action> <lib-name>
500
501 perlbrew lib list
502 perlbrew lib create <lib-name>
503 perlbrew lib delete <lib-name>
504
505 The `lib` command is used to manipulate local::lib roots inside perl
506 installations. Effectively it is similar to `perl
507 -Mlocal::lib=/path/to/lib-name`, but a little bit more than just that.
508
509 A lib name can be a short name, containing alphanumeric, like
510 'awesome', or a full name, prefixed by a perl installation name and a
511 '@' sign, for example, 'perl-5.14.2@awesome'.
512
513 Here are some a brief examples to invoke the `lib` command:
514
515 # Create lib perl-5.12.3@shizuka
516 perlbrew lib create perl-5.12.3@shizuka
517
518 # Create lib perl-5.14.2@nobita and perl-5.14.2@shizuka
519 perlbrew use perl-5.14.2
520 perlbrew lib create nobita
521 perlbrew lib create shizuka
522
523 # See the list of use/switch targets
524 perlbrew list
525
526 # Activate a lib in current shell
527 perlbrew use perl-5.12.3@shizuka
528 perlbrew use perl-5.14.2@nobita
529 perlbrew use perl-5.14.2@shizuka
530
531 # Activate a lib as default
532 perlbrew switch perl-5.12.3@shizuka
533 perlbrew switch perl-5.14.2@nobita
534 perlbrew switch perl-5.14.2@shizuka
535
536 # Delete lib perl-5.14.2@nobita and perl-5.14.2@shizuka
537 perlbrew use perl-5.14.2
538 perlbrew lib delete nobita
539 perlbrew lib delete shizuka
540
541 # Delete lib perl-5.12.3@shizuka
542 perlbrew lib delete perl-5.12.3@shizuka
543
544 Short lib names are local to current perl. A lib name 'nobita' can
545 refer to 'perl-5.12.3@nobita' or 'perl-5.14.2@nobita', depending on
546 your current perl.
547
548 When "use"ing or "switch"ing to a lib, always provide the long name. A
549 simple rule: the argument to "use" or "switch" command should appear in
550 the output of "perlbrew list".
551
553 Usage: perlbrew upgrade-perl
554
555 Minor Perl releases (ex. 5.x.*) are binary compatible with one another,
556 so this command offers you the ability to upgrade older perlbrew
557 environments in place.
558
559 It upgrades the currently activated perl to its latest released
560 brothers. If you have a shell with 5.14.0 activated, it upgrades it to
561 5.14.2.
562
564 Usage:
565
566 perlbrew download perl-5.14.2
567 perlbrew download perl-5.16.1
568 perlbrew download perl-5.17.3
569
570 Download the specified version of perl distribution tarball under
571 "$PERLBREW_ROOT/dists/" directory.
572
574 List all installed cpan modules for the current perl.
575
576 This command can be used in conjunction with `perlbrew exec` to migrate
577 your module installation to different perl. The following command re-
578 installs all modules under perl-5.16.0:
579
580 perlbrew list-modules | perlbrew exec --with perl-5.16.0 cpanm
581
582 Note that this installs the latest versions of the Perl modules on the
583 new perl, which are not necessarily the same module versions you had
584 installed previously.
585
587 This command re-installs all CPAN modules found from one installation
588 to another.
589
590 Usage:
591 perlbrew clone-modules <src_version> <dst_version>
592
593 for example
594
595 perlbrew clone-modules 5.26.1 5.27.7
596
598 App::perlbrew, App::cpanminus, Devel::PatchPerl
599
600
601
602perl v5.30.1 2020-01-29 PERLBREW(1)