1zef(1)                User Contributed Perl Documentation               zef(1)
2
3
4
5   Zef
6       Raku / Perl6 Module Management
7

Installation

9       Manual
10
11           $ git clone https://github.com/ugexe/zef.git
12           $ cd zef
13           $ perl6 -I. bin/zef install .
14
15       Rakudobrew
16
17       To install via rakudobrew, please use the following command:
18
19           $ rakudobrew build zef
20

USAGE

22           zef --help
23           zef --version
24
25           # install the CSV::Parser distribution
26           zef install CSV::Parser
27
28           # search for distribution names matching `CSV`
29           zef search CSV
30
31           # detailed information for a matching distribution
32           zef info CSV::Parser
33
34           # list all available distributions
35           zef list
36
37           # list reverse dependencies of an identity
38           zef rdepends HTTP::UserAgent
39
40           # test project in current directory
41           zef test .
42
43           # fetch a specific module only
44           zef fetch CSV::Parser
45
46           # fetch a module, then shell into its local path
47           zef look CSV::Parser
48
49           # smoke test modules from all repositories
50           zef smoke
51
52           # run Build.pm if one exists in given path
53           zef build .
54
55           # update Repository package lists
56           zef update
57
58           # upgrade all distributions (BETA)
59           zef upgrade
60
61           # upgrade specific distribution (BETA)
62           zef upgrade CSV::Parser
63
64           # lookup module info by name/path/sha1
65           zef --sha1 locate 9FA0AC28824EE9E5A9C0F99951CA870148AE378E
66
67           # launch browser to named support urls from meta data
68           zef browse zef bugtracker
69
70   More CLI
71       install [*@identities]
72
73       Note: The install process does not install anything until all phases
74       have completed. So, if the user requested to "install A", and A
75       required module B: both would be downloaded, potentially built, tested,
76       and installed -- but only if both passed all their tests. For example:
77       if module A failed its tests, then module B would not be installed
78       (even if it passed its own tests) unless forced.
79
80       [@identities] can take the form of a file path (starting with . or /),
81       URLs, paths, or identities:
82
83           # IDENTITY
84           zef install CSV::Parser
85           zef install "CSV::Parser:auth<tony-o>:ver<0.1.2>"
86           zef install "CSV::Parser:ver<0.1.2>"
87
88           # PATH
89           zef install ./Perl6-Net--HTTP
90
91           # URL
92           zef -v install git://github.com/ugexe/zef.git
93           zef -v install https://github.com/ugexe/zef/archive/master.tar.gz
94           zef -v install https://github.com/ugexe/zef.git@v0.1.22
95
96       A request may contain any number and combination of these. Paths and
97       URLs will be resolved first so they are available to fulfill any
98       dependencies of other requested identities.
99
100       Options
101
102           # Install to a custom locations
103           --install-to=<id> # site/home/vendor/perl, or
104           -to=<id>          # inst#/home/some/path/custom
105
106           # Install all transitive and direct dependencies
107           # even if they are already installed globally (BETA)
108           --contained
109
110           # Load a specific Zef config file
111           --config-path=/some/path/config.json
112
113           # Install only the dependency chains of the requested distributions
114           --deps-only
115
116           # Ignore errors occuring during the corresponding phase
117           --force-resolve
118           --force-fetch
119           --force-extract
120           --force-build
121           --force-test
122           --force-install
123
124           # or set the default to all unset --force-* flags to True
125           --force
126
127           # Set the timeout for corresponding phases
128           --fetch-timeout=600
129           --extract-timeout=3600
130           --build-timeout=3600
131           --test-timeout=3600
132           --install-timeout=3600
133
134           # Number of simultaneous distributions/jobs to process for the corresponding phases
135           --fetch-degree=5
136           --test-degree=1
137
138           # or set the default to all unset --*-timeout flags to 0
139           --timeout=0
140
141           # Do everything except the actual installations
142           --dry
143
144           # Build/Test/Install each dependency serially before proceeding to Build/Test/Install the next
145           --serial
146
147           # Disable testing
148           --/test
149
150           # Disable build phase
151           --/build
152
153           # Disable fetching dependencies
154           --/depends
155           --/build-depends
156           --/test-depends
157
158           # Force a refresh for all module index indexes
159           --update
160
161           # Force a refresh for a specific ecosystem module index
162           --update=[ecosystem]
163
164           # Skip refreshing all module index indexes
165           --/update
166
167           # Skip refreshing for a specific ecosystem module index
168           --/update=[ecosystem]
169
170       ENV Options
171
172           # Number of simultaneous distributions/jobs to process for the corresponding phases (see: --[phase]-degree options)
173           ZEF_FETCH_DEGREE=5
174           ZEF_TEST_DEGREE=1
175
176           # Set the timeout for corresponding phases (see: --[phase]-timeout options)
177           ZEF_FETCH_TIMEOUT=600
178           ZEF_EXTRACT_TIMEOUT=3600
179           ZEF_BUILD_TIMEOUT=3600
180           ZEF_TEST_TIMEOUT=3600
181           ZEF_INSTALL_TIMEOUT=3600
182
183       uninstall [*@identities]
184
185       Uninstall the specified distributions
186
187       Note: Requires a bleeding edge rakudo (not available in 6.c)
188
189       update
190
191       Update the package indexes for all "Repository" backends
192
193       Note: Some "Repository" backends, like the default Ecosystems, have an
194       "auto-update" option in "resources/config.json" that can be enabled.
195       This should be the number of hours until it should auto update based on
196       the file system last modified time of the ecosystem json file location.
197
198       upgrade [*@identities] BETA
199
200       Upgrade specified identities. If no identities are provided, zef
201       attempts to upgrade all installed distributions.
202
203       search [$identity]
204
205       How these are handled depends on the "Repository" engine used, which by
206       default is "Zef::Repository::Ecosystems>p6c<"
207
208           $ zef -v --cpan --metacpan search URI
209           ===> Found 4 results
210           -------------------------------------------------------------------------
211           ID|From                              |Package             |Description
212           -------------------------------------------------------------------------
213           1 |Zef::Repository::LocalCache       |URI:ver<0.1.1>    |A URI impleme...
214           2 |Zef::Repository::Ecosystems<p6c>  |URI:ver<0.1.1>    |A URI impleme...
215           3 |Zef::Repository::Ecosystems<cpan> |URI:ver<0.1.1>    |A URI impleme...
216           4 |Zef::Repository::Ecosystems<cpan> |URI:ver<0.000.001>|A URI impleme...
217           -------------------------------------------------------------------------
218
219       info [$identity]
220
221       View meta information of a distribution
222
223           $ zef -v info HTTP::UserAgent
224           - Info for: HTTP::UserAgent
225           - Identity: HTTP::UserAgent:ver<1.1.16>:auth<github:sergot>
226           - Recommended By: Zef::Repository::LocalCache
227           Author:  github:sergot
228           Description:     Web user agent
229           Source-url:      git://github.com/sergot/http-useragent.git
230           Provides: 11 modules
231           #       HTTP::Cookie
232           #       HTTP::Header
233           #       HTTP::Cookies
234           #       HTTP::Message
235           #       HTTP::Request
236           #       HTTP::Response
237           #       HTTP::MediaType
238           #       HTTP::UserAgent
239           #       HTTP::Header::Field
240           #       HTTP::Request::Common
241           #       HTTP::UserAgent::Common
242           Depends: 7 items
243           ---------------------------------
244           ID|Identity           |Installed?
245           ---------------------------------
246           1 |HTTP::Status       |X
247           2 |File::Temp         |X
248           3 |DateTime::Parse    |X
249           4 |Encode             |X
250           5 |MIME::Base64       |X
251           6 |URI                |X
252           7 |IO::Capture::Simple|X
253           ---------------------------------
254
255       Options
256
257           # Extra details (eg, list dependencies and which ones are installed)
258           -v
259
260       list [*@from]
261
262       List known available distributions
263
264           $ zef --installed list
265           ===> Found via /home/nickl/.rakudobrew/moar-master/install/share/perl6/site
266           CSV::Parser:ver<0.1.2>:auth<github:tony-o>
267           Zef:auth<github:ugexe>
268           ===> Found via /home/nickl/.rakudobrew/moar-master/install/share/perl6
269           CORE:ver<6.c>:auth<perl>
270
271       Note that not every Repository may provide such a list, and such lists
272       may only be a subset. For example: We may not be able to get a list of
273       every distribution on metacpan, but we *can* get the $x most recent
274       additions (we use 100 for now).
275
276       [@from] allows you to show results from specific repositories only:
277
278           zef --installed list perl   # Only list modules installed by rakudo itself
279
280           zef list cpan               # Only show available modules from the repository
281           zef list p6c                # with a name field matching the arguments to `list`
282           zef list cached             # (be sure the repository is enabled in config)
283
284       Otherwise results from all enabled repositories will be returned.
285
286       Options
287
288           # Only list installed distributions
289           --installed
290
291           # Additionally list the modules of discovered distributions
292           -v
293
294       depends [$identity]
295
296       List direct and transitive dependencies to the first successful build
297       graph for $identity
298
299           $ zef depends Cro::SSL
300           Cro::Core:ver<0.7>
301           IO::Socket::Async::SSL:ver<0.3>
302           OpenSSL:ver<0.1.14>:auth<github:sergot>
303
304       rdepends [$identity]
305
306       List available distributions that directly depend on $identity
307
308           $ zef rdepends Net::HTTP
309           Minecraft-Tools:ver<0.1.0>
310           LendingClub:ver<0.1.0>
311
312       fetch [*@identities]
313
314       Fetches candidates for given identities
315
316       test [*@paths]
317
318       Run tests on each distribution located at [@paths]
319
320       build [*@paths]
321
322       Run the Build.pm file located in the given [@paths]
323
324       If you want to create a build hook, put the following dependency-free
325       boilerplate in a file named "Build.pm" at the root of your
326       distribution:
327
328           class Build {
329               method build($dist-path) {
330                   # do build stuff to your module
331                   # which is located at $dist-path
332               }
333           }
334
335       Set the env variable ZEF_BUILDPM_DEBUG=1 or use the --debug flag for
336       additional debugging information.
337
338       Note: In the future, a more appropriate hooking solution will replace
339       this.
340
341       look [$identity]
342
343       Fetches the requested distribution and any dependencies (if requested),
344       changes the directory to that of the fetched distribution, and then
345       stops program execution. This allows you modify or look at the source
346       code before manually continuing the install via "zef install ."
347
348       Note that the path to any dependencies that needed to be fetched will
349       be set in env at PERL6LIB, so you should be able to run any build
350       scripts, tests, or complete a manual install without having to specify
351       their locations.
352
353       browse $identity [bugtracker | homepage | source]
354
355       Options
356
357           # disables launching a browser window (just shows url)
358           --/open
359
360       Output the url and launch a browser to open it.
361
362           # also opens browser
363           $ zef browse Net::HTTP bugtracker
364           https://github.com/ugexe/Perl6-Net--HTTP/issues
365
366           # only outputs the url
367           $ zef browse Net::HTTP bugtracker --/open
368           https://github.com/ugexe/Perl6-Net--HTTP/issues
369
370       locate [$identity, $name-path, $sha1-id]
371
372       Options
373
374           # The argument is a sha1-id (otherwise assumed to be an identity or name-path)
375           --sha1
376
377       Lookup a locally installed module by $identity, $name-path, or $sha1-id
378
379           $ zef --sha1 locate A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
380           ===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
381           lib/Zef/CLI.pm6 => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
382
383           $ zef locate Zef::CLI
384           ===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
385           lib/Zef/CLI.pm6 => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
386
387           $ zef locate lib/Zef/CLI.pm6
388           ===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
389           Zef::CLI => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
390
391       nuke [RootDir | TempDir | StoreDir]
392
393       Deletes all paths in the specific configuration directory
394
395       nuke [site | home]
396
397       Deletes all paths that are rooted in the prefix of the matching
398       CompUnit::Repository name
399
400           # uninstall all modules
401           $ zef nuke site home
402
403   Output Verbosity
404       You can control the logging level using the following flags:
405
406           # More/less detailed output
407           --error, --warn, --info (default), --verbose (-v), --debug
408

Global Configuration

410       Finding the configuration file
411
412       You can always see the configuration file that will be used by running:
413
414           $ zef --help
415
416       In most cases the default configuration combined with command line
417       options should be enough for most users.
418
419       If you are most users (e.g. not: power users, packagers, zef plugin
420       developers) you hopefully don't care about this section!
421
422       How the configuration file is chosen
423
424       The configuration file will be chosen at runtime from one of two
425       (technically four) locations, and one can affect the others (this is
426       not really a design decision and suggestions and PRs are welcome).
427
428       First, and the most precise way, is to specify the config file by
429       passing "--config-path="..."" to any zef command.
430
431       Second, third, and fourth we look at the path pointed to by
432       "%?RESOURCES<config.json>". This will point to
433       "$zef-dir/resources/config.json", where "$zef-dir" will be either:
434
435       •   The prefix of a common configuration directory, such as
436           $XDG_CONFIG_HOME  or "$HOME/.config".
437
438       •   The prefix of a rakudo installation location - This is the case if
439           the modules loaded for bin/zef come from an installation
440           CompUnit::Repository.
441
442       •   The current working directory $*CWD - This is the case when modules
443           loaded for bin/zef come from a non-installation
444           CompUnit::Repository (such as "-I $dist-path").
445
446           To understand how this is chosen, consider:
447
448               # Modules not loaded from an ::Installation,
449               # so %?RESOURCES is $*CWD/resources
450               $ perl6 -I. bin/zef --help
451               ...
452               CONFIGURATION /home/user/perl6/zef/resources/config.json
453               ...
454
455               # Installed zef script loads modules from an ::Installation,
456               # so %?RESOURCES is $perl6-share-dir/site/resources
457               $ zef --help
458               ...
459               CONFIGURATION /home/user/perl6/install/share/perl6/site/resources/EE5DBAABF07682ECBE72BEE98E6B95E5D08675DE.json
460               ...
461
462       This config is loaded, but it is not yet the chosen config! We check
463       that temporary config's "%config<RootDir>" for valid json in a file
464       named "config.json" (i.e. "%config<RootDir>/config.json"). This can be
465       confusing (so it may go away or be refined - PRs welcome) but for most
466       cases it just means "$*HOME/.zef/config.json" will override an
467       installed zef configuration file.
468
469       To summarize:
470
471       •   You can edit the "resources/config.json" file before you install
472           zef.
473
474           When you "perl6 -I. bin/zef install ." that configuration file be
475           be used to install zef and will also be installed with zef such
476           that it will be the default.
477
478       •   You can create a "%config<RootDir>/config.json" file.
479
480           Where "%config<RootDir>" comes from the previously mentioned
481           "%?RESOURCES<config.json>"'s "RootDir" field ("$*HOME/.zef" in most
482           cases), to allow overriding zef config behavior on a per user basis
483           (allows setting different "--install-to" targets for, say, a root
484           user and a regular user). Since this new config file could have a
485           different "RootDir" than the default config (used to find the new
486           one in the first place) this behavior may be changed in the future
487           to be less confusing.
488
489       •   You can override both of the previous entries by passing "zef
490           --config-path="$path" <any command>"
491
492       Configuration fields
493
494       Basic Settings
495
496RootDir - Where zef will look for a custom config.json file
497
498TempDir - A staging area for items that have been fetched and need
499           to be extracted/moved
500
501StoreDir - Where zef caches distributions, package lists, etc after
502           they've been fetched and extracted
503
504DefaultCUR - This sets the default value for "--install-to="..."".
505           The default value of "auto" means it will first try installing to
506           rakudo's installation prefix, and if its not writable by the
507           current user it will install to "$*HOME/.perl6". These directories
508           are not chosen by zef - they are actually represented by the magic
509           strings "site" and "home" (which, like "auto", are valid values
510           despite not being paths along with "vendor" and "perl")
511
512       Phases / Plugins Settings
513
514       These consist of an array of hashes that describe how to instantiate
515       some class that fulfills the appropriate interface from Zef.pm
516       ("Repository" "Fetcher" "Extractor" "Builder" "Tester")
517
518       The descriptions follow this format:
519
520           {
521               "short-name" : "p6c",
522               "enabled" : 1,
523               "module" : "Zef::Repository::Ecosystems",
524               "options" : { }
525           }
526
527       and are instantiated via
528
529           ::($hash<module>).new(|($hash<options>)
530
531short-name - This adds an enable and disable flag by the same name
532           to the CLI (e.g. "--p6c" and "--/p6c") and is used when referencing
533           which object took some action.
534
535enabled - Set to 0 to skip over the object during consideration (it
536           will never be loaded). If omitted or if the value is non 0 then it
537           will be enabled for use.
538
539module - The name of the class to instantiate. While it doesn't
540           technically have to be a module it does need to be a known
541           namespace to "require".
542
543options - These are passed to the objects "new" method and may not
544           be consistent between modules as they are free to implement their
545           own requirements.
546
547       See the configuration file in resources/config.json
548       <https://github.com/ugexe/zef/blob/master/resources/config.json> for a
549       little more information on how plugins are invoked.
550
551       You can see debug output related to chosing and loading plugins by
552       setting the env variable ZEF_PLUGIN_DEBUG=1
553

FAQ

555       CPAN?
556
557       CPAN is now used as a default (alongside the familiar p6c "ecosystem").
558
559           # Explicitly enable cpan (now defaults to the same as `zef search zef`)
560           $ zef --cpan search Inline::Perl5
561
562       Proxy support?
563
564       All the default fetching plugins have proxy support, but you'll need to
565       refer to the backend program's (wget, curl, git, etc) docs. You may
566       need to set an ENV variable, or you may need to add a command line
567       option for that specific plugin in resources/config.json
568
569       Custom installation locations?
570
571       Pass a path to the -to / --install-to option and prefix the path with
572       "inst#" (unless you know what you're doing)
573
574           $ zef -to="inst#/home/perl6/custom" install Text::Table::Simple
575           ===> Searching for: Text::Table::Simple
576           ===> Testing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
577           ===> Testing [OK] for Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
578           ===> Installing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
579
580       To make the custom location discoverable:
581
582           # Set the PERL6LIB env:
583           $ PERL6LIB="inst#/home/perl6/custom" perl6 -e "use Text::Table::Simple; say 'ok'"
584           ok
585
586           # or simply include it as needed
587           $ perl6 -Iinst#/home/perl6/custom -e "use Text::Table::Simple; say 'ok'"
588           ok
589
590       Test reporting?
591
592       This feature can be enabled by passing `--p6ctesters` (and having
593       "Net::HTTP" installed) or `--cpantesters` (and having
594       "Zef::CPANReporter" installed)
595
596
597
598perl v5.34.0                      2022-01-21                            zef(1)
Impressum