Zef

Perl6 Module Management

Installation

Rakudobrew

To install via rakudobrew, please use the following command:

$ rakudobrew build zef

Manual

$ git clone https://github.com/ugexe/zef.git
$ cd zef
$ perl6 -Ilib bin/zef install .

USAGE

zef --help

# 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.pm 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

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 /), URNs, 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 ./Perl6-Net--HTTP`

# URL
`zef -v install git://github.com/ugexe/zef.git`
`zef -v install https://github.com/ugexe/zef/archive/master.tar.gz`

# URN
`zef install github:tony-o:CSV--Parser:0.1.2`

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.

Note: In the name portion of the URN style, a double -- indicates a ::. This is because modules can have - as part of their name. -- is probably valid too, but this makes my life a lot easier for now!

Options

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

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

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

# Install the requested modules regardless of: currently installed versions,
# test results, or failed dependency installations
--force

# 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

uninstall [*@identities]

Uninstall the specified distributions

Note: Requires a bleeding edge rakudo (not available in 6.c)

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

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<p6c>`

$ zef -v --cpan --metacpan search URI
===> Found 4 results
---------------------------------------------------------------------------
ID|From                              |Package             |Description
---------------------------------------------------------------------------
1 |Zef::Repository::LocalCache       |URI:ver('0.1.1')    |A URI impleme...
2 |Zef::Repository::Ecosystems<p6c>  |URI:ver('0.1.1')    |A URI impleme...
3 |Zef::Repository::Ecosystems<cpan> |URI:ver('0.1.1')    |A URI impleme...
4 |Zef::Repository::Ecosystems<cpan> |URI:ver('0.000.001')|A URI impleme...
5 |Zef::Repository::MetaCPAN         |URI:ver('0.1.1')    |A URI impleme...
6 |Zef::Repository::MetaCPAN         |URI:ver('0.000.001')|A URI impleme...
---------------------------------------------------------------------------

info [$identity]

View meta information of a distribution

$ zef -v info HTTP::UserAgent
- Info for: HTTP::UserAgent
- Identity: HTTP::UserAgent:ver('1.1.16'):auth('github:sergot')
- Recommended By: Zef::Repository::LocalCache
Author:  github:sergot
Description:     Web user agent
Source-url:      git://github.com/sergot/http-useragent.git
Provides: 11 modules
#       HTTP::Cookie
#       HTTP::Header
#       HTTP::Cookies
#       HTTP::Message
#       HTTP::Request
#       HTTP::Response
#       HTTP::MediaType
#       HTTP::UserAgent
#       HTTP::Header::Field
#       HTTP::Request::Common
#       HTTP::UserAgent::Common
Depends: 7 items
---------------------------------
ID|Identity           |Installed?
---------------------------------
1 |HTTP::Status       |✓
2 |File::Temp         |✓
3 |DateTime::Parse    |✓
4 |Encode             |✓
5 |MIME::Base64       |✓
6 |URI                |✓
7 |IO::Capture::Simple|✓
---------------------------------

Options

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

list [*@from]

List known available distributions

$ zef --installed list
===> Found via /home/nickl/.rakudobrew/moar-nom/install/share/perl6/site
CSV::Parser:ver('0.1.2'):auth('github:tony-o')
Zef:auth('github:ugexe')
===> Found via /home/nickl/.rakudobrew/moar-nom/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 metacpan, 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 cpan               # Only show available modules from the repository
zef list p6c                # with a name field of `cpan` in the configuration
zef list cached             # (be sure the repository is enabled in config)

Otherwise results from all enabled repositories will be returned.

Options

# Only list installed distributions
--installed

# Additionally list the modules of discovered distributions
-v

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 identities

test [*@paths]

Run tests on each distribution located at [@paths]

build [*@paths]

Run the Build.pm file located in the given [@paths]

If you want to create a build hook, put the following dependency-free boilerplate in a file named `Build.pm` at the root of your distribution:

class Builder {
    method build($dist-path) {
        # do build stuff to your module
        # which is located at $dist-path
    }

    # Only needed for panda compatability
    method isa($what) {
        return True if $what.^name eq 'Panda::Builder';
        callsame;
    }
}

Set the env variable ZEF_BUILDPM_DEBUG=1 for additional debugging information.

Note: In the future, a more appropriate hooking solution will replace this.

look [$identity]

Fetches the requested distribution and any dependencies (if requested), changes the directory to that of the fetched distribution, and then stops program execution. This allows you modify or look at the source code before manually continuing the install via `zef install .`

Note that the path to any dependencies that needed to be fetched will be set in env at PERL6LIB, so you should be able to run any build scripts, tests, or complete a manual install without having to specify their locations.

locate [$identity, $name-path, $sha1-id]

Options

# The argument is a sha1-id (otherwise assumed to be an identity or name-path)
--sha1

Lookup a locally installed module by $identity, $name-path, or $sha1-id

$ zef --sha1 locate A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
lib/Zef/CLI.pm6 => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

$ zef locate Zef::CLI
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
lib/Zef/CLI.pm6 => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

$ zef locate lib/Zef/CLI.pm6
===> From Distribution: zef:ver<*>:auth<github:ugexe>:api<>
Zef::CLI => ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31

nuke [RootDir | TempDir | StoreDir]

Deletes all paths in the specific configuration directory

nuke [site | home]

Deletes all paths that are rooted in the prefix of the matching CompUnit::Repository name

# uninstall all modules
$ zef nuke site home

Output Verbosity

You can control the logging level using the following flags:

# More/less detailed output
--error, --warn, --info (default), --verbose (-v), --debug

Plugins, Service Locator, and Configuration

See the root zef directory for config.json. Each phase module will attempt to load/use each plugin in order. More details to be made available in time, but they are fairly simple and the code itself should provide enough insight to get something done.

Plugins can be enabled and disabled from the command line. The flags to do this are based on the configuration values for each plugin. So --cpan (field `short-name`) would set "enabled" : 1. Conversely --/cpan would set "enabled" : 0

See the configuration file in resources/config.json for a little more information on how plugins are invoked.

You can see debug output related to plugins by setting the env variable ZEF_PLUGIN_DEBUG=1

FAQ

CPAN?

The functionality is mostly there. The API to search and find a specific module needs more work, but currently can execute a query and takes a matching distribution name with a matching (or newest) version. It can also download, extract, and install as well. Other than polishing up the search API access it needs metacpan itself to host Perl6 distributions.

You can enable it by setting "enabled" : 1 in the config under the Repository::Ecosystems plugin, or temporarily by passing the flag --cpan

# Search cpan in addition to other configuration defaults
$ zef -v --cpan search CSV::Parser

# Same as above, but disables the default ecosystem `p6c`
$ zef -v --cpan --/p6c search CSV::Parser

You can also use a beta version of MetaCPAN with --metacpan which uses Repository::MetaCPAN

Proxy support?

All the default fetching plugins have proxy support, but you'll need to refer to the backend program's (wget, curl, git, etc) docs. You may need to set an ENV variable, or you may need to add a command line option for that specific plugin in resources/config.json

Custom installation locations?

Pass a path to the -to / --install-to option and prefix the path with `inst#` (unless you know what you're doing)

$ zef -to="inst#/home/perl6/custom" install Text::Table::Simple
===> Searching for: Text::Table::Simple
===> Testing: Text::Table::Simple:ver('0.0.3'):auth('github:ugexe')
===> Testing [OK] for Text::Table::Simple:ver('0.0.3'):auth('github:ugexe')
===> Installing: Text::Table::Simple:ver('0.0.3'):auth('github:ugexe')

To make the custom location discoverable:

# Set the PERL6LIB env:
$ PERL6LIB="inst#/home/perl6/custom" perl6 -e "use Text::Table::Simple; say 'ok'"
ok

# or simply include it as needed
$ perl6 -Iinst#/home/perl6/custom -e "use Text::Table::Simple; say 'ok'"
ok

paizzj/zef

Zef

Installation

Rakudobrew

Manual

USAGE

More CLI

install [*@identities]

uninstall [*@identities]

update

upgrade [*@identities] BETA

search [$identity]

info [$identity]

list [*@from]

rdepends [$identity]

fetch [*@identities]

test [*@paths]

build [*@paths]

look [$identity]

locate [$identity, $name-path, $sha1-id]

nuke [RootDir | TempDir | StoreDir]

nuke [site | home]

Output Verbosity

Plugins, Service Locator, and Configuration

FAQ

CPAN?

Proxy support?

Custom installation locations?

upgrade [@identities] BETA*