zef1

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!

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 --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 $zef-dir/resources/config.json, where $zef-dir will be either:

•

The prefix of a common configuration directory, such as $XDG_CONFIG_HOME or $HOME/.config.

•

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

•

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

To understand how this is chosen, consider:

  # Modules not loaded from an ::Installation,
  # so %?RESOURCES is $*CWD/resources
  $ raku -I. bin/zef --help
  ...
  CONFIGURATION /home/user/raku/zef/resources/config.json
  ...
  # Installed zef script loads modules from an ::Installation,
  # so %?RESOURCES is $raku-share-dir/site/resources
  $ zef --help
  ...
  CONFIGURATION /home/user/raku/install/share/perl6/site/resources/EE5DBAABF07682ECBE72BEE98E6B95E5D08675DE.json
  ...

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

To summarize:

•

You can edit the resources/config.json file before you install zef.

When you raku -I. 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.

•

You can create a %config<RootDir>/config.json file.

Where %config<RootDir> comes from the previously mentioned %?RESOURCES<config.json>’s RootDir field ($*HOME/.zef in most cases), to allow overriding zef config behavior on a per user basis (allows setting different --install-to targets for, say, a root user and a regular user). Since this new config file could have a different 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.

•

You can override both of the previous entries by passing zef --config-path="$path" <any command>

Configuration fields

Basic Settings

•

RootDir - Where zef will look for a custom config.json file

•

TempDir - A staging area for items that have been fetched and need to be extracted/moved

•

StoreDir - Where zef caches distributions, package lists, etc after they’ve been fetched and extracted

•

DefaultCUR - This sets the default value for --install-to="...". The default value of 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 $*HOME/.raku. These directories are not chosen by zef - they are actually represented by the magic strings site and home (which, like auto, are valid values despite not being paths along with vendor and perl)

Phases / Plugins Settings

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

The descriptions follow this format:

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

and are instantiated via

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

•

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

•

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.

•

module - The name of the class to instantiate. While it doesn’t technically have to be a module it does need to be a known namespace to require.

•

options - These are passed to the objects new method and may not be consistent between modules as they are free to implement their own requirements.

See the configuration file in resources/config.json ⟨https://github.com/ugexe/zef/blob/master/resources/config.json⟩\c 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 ZEF_PLUGIN_DEBUG=1

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/raku/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 RAKULIB env:
$ RAKULIB="inst#/home/raku/custom" raku -e "use Text::Table::Simple; say 'ok'"
ok
# or simply include it as needed
$ raku -Iinst#/home/raku/custom -e "use Text::Table::Simple; say 'ok'"
ok