1zef(1) User Contributed Perl Documentation zef(1)
2 Zef
6 Raku / Perl6 Module Management
7
9 Manual
10 $ git clone https://github.com/ugexe/zef.git
12 $ cd zef
13 $ perl6 -I. bin/zef install .
14 Rakudobrew
16 To install via rakudobrew, please use the following command:
18 $ rakudobrew build zef
20
22 zef --help
23 zef --version
24 # install the CSV::Parser distribution
26 zef install CSV::Parser
27 # search for distribution names matching `CSV`
29 zef search CSV
30 # detailed information for a matching distribution
32 zef info CSV::Parser
33 # list all available distributions
35 zef list
36 # list reverse dependencies of an identity
38 zef rdepends HTTP::UserAgent
39 # test project in current directory
41 zef test .
42 # fetch a specific module only
44 zef fetch CSV::Parser
45 # fetch a module, then shell into its local path
47 zef look CSV::Parser
48 # smoke test modules from all repositories
50 zef smoke
51 # run Build.pm if one exists in given path
53 zef build .
54 # update Repository package lists
56 zef update
57 # upgrade all distributions (BETA)
59 zef upgrade
60 # upgrade specific distribution (BETA)
62 zef upgrade CSV::Parser
63 # lookup module info by name/path/sha1
65 zef --sha1 locate 9FA0AC28824EE9E5A9C0F99951CA870148AE378E
66 # launch browser to named support urls from meta data
68 zef browse zef bugtracker
69 More CLI
71 install [*@identities]
72 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 [@identities] can take the form of a file path (starting with . or /),
81 URLs, paths, or identities:
82 # 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 # PATH
89 zef install ./Perl6-Net--HTTP
90 # 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 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 Options
101 # Install to a custom locations
103 --install-to=<id> # site/home/vendor/perl, or
104 -to=<id> # inst#/home/some/path/custom
105 # Install all transitive and direct dependencies
107 # even if they are already installed globally (BETA)
108 --contained
109 # Load a specific Zef config file
111 --config-path=/some/path/config.json
112 # Install only the dependency chains of the requested distributions
114 --deps-only
115 # 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 # or set the default to all unset --force-* flags to True
125 --force
126 # 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 # Number of simultaneous distributions/jobs to process for the corresponding phases
135 --fetch-degree=5
136 --test-degree=1
137 # or set the default to all unset --*-timeout flags to 0
139 --timeout=0
140 # Do everything except the actual installations
142 --dry
143 # Build/Test/Install each dependency serially before proceeding to Build/Test/Install the next
145 --serial
146 # Disable testing
148 --/test
149 # Disable build phase
151 --/build
152 # Disable fetching dependencies
154 --/depends
155 --/build-depends
156 --/test-depends
157 # Force a refresh for all module index indexes
159 --update
160 # Force a refresh for a specific ecosystem module index
162 --update=[ecosystem]
163 # Skip refreshing all module index indexes
165 --/update
166 # Skip refreshing for a specific ecosystem module index
168 --/update=[ecosystem]
169 ENV Options
171 # 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 # 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 uninstall [*@identities]
184 Uninstall the specified distributions
186 Note: Requires a bleeding edge rakudo (not available in 6.c)
188 update
190 Update the package indexes for all "Repository" backends
192 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 upgrade [*@identities] BETA
199 Upgrade specified identities. If no identities are provided, zef
201 attempts to upgrade all installed distributions.
202 search [$identity]
204 How these are handled depends on the "Repository" engine used, which by
206 default is "Zef::Repository::Ecosystems>p6c<"
207 $ 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 info [$identity]
220 View meta information of a distribution
222 $ 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 Options
256 # Extra details (eg, list dependencies and which ones are installed)
258 -v
259 list [*@from]
261 List known available distributions
263 $ 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 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 [@from] allows you to show results from specific repositories only:
277 zef --installed list perl # Only list modules installed by rakudo itself
279 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 Otherwise results from all enabled repositories will be returned.
285 Options
287 # Only list installed distributions
289 --installed
290 # Additionally list the modules of discovered distributions
292 -v
293 depends [$identity]
295 List direct and transitive dependencies to the first successful build
297 graph for $identity
298 $ 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 rdepends [$identity]
305 List available distributions that directly depend on $identity
307 $ zef rdepends Net::HTTP
309 Minecraft-Tools:ver<0.1.0>
310 LendingClub:ver<0.1.0>
311 fetch [*@identities]
313 Fetches candidates for given identities
315 test [*@paths]
317 Run tests on each distribution located at [@paths]
319 build [*@paths]
321 Run the Build.pm file located in the given [@paths]
323 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 class Build {
329 method build($dist-path) {
330 # do build stuff to your module
331 # which is located at $dist-path
332 }
333 }
334 Set the env variable ZEF_BUILDPM_DEBUG=1 or use the --debug flag for
336 additional debugging information.
337 Note: In the future, a more appropriate hooking solution will replace
339 this.
340 look [$identity]
342 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 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 browse $identity [bugtracker | homepage | source]
354 Options
356 # disables launching a browser window (just shows url)
358 --/open
359 Output the url and launch a browser to open it.
361 # also opens browser
363 $ zef browse Net::HTTP bugtracker
364 https://github.com/ugexe/Perl6-Net--HTTP/issues
365 # only outputs the url
367 $ zef browse Net::HTTP bugtracker --/open
368 https://github.com/ugexe/Perl6-Net--HTTP/issues
369 locate [$identity, $name-path, $sha1-id]
371 Options
373 # The argument is a sha1-id (otherwise assumed to be an identity or name-path)
375 --sha1
376 Lookup a locally installed module by $identity, $name-path, or $sha1-id
378 $ 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 $ 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 $ 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 nuke [RootDir | TempDir | StoreDir]
392 Deletes all paths in the specific configuration directory
394 nuke [site | home]
396 Deletes all paths that are rooted in the prefix of the matching
398 CompUnit::Repository name
399 # uninstall all modules
401 $ zef nuke site home
402 Output Verbosity
404 You can control the logging level using the following flags:
405 # More/less detailed output
407 --error, --warn, --info (default), --verbose (-v), --debug
408
410 Finding the configuration file
411 You can always see the configuration file that will be used by running:
413 $ zef --help
415 In most cases the default configuration combined with command line
417 options should be enough for most users.
418 If you are most users (e.g. not: power users, packagers, zef plugin
420 developers) you hopefully don't care about this section!
421 How the configuration file is chosen
423 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 First, and the most precise way, is to specify the config file by
429 passing "--config-path="..."" to any zef command.
430 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 • The prefix of a common configuration directory, such as
436 $XDG_CONFIG_HOME or "$HOME/.config".
437 • 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 • 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 To understand how this is chosen, consider:
447 # 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 # 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 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 To summarize:
470 • You can edit the "resources/config.json" file before you install
472 zef.
473 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 • You can create a "%config<RootDir>/config.json" file.
479 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 • You can override both of the previous entries by passing "zef
490 --config-path="$path" <any command>"
491 Configuration fields
493 Basic Settings
495 • RootDir - Where zef will look for a custom config.json file
497 • TempDir - A staging area for items that have been fetched and need
499 to be extracted/moved
500 • StoreDir - Where zef caches distributions, package lists, etc after
502 they've been fetched and extracted
503 • DefaultCUR - 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 Phases / Plugins Settings
513 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 The descriptions follow this format:
519 {
521 "short-name" : "p6c",
522 "enabled" : 1,
523 "module" : "Zef::Repository::Ecosystems",
524 "options" : { }
525 }
526 and are instantiated via
528 ::($hash<module>).new(|($hash<options>)
530 • short-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 • enabled - 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 • module - 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 • options - 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 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 You can see debug output related to chosing and loading plugins by
552 setting the env variable ZEF_PLUGIN_DEBUG=1
553
555 CPAN?
556 CPAN is now used as a default (alongside the familiar p6c "ecosystem").
558 # Explicitly enable cpan (now defaults to the same as `zef search zef`)
560 $ zef --cpan search Inline::Perl5
561 Proxy support?
563 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 Custom installation locations?
570 Pass a path to the -to / --install-to option and prefix the path with
572 "inst#" (unless you know what you're doing)
573 $ 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 To make the custom location discoverable:
581 # Set the PERL6LIB env:
583 $ PERL6LIB="inst#/home/perl6/custom" perl6 -e "use Text::Table::Simple; say 'ok'"
584 ok
585 # or simply include it as needed
587 $ perl6 -Iinst#/home/perl6/custom -e "use Text::Table::Simple; say 'ok'"
588 ok
589 Test reporting?
591 This feature can be enabled by passing `--p6ctesters` (and having
593 "Net::HTTP" installed) or `--cpantesters` (and having
594 "Zef::CPANReporter" installed)
595perl v5.36.0 2022-07-23 zef(1)