=pod

=encoding utf8

=head2 Zef

Perl6 Module Management

=for HTML <a href="https://travis-ci.org/ugexe/zef"><img src="https://travis-ci.org/ugexe/zef.svg?branch=master"></a>
          <a href="https://ci.appveyor.com/project/ugexe/zef/branch/master"><img src="https://ci.appveyor.com/api/projects/status/github/ugexe/zef?branch=master&passingText=Windows%20-%20OK&failingText=Windows%20-%20FAIL&pendingText=Windows%20-%20pending&svg=true"></a>

=head1 Installation

=head4 Manual

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

=head4 Rakudobrew

To install via rakudobrew, please use the following command:

    $ rakudobrew build zef

=head1 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

=head2 More CLI

=head4 B<install> [*@identities]

Note: The install process does not install anything until all phases have completed. So, if the user requested to C<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.

[C<@identities>] can take the form of a file path (starting with B<.> or B</>), 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 B<URN> style, a double I<--> indicates a I<::>. This is because modules can have I<->
as part of their name. I<--> is probably valid too, but this makes my life a lot easier for now!

B<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

=head4 B<uninstall> [*@identities]

Uninstall the specified distributions

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

=head4 B<update>

Update the package indexes for all C<Repository> backends

Note: Some C<Repository> backends, like the default Ecosystems, have an C<auto-update> option
in C<resources/config.json> that can be enabled

=head4 B<upgrade> [*@identities] I<BETA>

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

=head4 B<search> [$identity]

How these are handled depends on the C<Repository> engine used, which by default is C<Zef::Repository::EcosystemsE<gt>p6cE<lt>>

    $ 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...
    ---------------------------------------------------------------------------

=head4 B<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|✓
    ---------------------------------

B<Options>

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

=head4 B<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).

[C<@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 matching the arguments to `list`
    zef list cached             # (be sure the repository is enabled in config)

Otherwise results from all enabled repositories will be returned.

B<Options>

    # Only list installed distributions
    --installed

    # Additionally list the modules of discovered distributions
    -v

=head4 B<rdepends> [$identity]

List available distributions that directly depend on C<$identity>

    $ zef rdepends Net::HTTP
    Minecraft-Tools:ver('0.1.0')
    LendingClub:ver('0.1.0')

=head4 B<fetch> [*@identities]

Fetches candidates for given identities

=head4 B<test> [*@paths]

Run tests on each distribution located at [C<@paths>]

=head4 B<build> [*@paths]

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

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

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

Set the env variable B<ZEF_BUILDPM_DEBUG=1> or use the I<--debug> flag for additional debugging information.

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

=head4 B<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 C<zef install .>

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

=head4 B<locate> [$identity, $name-path, $sha1-id]

B<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

=head4 B<nuke> [RootDir | TempDir | StoreDir]

Deletes all paths in the specific configuration directory

=head4 B<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

=head2 Output Verbosity

You can control the logging level using the following flags:

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

=head1 Global Configuration

=head3 Finding the configuration file

You can always see the configuration file that will be used by running:

    $ zef --help

In most cases the default configuration combined with command line options should be enough for most users.

If you are most users (e.g. not: power users, packagers, zef plugin developers) you hopefully don't care about this section! 

=head3 How the configuration file is chosen

The configuration file will be chosen at runtime from one of two (technically four) locations, and one can affect the others (this is not really a design decision and suggestions and PRs are welcome).

First, and the most precise way, is to specify the config file by passing C<--config-path="..."> to any zef command.

Second, third, and fourth we look at the path pointed to by `%?RESOURCES<config.json>`. This will point to C<$zef-dir/resources/config.json>, where C<$zef-dir> will be either:

=over 4

=item * The prefix of a rakudo installation location - This is the case if the modules loaded for bin/zef come from an installation CompUnit::Repository.

=item * The current working directory C<$*CWD> - This is the case when modules loaded for bin/zef come from a non-installation CompUnit::Repository (such as C<-I $lib>).

To understand how this is chosen, consider:

    # Modules not loaded from an ::Installation,
    # so %?RESOURCES is $*CWD/resources
    $ perl6 -Ilib bin/zef --help
    ...
    CONFIGURATION /home/user/perl6/zef/resources/config.json
    ...

    # Installed zef script loads modules from an ::Installation,
    # so %?RESOURCES is $perl6-share-dir/site/resources
    $ zef --help
    ...
    CONFIGURATION /home/user/perl6/install/share/perl6/site/resources/EE5DBAABF07682ECBE72BEE98E6B95E5D08675DE.json
    ...

=back

This config is loaded, but it is not yet the chosen config! We check that temporary config's C<%configE<lt>RootDirE<gt>> for valid json in a file named C<config.json> (i.e. C<%configE<lt>RootDirE<gt>/config.json>). This can be confusing (so it may go away or be refined - PRs welcome) but for most cases it just means C<$*HOME/.zef/config.json> will override an installed zef configuration file.

To summarize:

=over 4

=item * You can edit the C<resources/config.json> file before you install zef.

When you C<perl6 -Ilib bin/zef install .> that configuration file be be used to install zef and will also be installed with zef such that it will be the default.

=item * You can create a C<%configE<lt>RootDirE<gt>/config.json> file.

Where C<%configE<lt>RootDirE<gt>>` comes from the previously mentioned C<%?RESOURCESE<lt>config.jsonE<gt>>'s C<RootDir> field (C<$*HOME/.zef> in most cases), to allow overriding zef config behavior on a per user basis (allows setting different C<--install-to> targets for, say, a root user and a regular user). Since this new config file could have a different C<RootDir> than the default config (used to find the new one in the first place) this behavior may be changed in the future to be less confusing.

=item * You can override both of the previous entries by passing C<zef --config-path="$path" E<lt>any commandE<gt>>

=back

=head3 Configuration fields

=head4 Basic Settings

=over 4

=item * B<RootDir> - Where zef will look for a custom config.json file

=item * B<TempDir> - A staging area for items that have been fetched and need to be extracted/moved

=item * B<StoreDir> - Where zef caches distributions, package lists, etc after they've been fetched and extracted

=item * B<DefaultCUR> - This sets the default value for C<--install-to="...">. The default value of C<auto> means it will first try installing to rakudo's installation prefix, and if its not writable by the current user it will install to C<$*HOME/.perl6>. These directories are not chosen by zef - they are actually represented by the magic strings C<site> and C<home> (which, like C<auto>, are valid values despite not being paths along with C<vendor> and C<perl>)

=back

=head4 Phases / Plugins Settings

These consist of an array of hashes that describe how to instantiate some class that fulfills the appropriate interface from I<Zef.pm> (C<Repository> C<Fetcher> C<Extractor> C<Builder> C<Tester>)

The descriptions follow this format:

    {
        "short-name" : "p6c",
        "enabled" : 1,
        "module" : "Zef::Repository::Ecosystems",
        "options" : { }
    }

and are instantiated via

    ::($hash<module>).new(|($hash<options>)

=over 4

=item * B<short-name> - This adds an enable and disable flag by the same name to the CLI (e.g. C<--p6c> and C<--/p6c>) and is used when referencing which object took some action.

=item * B<enabled> - Set to 0 to skip over the object during consideration (it will never be loaded). If omitted or if the value is non 0 then it will be enabled for use.

=item * B<module> - The name of the class to instantiate. While it doesn't technically have to be a module it I<does> need to be a known namespace to C<require>.

=item * B<options> - These are passed to the objects C<new> method and may not be consistent between modules as they are free to implement their own requirements.

=back

See the configuration file in L<resources/config.json|https://github.com/ugexe/zef/blob/master/resources/config.json> for a
little more information on how plugins are invoked.

You can see debug output related to chosing and loading plugins by setting the env variable B<ZEF_PLUGIN_DEBUG=1>

=head1 FAQ

=head3 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 I<"enabled" : 1> in the config under the Repository::Ecosystems plugin, or temporarily
by passing the flag I<--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 I<--metacpan> which uses Repository::MetaCPAN

=head3 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 I<ENV> variable, or you may need to add a command line
option for that specific plugin in I<resources/config.json>

=head3 Custom installation locations?

Pass a path to the I<-to> / I<--install-to> option and prefix the path with C<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

=head3 Test reporting?

This feature can be enabled by passing `--p6ctesters` (and having C<Net::HTTP> installed) or `--cpantesters` (and having C<Zef::CPANReporter> installed)

=cut