Zef

Raku Module Management

Installation

Manual

$ git clone https://github.com/ugexe/zef.git
$ cd zef
$ raku -I. bin/zef install .

Rakubrew

To install via rakubrew, please use the following command:

$ rakubrew build-zef

USAGE

zef --help
zef --version

# install the CSV::Parser distribution
zef install CSV::Parser

# search for distribution names matching `CSV`
zef search CSV

# detailed information for a matching distribution
zef info CSV::Parser

# list all available distributions
zef list

# list reverse dependencies of an identity
zef rdepends HTTP::UserAgent

# test project in current directory
zef test .

# fetch a specific module only
zef fetch CSV::Parser

# fetch a module, then shell into its local path
zef look CSV::Parser

# smoke test modules from all repositories
zef smoke

# run Build.rakumod if one exists in given path
zef build .

# update Repository package lists
zef update

# upgrade all distributions (BETA)
zef upgrade

# upgrade specific distribution (BETA)
zef upgrade CSV::Parser

# lookup module info by name/path/sha1
zef --sha1 locate 9FA0AC28824EE9E5A9C0F99951CA870148AE378E

# launch browser to named support urls from meta data
zef browse zef bugtracker

More CLI

install [*@identities]

Note: The install process does not install anything until all phases have completed. So, if the user requested to install A, and A required module B: both would be downloaded, potentially built, tested, and installed -- but only if both passed all their tests. For example: if module A failed its tests, then module B would not be installed (even if it passed its own tests) unless forced.

[@identities] can take the form of a file path (starting with . or /), URLs, paths, or identities:

# IDENTITY
zef install CSV::Parser
zef install "CSV::Parser:auth<tony-o>:ver<0.1.2>"
zef install "CSV::Parser:ver<0.1.2>"

# PATH
zef install ./Raku-Net--HTTP

# URL
zef -v install https://github.com/ugexe/zef.git
zef -v install https://github.com/ugexe/zef/archive/main.tar.gz
zef -v install https://github.com/ugexe/zef.git@v0.1.22

# STDIN
echo "Net::HTTP" | zef install -

A request may contain any number and combination of these. Paths and URLs will be resolved first so they are available to fulfill any dependencies of other requested identities. An identity of - will treat each line of STDIN as an identity.

Options

# Install to a custom locations
--install-to=<id> # site/home/vendor/perl, or
-to=<id>          # inst#/home/some/path/custom

# Install all transitive and direct dependencies
# even if they are already installed globally (BETA)
--contained

# Load a specific Zef config file
--config-path=/some/path/config.json

# Install only the dependency chains of the requested distributions
--deps-only

# Ignore errors occuring during the corresponding phase
--force-resolve
--force-fetch
--force-extract
--force-build
--force-test
--force-install

# or set the default to all unset --force-* flags to True
--force

# Set the timeout for corresponding phases
--fetch-timeout=600
--extract-timeout=3600
--build-timeout=3600
--test-timeout=3600
--install-timeout=3600

# or set the default to all unset --*-timeout flags to 0
--timeout=0

# Number of simultaneous distributions/jobs to process for the corresponding phases
--fetch-degree=5
--test-degree=1

# Disable precompilation during installation
--/precompile-install

# Do everything except the actual installations
--dry

# Build/Test/Install each dependency serially before proceeding to Build/Test/Install the next
--serial

# Disable testing
--/test

# Disable build phase
--/build

# Disable fetching dependencies
--/depends
--/build-depends
--/test-depends

# Force a refresh for all module index indexes
--update

# Force a refresh for a specific ecosystem module index
--update=[ecosystem]

# Skip refreshing all module index indexes
--/update

# Skip refreshing for a specific ecosystem module index
--/update=[ecosystem]

ENV Options

# Number of simultaneous distributions/jobs to process for the corresponding phases (see: --[phase]-degree options)
ZEF_FETCH_DEGREE=5
ZEF_TEST_DEGREE=1

# Set the timeout for corresponding phases (see: --[phase]-timeout options)
ZEF_FETCH_TIMEOUT=600
ZEF_EXTRACT_TIMEOUT=3600
ZEF_BUILD_TIMEOUT=3600
ZEF_TEST_TIMEOUT=3600
ZEF_INSTALL_TIMEOUT=3600

# Set default --install-to target
ZEF_INSTALL_TO=site

# Path to config file (see: --config-path option)
ZEF_CONFIG_PATH=$PWD/resources/config.json

# Override DefaultCUR from the config file
ZEF_CONFIG_DEFAULTCUR=auto

# Override StoreDir from the config file
ZEF_CONFIG_STOREDIR=/home/ugexe/.config/zef/store

# Override TempDir from the config file
ZEF_CONFIG_TEMPDIR=/home/ugexe/.config/zef/temp

uninstall [*@identities]

Uninstall the specified distributions

update

Update the package indexes for all Repository backends

Note: Some Repository backends, like the default Ecosystems, have an auto-update option in resources/config.json that can be enabled. This should be the number of hours until it should auto update based on the file system last modified time of the ecosystem json file location.

upgrade [*@identities] BETA

Upgrade specified identities. If no identities are provided, zef attempts to upgrade all installed distributions.

search [$identity]

How these are handled depends on the Repository engine used, which by default is Zef::Repository::Ecosystems<fez> and Zef::Repository::Ecosystems<rea>

$ zef -v search URI
===> Found 4 results
-------------------------------------------------------------------------
ID|From                              |Package             |Description
-------------------------------------------------------------------------
2 |Zef::Repository::Ecosystems<fez> |URI:ver<0.1.1>    |A URI impleme...
3 |Zef::Repository::Ecosystems<rea> |URI:ver<0.1.1>    |A URI impleme...
4 |Zef::Repository::Ecosystems<rea> |URI:ver<0.000.001>|A URI impleme...
-------------------------------------------------------------------------

info [$identity]

View meta information of a distribution

$ zef info Distribution::Common::Remote -v
- Info for: Distribution::Common::Remote
- Identity: Distribution::Common::Remote:ver<0.1.0>:auth<github:ugexe>:api<0>
- Recommended By: Zef::Repository::Ecosystems<rea>
- Installed: No
Description:     Create an installable Distribution from common remote sources
License:     Artistic-2.0
Source-url:  https://raw.githubusercontent.com/raku/REA/main/archive/D/Distribution%3A%3ACommon%3A%3ARemote/Distribution%3A%3ACommon%3A%3ARemote%3Aver%3C0.1.0%3E%3Aauth%3Cgithub%3Augexe%3E.tar.gz
Provides: 2 modules
----------------------------------------------------------------------------------
Module                              |Path-Name
----------------------------------------------------------------------------------
Distribution::IO::Remote::Github    |lib/Distribution/IO/Remote/Github.rakumod
Distribution::Common::Remote::Github|lib/Distribution/Common/Remote/Github.rakumod
----------------------------------------------------------------------------------
Support:
#   bugtracker: https://github.com/ugexe/Raku-Distribution--Common--Remote/issues
#   source: https://github.com/ugexe/Raku-Distribution--Common--Remote.git
Depends: 2 items
----------------------------------
ID|Identity            |Installed?
----------------------------------
1 |Distribution::Common|✓
2 |Test                |✓
----------------------------------

Options

# Extra details (eg, list dependencies and which ones are installed)
-v

list [*@from]

List known available distributions

$ zef --installed list
===> Found via /home/foo/.rakubrew/moar/install/share/perl6/site
CSV::Parser:ver<0.1.2>:auth<github:tony-o>
Zef:auth<github:ugexe>
===> Found via /home/foo/.rakubrew/moar/install/share/perl6
CORE:ver<6.c>:auth<perl>

Note that not every Repository may provide such a list, and such lists may only be a subset. For example: We may not be able to get a list of every distribution on cpan, but we *can* get the $x most recent additions (we use 100 for now).

[@from] allows you to show results from specific repositories only:

zef --installed list perl   # Only list modules installed by rakudo itself

zef list fez               # Only show available modules from the repository
zef list rea               # with a name field matching the arguments to `list`
zef list p6c               # (be sure the repository is enabled in config)
zef list cpan --cpan       # (or enabled via a cli flag)

Otherwise results from all enabled repositories will be returned.

Options

# Only list installed distributions
--installed

# Additionally list the modules of discovered distributions
-v

depends [$identity]

List direct and transitive dependencies to the first successful build graph for $identity

$ zef depends Cro::SSL
Cro::Core:ver<0.7>
IO::Socket::Async::SSL:ver<0.3>
OpenSSL:ver<0.1.14>:auth<github:sergot>

rdepends [$identity]

List available distributions that directly depend on $identity

$ zef rdepends Net::HTTP
Minecraft-Tools:ver<0.1.0>
LendingClub:ver<0.1.0>

fetch [*@identities]

Fetches candidates for given identi