1zef(1) User Contributed Perl Documentation zef(1)
2 Zef
6 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 # or set the default to all unset --*-timeout flags to 0
135 --timeout=0
136 # Do everything except the actual installations
138 --dry
139 # Build/Test/Install each dependency serially before proceeding to Build/Test/Install the next
141 --serial
142 # Disable testing
144 --/test
145 # Disable build phase
147 --/build
148 # Disable fetching dependencies
150 --/depends
151 --/build-depends
152 --/test-depends
153 uninstall [*@identities]
155 Uninstall the specified distributions
157 Note: Requires a bleeding edge rakudo (not available in 6.c)
159 update
161 Update the package indexes for all "Repository" backends
163 Note: Some "Repository" backends, like the default Ecosystems, have an
165 "auto-update" option in "resources/config.json" that can be enabled.
166 This should be the number of hours until it should auto update based on
167 the file system last modified time of the ecosystem json file location.
168 upgrade [*@identities] BETA
170 Upgrade specified identities. If no identities are provided, zef
172 attempts to upgrade all installed distributions.
173 search [$identity]
175 How these are handled depends on the "Repository" engine used, which by
177 default is "Zef::Repository::Ecosystems>p6c<"
178 $ zef -v --cpan --metacpan search URI
180 ===> Found 4 results
181 -------------------------------------------------------------------------
182 ID|From |Package |Description
183 -------------------------------------------------------------------------
184 1 |Zef::Repository::LocalCache |URI:ver<0.1.1> |A URI impleme...
185 2 |Zef::Repository::Ecosystems<p6c> |URI:ver<0.1.1> |A URI impleme...
186 3 |Zef::Repository::Ecosystems<cpan> |URI:ver<0.1.1> |A URI impleme...
187 4 |Zef::Repository::Ecosystems<cpan> |URI:ver<0.000.001>|A URI impleme...
188 5 |Zef::Repository::MetaCPAN |URI:ver<0.1.1> |A URI impleme...
189 6 |Zef::Repository::MetaCPAN |URI:ver<0.000.001>|A URI impleme...
190 -------------------------------------------------------------------------
191 info [$identity]
193 View meta information of a distribution
195 $ zef -v info HTTP::UserAgent
197 - Info for: HTTP::UserAgent
198 - Identity: HTTP::UserAgent:ver<1.1.16>:auth<github:sergot>
199 - Recommended By: Zef::Repository::LocalCache
200 Author: github:sergot
201 Description: Web user agent
202 Source-url: git://github.com/sergot/http-useragent.git
203 Provides: 11 modules
204 # HTTP::Cookie
205 # HTTP::Header
206 # HTTP::Cookies
207 # HTTP::Message
208 # HTTP::Request
209 # HTTP::Response
210 # HTTP::MediaType
211 # HTTP::UserAgent
212 # HTTP::Header::Field
213 # HTTP::Request::Common
214 # HTTP::UserAgent::Common
215 Depends: 7 items
216 ---------------------------------
217 ID|Identity |Installed?
218 ---------------------------------
219 1 |HTTP::Status |X
220 2 |File::Temp |X
221 3 |DateTime::Parse |X
222 4 |Encode |X
223 5 |MIME::Base64 |X
224 6 |URI |X
225 7 |IO::Capture::Simple|X
226 ---------------------------------
227 Options
229 # Extra details (eg, list dependencies and which ones are installed)
231 -v
232 list [*@from]
234 List known available distributions
236 $ zef --installed list
238 ===> Found via /home/nickl/.rakudobrew/moar-master/install/share/perl6/site
239 CSV::Parser:ver<0.1.2>:auth<github:tony-o>
240 Zef:auth<github:ugexe>
241 ===> Found via /home/nickl/.rakudobrew/moar-master/install/share/perl6
242 CORE:ver<6.c>:auth<perl>
243 Note that not every Repository may provide such a list, and such lists
245 may only be a subset. For example: We may not be able to get a list of
246 every distribution on metacpan, but we *can* get the $x most recent
247 additions (we use 100 for now).
248 [@from] allows you to show results from specific repositories only:
250 zef --installed list perl # Only list modules installed by rakudo itself
252 zef list cpan # Only show available modules from the repository
254 zef list p6c # with a name field matching the arguments to `list`
255 zef list cached # (be sure the repository is enabled in config)
256 Otherwise results from all enabled repositories will be returned.
258 Options
260 # Only list installed distributions
262 --installed
263 # Additionally list the modules of discovered distributions
265 -v
266 depends [$identity]
268 List direct and transitive dependencies to the first successful build
270 graph for $identity
271 $ zef depends Cro::SSL
273 Cro::Core:ver<0.7>
274 IO::Socket::Async::SSL:ver<0.3>
275 OpenSSL:ver<0.1.14>:auth<github:sergot>
276 rdepends [$identity]
278 List available distributions that directly depend on $identity
280 $ zef rdepends Net::HTTP
282 Minecraft-Tools:ver<0.1.0>
283 LendingClub:ver<0.1.0>
284 fetch [*@identities]
286 Fetches candidates for given identities
288 test [*@paths]
290 Run tests on each distribution located at [@paths]
292 build [*@paths]
294 Run the Build.pm file located in the given [@paths]
296 If you want to create a build hook, put the following dependency-free
298 boilerplate in a file named "Build.pm" at the root of your
299 distribution:
300 class Build {
302 method build($dist-path) {
303 # do build stuff to your module
304 # which is located at $dist-path
305 }
306 }
307 Set the env variable ZEF_BUILDPM_DEBUG=1 or use the --debug flag for
309 additional debugging information.
310 Note: In the future, a more appropriate hooking solution will replace
312 this.
313 look [$identity]
315 Fetches the requested distribution and any dependencies (if requested),
317 changes the directory to that of the fetched distribution, and then
318 stops program execution. This allows you modify or look at the source
319 code before manually continuing the install via "zef install ."
320 Note that the path to any dependencies that needed to be fetched will
322 be set in env at PERL6LIB, so you should be able to run any build
323 scripts, tests, or complete a manual install without having to specify
324 their locations.
325 browse $identity [bugtracker | homepage | source]
327 Options
329 # disables launching a browser window (just shows url)
331 --/open
332 Output the url and launch a browser to open it.
334 # also opens browser
336 $ zef browse Net::HTTP bugtracker
337 https://github.com/ugexe/Perl6-Net--HTTP/issues
338 # only outputs the url
340 $ zef browse Net::HTTP bugtracker --/open
341 https://github.com/ugexe/Perl6-Net--HTTP/issues
342 locate [$identity, $name-path, $sha1-id]
344 Options
346 # The argument is a sha1-id (otherwise assumed to be an identity or name-path)
348 --sha1
349 Lookup a locally installed module by $identity, $name-path, or $sha1-id
351 $ zef --sha1 locate A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
353 ===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
354 lib/Zef/CLI.pm6 => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
355 $ zef locate Zef::CLI
357 ===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
358 lib/Zef/CLI.pm6 => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
359 $ zef locate lib/Zef/CLI.pm6
361 ===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
362 Zef::CLI => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
363 nuke [RootDir | TempDir | StoreDir]
365 Deletes all paths in the specific configuration directory
367 nuke [site | home]
369 Deletes all paths that are rooted in the prefix of the matching
371 CompUnit::Repository name
372 # uninstall all modules
374 $ zef nuke site home
375 Output Verbosity
377 You can control the logging level using the following flags:
378 # More/less detailed output
380 --error, --warn, --info (default), --verbose (-v), --debug
381
383 Finding the configuration file
384 You can always see the configuration file that will be used by running:
386 $ zef --help
388 In most cases the default configuration combined with command line
390 options should be enough for most users.
391 If you are most users (e.g. not: power users, packagers, zef plugin
393 developers) you hopefully don't care about this section!
394 How the configuration file is chosen
396 The configuration file will be chosen at runtime from one of two
398 (technically four) locations, and one can affect the others (this is
399 not really a design decision and suggestions and PRs are welcome).
400 First, and the most precise way, is to specify the config file by
402 passing "--config-path="..."" to any zef command.
403 Second, third, and fourth we look at the path pointed to by
405 "%?RESOURCES<config.json>". This will point to
406 "$zef-dir/resources/config.json", where "$zef-dir" will be either:
407 · The prefix of a common configuration directory, such as
409 $XDG_CONFIG_HOME or "$HOME/.config".
410 · The prefix of a rakudo installation location - This is the case if
412 the modules loaded for bin/zef come from an installation
413 CompUnit::Repository.
414 · The current working directory $*CWD - This is the case when modules
416 loaded for bin/zef come from a non-installation
417 CompUnit::Repository (such as "-I $dist-path").
418 To understand how this is chosen, consider:
420 # Modules not loaded from an ::Installation,
422 # so %?RESOURCES is $*CWD/resources
423 $ perl6 -I. bin/zef --help
424 ...
425 CONFIGURATION /home/user/perl6/zef/resources/config.json
426 ...
427 # Installed zef script loads modules from an ::Installation,
429 # so %?RESOURCES is $perl6-share-dir/site/resources
430 $ zef --help
431 ...
432 CONFIGURATION /home/user/perl6/install/share/perl6/site/resources/EE5DBAABF07682ECBE72BEE98E6B95E5D08675DE.json
433 ...
434 This config is loaded, but it is not yet the chosen config! We check
436 that temporary config's "%config<RootDir>" for valid json in a file
437 named "config.json" (i.e. "%config<RootDir>/config.json"). This can be
438 confusing (so it may go away or be refined - PRs welcome) but for most
439 cases it just means "$*HOME/.zef/config.json" will override an
440 installed zef configuration file.
441 To summarize:
443 · You can edit the "resources/config.json" file before you install
445 zef.
446 When you "perl6 -I. bin/zef install ." that configuration file be
448 be used to install zef and will also be installed with zef such
449 that it will be the default.
450 · You can create a "%config<RootDir>/config.json" file.
452 Where "%config<RootDir>" comes from the previously mentioned
454 "%?RESOURCES<config.json>"'s "RootDir" field ("$*HOME/.zef" in most
455 cases), to allow overriding zef config behavior on a per user basis
456 (allows setting different "--install-to" targets for, say, a root
457 user and a regular user). Since this new config file could have a
458 different "RootDir" than the default config (used to find the new
459 one in the first place) this behavior may be changed in the future
460 to be less confusing.
461 · You can override both of the previous entries by passing "zef
463 --config-path="$path" <any command>"
464 Configuration fields
466 Basic Settings
468 · RootDir - Where zef will look for a custom config.json file
470 · TempDir - A staging area for items that have been fetched and need
472 to be extracted/moved
473 · StoreDir - Where zef caches distributions, package lists, etc after
475 they've been fetched and extracted
476 · DefaultCUR - This sets the default value for "--install-to="..."".
478 The default value of "auto" means it will first try installing to
479 rakudo's installation prefix, and if its not writable by the
480 current user it will install to "$*HOME/.perl6". These directories
481 are not chosen by zef - they are actually represented by the magic
482 strings "site" and "home" (which, like "auto", are valid values
483 despite not being paths along with "vendor" and "perl")
484 Phases / Plugins Settings
486 These consist of an array of hashes that describe how to instantiate
488 some class that fulfills the appropriate interface from Zef.pm
489 ("Repository" "Fetcher" "Extractor" "Builder" "Tester")
490 The descriptions follow this format:
492 {
494 "short-name" : "p6c",
495 "enabled" : 1,
496 "module" : "Zef::Repository::Ecosystems",
497 "options" : { }
498 }
499 and are instantiated via
501 ::($hash<module>).new(|($hash<options>)
503 · short-name - This adds an enable and disable flag by the same name
505 to the CLI (e.g. "--p6c" and "--/p6c") and is used when referencing
506 which object took some action.
507 · enabled - Set to 0 to skip over the object during consideration (it
509 will never be loaded). If omitted or if the value is non 0 then it
510 will be enabled for use.
511 · module - The name of the class to instantiate. While it doesn't
513 technically have to be a module it does need to be a known
514 namespace to "require".
515 · options - These are passed to the objects "new" method and may not
517 be consistent between modules as they are free to implement their
518 own requirements.
519 See the configuration file in resources/config.json
521 <https://github.com/ugexe/zef/blob/master/resources/config.json> for a
522 little more information on how plugins are invoked.
523 You can see debug output related to chosing and loading plugins by
525 setting the env variable ZEF_PLUGIN_DEBUG=1
526
528 CPAN?
529 CPAN is now used as a default (alongside the familiar p6c "ecosystem").
531 # Explicitly enable cpan (now defaults to the same as `zef search zef`)
533 $ zef --cpan search Inline::Perl5
534 You can also use a beta version of MetaCPAN with --metacpan which uses
536 Repository::MetaCPAN
537 $ zef --metacpan search Inline::Perl5
539 Proxy support?
541 All the default fetching plugins have proxy support, but you'll need to
543 refer to the backend program's (wget, curl, git, etc) docs. You may
544 need to set an ENV variable, or you may need to add a command line
545 option for that specific plugin in resources/config.json
546 Custom installation locations?
548 Pass a path to the -to / --install-to option and prefix the path with
550 "inst#" (unless you know what you're doing)
551 $ zef -to="inst#/home/perl6/custom" install Text::Table::Simple
553 ===> Searching for: Text::Table::Simple
554 ===> Testing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
555 ===> Testing [OK] for Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
556 ===> Installing: Text::Table::Simple:ver<0.0.3>:auth<github:ugexe>
557 To make the custom location discoverable:
559 # Set the PERL6LIB env:
561 $ PERL6LIB="inst#/home/perl6/custom" perl6 -e "use Text::Table::Simple; say 'ok'"
562 ok
563 # or simply include it as needed
565 $ perl6 -Iinst#/home/perl6/custom -e "use Text::Table::Simple; say 'ok'"
566 ok
567 Test reporting?
569 This feature can be enabled by passing `--p6ctesters` (and having
571 "Net::HTTP" installed) or `--cpantesters` (and having
572 "Zef::CPANReporter" installed)
573perl v5.28.1 2019-03-02 zef(1)