{"id":13734224,"url":"https://github.com/ugexe/zef","last_synced_at":"2026-05-25T01:03:25.960Z","repository":{"id":9300593,"uuid":"11138330","full_name":"ugexe/zef","owner":"ugexe","description":"Raku Module Management","archived":false,"fork":false,"pushed_at":"2025-03-01T01:05:23.000Z","size":2478,"stargazers_count":213,"open_issues_count":47,"forks_count":45,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-04-12T14:17:10.324Z","etag":null,"topics":["hacktoberfest","meta-search","module-installer","package-manager","perl6","raku","toolchain"],"latest_commit_sha":null,"homepage":"","language":"Raku","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"artistic-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ugexe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["ugexe"]}},"created_at":"2013-07-03T00:25:36.000Z","updated_at":"2025-03-24T01:41:32.000Z","dependencies_parsed_at":"2023-10-20T03:48:56.127Z","dependency_job_id":"29d0087a-8d18-413d-85d9-25c770c22b26","html_url":"https://github.com/ugexe/zef","commit_stats":{"total_commits":1697,"total_committers":32,"mean_commits":53.03125,"dds":"0.44902769593400116","last_synced_commit":"0e4e9de51c9d2ad940810a9ed3df508b26821dfa"},"previous_names":[],"tags_count":145,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugexe%2Fzef","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugexe%2Fzef/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugexe%2Fzef/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ugexe%2Fzef/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ugexe","download_url":"https://codeload.github.com/ugexe/zef/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553958,"owners_count":22090417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","meta-search","module-installer","package-manager","perl6","raku","toolchain"],"created_at":"2024-08-03T03:00:53.653Z","updated_at":"2026-05-25T01:03:25.954Z","avatar_url":"https://github.com/ugexe.png","language":"Raku","funding_links":["https://github.com/sponsors/ugexe"],"categories":["Modules"],"sub_categories":["Installation"],"readme":"## Zef\n\nRaku Module Management\n\n# Installation\n\n#### Manual\n\n    $ git clone https://github.com/ugexe/zef.git\n    $ cd zef\n    $ raku -I. bin/zef install .\n\n#### Rakubrew\n\nTo install via rakubrew, please use the following command:\n\n    $ rakubrew build-zef\n\n# USAGE\n\n    zef --help\n    zef --version\n\n    # install the CSV::Parser distribution\n    zef install CSV::Parser\n\n    # search for distribution names matching `CSV`\n    zef search CSV\n\n    # detailed information for a matching distribution\n    zef info CSV::Parser\n\n    # list all available distributions\n    zef list\n\n    # list reverse dependencies of an identity\n    zef rdepends HTTP::UserAgent\n\n    # test project in current directory\n    zef test .\n\n    # fetch a specific module only\n    zef fetch CSV::Parser\n\n    # fetch a module, then shell into its local path\n    zef look CSV::Parser\n\n    # smoke test modules from all repositories\n    zef smoke\n\n    # run Build.rakumod if one exists in given path\n    zef build .\n\n    # update Repository package lists\n    zef update\n\n    # upgrade all distributions (BETA)\n    zef upgrade\n\n    # upgrade specific distribution (BETA)\n    zef upgrade CSV::Parser\n\n    # lookup module info by name/path/sha1\n    zef --sha1 locate 9FA0AC28824EE9E5A9C0F99951CA870148AE378E\n\n    # launch browser to named support urls from meta data\n    zef browse zef bugtracker\n\n## More CLI\n\n#### **install** \\[\\*@identities\\]\n\nNote: The install process does not install anything until all phases have completed. So, if the user requested to\n`install A`, and A required module B: both would be downloaded, potentially built, tested, and installed -- but only\nif both passed all their tests. For example: if module A failed its tests, then module B would not be installed\n(even if it passed its own tests) unless forced.\n\n\\[`@identities`\\] can take the form of a file path (starting with **.** or **/**), URLs, paths, or identities:\n\n    # IDENTITY\n    zef install CSV::Parser\n    zef install \"CSV::Parser:auth\u003ctony-o\u003e:ver\u003c0.1.2\u003e\"\n    zef install \"CSV::Parser:ver\u003c0.1.2\u003e\"\n\n    # PATH\n    zef install ./Raku-Net--HTTP\n\n    # URL\n    zef -v install https://github.com/ugexe/zef.git\n    zef -v install https://github.com/ugexe/zef/archive/main.tar.gz\n    zef -v install https://github.com/ugexe/zef.git@v0.1.22\n\n    # STDIN\n    echo \"Net::HTTP\" | zef install -\n\nA request may contain any number and combination of these. Paths and URLs will be resolved first so they are available\nto fulfill any dependencies of other requested identities. An identity of `-` will treat each line of STDIN as an\nidentity.\n\n**Options**\n\n    # Install to a custom locations\n    --install-to=\u003cid\u003e # site/home/vendor/perl, or\n    -to=\u003cid\u003e          # inst#/home/some/path/custom\n\n    # Install all transitive and direct dependencies\n    # even if they are already installed globally (BETA)\n    --contained\n\n    # Load a specific Zef config file\n    --config-path=/some/path/config.json\n\n    # Install only the dependency chains of the requested distributions\n    --deps-only\n\n    # Ignore errors occuring during the corresponding phase\n    --force-resolve\n    --force-fetch\n    --force-extract\n    --force-build\n    --force-test\n    --force-install\n\n    # or set the default to all unset --force-* flags to True\n    --force\n\n    # Set the timeout for corresponding phases\n    --fetch-timeout=600\n    --extract-timeout=3600\n    --build-timeout=3600\n    --test-timeout=3600\n    --install-timeout=3600\n\n    # or set the default to all unset --*-timeout flags to 0\n    --timeout=0\n\n    # Number of simultaneous distributions/jobs to process for the corresponding phases\n    --fetch-degree=5\n    --test-degree=1\n\n    # Disable precompilation during installation\n    --/precompile-install\n\n    # Do everything except the actual installations\n    --dry\n\n    # Build/Test/Install each dependency serially before proceeding to Build/Test/Install the next\n    --serial\n\n    # Disable testing\n    --/test\n\n    # Disable build phase\n    --/build\n\n    # Disable fetching dependencies\n    --/depends\n    --/build-depends\n    --/test-depends\n\n    # Force a refresh for all module index indexes\n    --update\n\n    # Force a refresh for a specific ecosystem module index\n    --update=[ecosystem]\n\n    # Skip refreshing all module index indexes\n    --/update\n\n    # Skip refreshing for a specific ecosystem module index\n    --/update=[ecosystem]\n\n**ENV Options**\n\n    # Number of simultaneous distributions/jobs to process for the corresponding phases (see: --[phase]-degree options)\n    ZEF_FETCH_DEGREE=5\n    ZEF_TEST_DEGREE=1\n\n    # Set the timeout for corresponding phases (see: --[phase]-timeout options)\n    ZEF_FETCH_TIMEOUT=600\n    ZEF_EXTRACT_TIMEOUT=3600\n    ZEF_BUILD_TIMEOUT=3600\n    ZEF_TEST_TIMEOUT=3600\n    ZEF_INSTALL_TIMEOUT=3600\n\n    # Set default --install-to target\n    ZEF_INSTALL_TO=site\n\n    # Path to config file (see: --config-path option)\n    ZEF_CONFIG_PATH=$PWD/resources/config.json\n\n    # Override DefaultCUR from the config file\n    ZEF_CONFIG_DEFAULTCUR=auto\n\n    # Override StoreDir from the config file\n    ZEF_CONFIG_STOREDIR=/home/ugexe/.config/zef/store\n\n    # Override TempDir from the config file\n    ZEF_CONFIG_TEMPDIR=/home/ugexe/.config/zef/temp\n\n#### **uninstall** \\[\\*@identities\\]\n\nUninstall the specified distributions\n\n#### **update**\n\nUpdate the package indexes for all `Repository` backends\n\nNote: Some `Repository` backends, like the default Ecosystems, have an `auto-update` option\nin `resources/config.json` that can be enabled. This should be the number of hours until it should\nauto update based on the file system last modified time of the ecosystem json file location.\n\n#### **upgrade** \\[\\*@identities\\] _BETA_\n\nUpgrade specified identities. If no identities are provided, zef attempts to upgrade all installed distributions.\n\n#### **search** \\[$identity\\]\n\nHow these are handled depends on the `Repository` engine used, which by default is `Zef::Repository::Ecosystems\u003cfez\u003e` and `Zef::Repository::Ecosystems\u003crea\u003e`\n\n    $ zef -v search URI\n    ===\u003e Found 4 results\n    -------------------------------------------------------------------------\n    ID|From                              |Package             |Description\n    -------------------------------------------------------------------------\n    2 |Zef::Repository::Ecosystems\u003cfez\u003e |URI:ver\u003c0.1.1\u003e    |A URI impleme...\n    3 |Zef::Repository::Ecosystems\u003crea\u003e |URI:ver\u003c0.1.1\u003e    |A URI impleme...\n    4 |Zef::Repository::Ecosystems\u003crea\u003e |URI:ver\u003c0.000.001\u003e|A URI impleme...\n    -------------------------------------------------------------------------\n\n#### **info** \\[$identity\\]\n\nView meta information of a distribution\n\n    $ zef info Distribution::Common::Remote -v\n    - Info for: Distribution::Common::Remote\n    - Identity: Distribution::Common::Remote:ver\u003c0.1.0\u003e:auth\u003cgithub:ugexe\u003e:api\u003c0\u003e\n    - Recommended By: Zef::Repository::Ecosystems\u003crea\u003e\n    - Installed: No\n    Description:     Create an installable Distribution from common remote sources\n    License:     Artistic-2.0\n    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\n    Provides: 2 modules\n    ----------------------------------------------------------------------------------\n    Module                              |Path-Name\n    ----------------------------------------------------------------------------------\n    Distribution::IO::Remote::Github    |lib/Distribution/IO/Remote/Github.rakumod\n    Distribution::Common::Remote::Github|lib/Distribution/Common/Remote/Github.rakumod\n    ----------------------------------------------------------------------------------\n    Support:\n    #   bugtracker: https://github.com/ugexe/Raku-Distribution--Common--Remote/issues\n    #   source: https://github.com/ugexe/Raku-Distribution--Common--Remote.git\n    Depends: 2 items\n    ----------------------------------\n    ID|Identity            |Installed?\n    ----------------------------------\n    1 |Distribution::Common|✓\n    2 |Test                |✓\n    ----------------------------------\n\n**Options**\n\n    # Extra details (eg, list dependencies and which ones are installed)\n    -v\n\n#### **list** \\[\\*@from\\]\n\nList known available distributions\n\n    $ zef --installed list\n    ===\u003e Found via /home/foo/.rakubrew/moar/install/share/perl6/site\n    CSV::Parser:ver\u003c0.1.2\u003e:auth\u003cgithub:tony-o\u003e\n    Zef:auth\u003cgithub:ugexe\u003e\n    ===\u003e Found via /home/foo/.rakubrew/moar/install/share/perl6\n    CORE:ver\u003c6.c\u003e:auth\u003cperl\u003e\n\nNote that not every Repository may provide such a list, and such lists may only\nbe a subset. For example: We may not be able to get a list of every distribution\non cpan, but we \\*can\\* get the $x most recent additions (we use 100 for now).\n\n\\[`@from`\\] allows you to show results from specific repositories only:\n\n    zef --installed list perl   # Only list modules installed by rakudo itself\n\n    zef list fez               # Only show available modules from the repository\n    zef list rea               # with a name field matching the arguments to `list`\n    zef list p6c               # (be sure the repository is enabled in config)\n    zef list cpan --cpan       # (or enabled via a cli flag)\n\nOtherwise results from all enabled repositories will be returned.\n\n**Options**\n\n    # Only list installed distributions\n    --installed\n\n    # Additionally list the modules of discovered distributions\n    -v\n\n#### **depends** \\[$identity\\]\n\nList direct and transitive dependencies to the first successful build graph for `$identity`\n\n    $ zef depends Cro::SSL\n    Cro::Core:ver\u003c0.7\u003e\n    IO::Socket::Async::SSL:ver\u003c0.3\u003e\n    OpenSSL:ver\u003c0.1.14\u003e:auth\u003cgithub:sergot\u003e\n\n#### **rdepends** \\[$identity\\]\n\nList available distributions that directly depend on `$identity`\n\n    $ zef rdepends Net::HTTP\n    Minecraft-Tools:ver\u003c0.1.0\u003e\n    LendingClub:ver\u003c0.1.0\u003e\n\n#### **fetch** \\[\\*@identities\\]\n\nFetches candidates for given identities\n\n#### **test** \\[\\*@paths\\]\n\nRun tests on each distribution located at \\[`@paths`\\]\n\n#### **build** \\[\\*@paths\\]\n\nRun the build step for each distribution located in the given \\[`@paths`\\]\n\nSet the env variable **ZEF\\_BUILDPM\\_DEBUG=1** or use the _--debug_ flag for additional debugging information.\n\nIf you want to create a build hook you have two options:\n\n* **PREFERRED** List a builder module that can do what you need in the `builder` field of the META6.json file. For instace many cases of the I-need-to-run-make pattern can list `\"builder\":\"Distribution::Builder::MakeFromJSON\"` and supply some extra info to the `\"build\"` field (a non-standard `Distribution::Builder::MakeFromJSON` specific field). For a more concrete example check out how `Inline::Perl5` [uses the builder field](https://github.com/niner/Inline-Perl5/blob/2e7b99fb03d182d15df4f88818d835b151117786/META6.json#L58-L68). Remember to add any such module to your `build-depends` though! See `Zef::Service::Shell::DistributionBuilder` for more information.\n\n* **DEPRECATED** (_but probably never going away_) Put the following dependency-free boilerplate in a file named `Build.rakumod` at the root of your distribution:\n\n    ```\n    class Build {\n        method build($dist-path) {\n            # do build stuff to your module\n            # which is located at $dist-path\n        }\n    }\n    ```\n\n#### **look** \\[$identity\\]\n\nFetches the requested distribution and any dependencies (if requested), changes the directory to that of the fetched\ndistribution, and then stops program execution. This allows you modify or look at the source code before manually\ncontinuing the install via `zef install .`\n\nNote that the path to any dependencies that needed to be fetched will be set in env at **RAKULIB**, so you should\nbe able to run any build scripts, tests, or complete a manual install without having to specify their locations.\n\n#### **browse** $identity \\[bugtracker | homepage | source\\]\n\n**Options**\n\n    # disables launching a browser window (just shows url)\n    --/open\n\nOutput the url and launch a browser to open it.\n\n    # also opens browser\n    $ zef browse Net::HTTP bugtracker\n    https://github.com/ugexe/Raku-Net--HTTP/issues\n\n    # only outputs the url\n    $ zef browse Net::HTTP bugtracker --/open\n    https://github.com/ugexe/Raku-Net--HTTP/issues\n\n#### **locate** \\[$identity, $name-path, $sha1-id\\]\n\n**Options**\n\n    # The argument is a sha1-id (otherwise assumed to be an identity or name-path)\n    --sha1\n\nLookup a locally installed module by $identity, $name-path, or $sha1-id\n\n    $ zef --sha1 locate A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31\n    ===\u003e From Distribution: zef:ver\u003c*\u003e:auth\u003cgithub:ugexe\u003e:api\u003c\u003e\n    lib/Zef/CLI.rakumod =\u003e ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31\n\n    $ zef locate Zef::CLI\n    ===\u003e From Distribution: zef:ver\u003c*\u003e:auth\u003cgithub:ugexe\u003e:api\u003c\u003e\n    lib/Zef/CLI.rakumod =\u003e ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31\n\n    $ zef locate lib/Zef/CLI.rakumod\n    ===\u003e From Distribution: zef:ver\u003c*\u003e:auth\u003cgithub:ugexe\u003e:api\u003c\u003e\n    Zef::CLI =\u003e ~/rakudo/install/share/perl6/site/sources/A9948E7371E0EB9AFDF1EEEB07B52A1B75537C31\n\n#### **nuke** \\[StoreDir | TempDir\\]\n\nDeletes all paths in the specific configuration directory\n\n#### **nuke** \\[site | home\\]\n\nDeletes all paths that are rooted in the prefix of the matching CompUnit::Repository name\n\n    # uninstall all modules\n    $ zef nuke site home\n\n## Output Verbosity\n\nYou can control the logging level using the following flags:\n\n    # More/less detailed output\n    --error, --warn, --info (default), --verbose (-v), --debug\n\n# Global Configuration\n\n### Finding the configuration file\n\nYou can always see the configuration file that will be used by running:\n\n    $ zef --help\n\nIn most cases the default configuration combined with command line options should be enough for most users.\n\nIf you are most users (e.g. not: power users, packagers, zef plugin developers) you hopefully don't care about this section! \n\n### How the configuration file is chosen\n\nThe configuration file will be chosen at runtime from one of two (technically four) locations.\n\nFirst, and the most precise way, is to specify the config file by passing `--config-path=\"...\"` to any zef command.\n\nSecond, third, and fourth we look at the path pointed to by `%?RESOURCES\u003cconfig.json\u003e`. This will point to `$zef-dir/resources/config.json`, where `$zef-dir` will be either:\n\n- The prefix of a common configuration directory, such as `$XDG_CONFIG_HOME`  or `$HOME/.config`.\n- The prefix of a rakudo installation location - This is the case if the modules loaded for bin/zef come from an installation CompUnit::Repository.\n- 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`).\n\n    To understand how this is chosen, consider:\n\n        # Modules not loaded from an ::Installation,\n        # so %?RESOURCES is $*CWD/resources\n        $ raku -I. bin/zef --help\n        ...\n        CONFIGURATION /home/user/raku/zef/resources/config.json\n        ...\n\n        # Installed zef script loads modules from an ::Installation,\n        # so %?RESOURCES is $raku-share-dir/site/resources\n        $ zef --help\n        ...\n        CONFIGURATION /home/user/raku/install/share/perl6/site/resources/EE5DBAABF07682ECBE72BEE98E6B95E5D08675DE.json\n        ...\n\nTo summarize:\n\n- You can edit the `resources/config.json` file before you install zef.\n\n    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.\n\n- You can create a `$*HOME/.config/zef/config.json` file.\n\n    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). Alternative one can set the `XDG_CONFIG_HOME` env variable to instead look\n    in `$XDG_CONFIG_HOME/zef/config.json`.\n\n- You can override both of the previous entries by passing `zef --config-path=\"$path\" \u003cany command\u003e`\n\n### Configuration fields\n\n#### Basic Settings\n\n- **TempDir** - A staging area for items that have been fetched and need to be extracted/moved\n- **StoreDir** - Where zef caches distributions, package lists, etc after they've been fetched and extracted\n- **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`)\n\n#### Phases / Plugins Settings\n\nThese consist of an array of hashes that describe how to instantiate some class that fulfills the appropriate interface from _Zef.rakumod_ (`Repository` `Fetcher` `Extractor` `Builder` `Tester` `Reporter`)\n\nThe descriptions follow this format:\n\n    {\n        \"short-name\" : \"fez\",\n        \"enabled\" : 1,\n        \"module\" : \"Zef::Repository::Ecosystems\",\n        \"options\" : { }\n    }\n\nand are instantiated via\n\n    ::($hash\u003cmodule\u003e).new(|($hash\u003coptions\u003e)\n\n- **short-name** - This adds an enable and disable flag by the same name to the CLI (e.g. `--fez` and `--/fez`) and is used when referencing which object took some action.\n- **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.\n- **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`.\n- **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.\n\nSee the configuration file in [resources/config.json](https://github.com/ugexe/zef/blob/main/resources/config.json) for a\nlittle more information on how plugins are invoked.\n\nYou can see debug output related to chosing and loading plugins by setting the env variable **ZEF\\_PLUGIN\\_DEBUG=1**\n\n# FAQ\n\n### Proxy support?\n\nAll the default fetching plugins have proxy support, but you'll need to refer to the backend program's\n(wget, curl, git, etc) docs. You may need to set an _ENV_ variable, or you may need to add a command line\noption for that specific plugin in _resources/config.json_\n\n### Custom installation locations?\n\nPass a path to the _-to_ / _--install-to_ option and prefix the path with `inst#` (unless you know what you're doing)\n\n    $ zef -to=\"inst#/home/raku/custom\" install Text::Table::Simple\n    ===\u003e Searching for: Text::Table::Simple\n    ===\u003e Testing: Text::Table::Simple:ver\u003c0.0.3\u003e:auth\u003cgithub:ugexe\u003e\n    ===\u003e Testing [OK] for Text::Table::Simple:ver\u003c0.0.3\u003e:auth\u003cgithub:ugexe\u003e\n    ===\u003e Installing: Text::Table::Simple:ver\u003c0.0.3\u003e:auth\u003cgithub:ugexe\u003e\n\nTo make the custom location discoverable:\n\n    # Set the RAKULIB env:\n    $ RAKULIB=\"inst#/home/raku/custom\" raku -e \"use Text::Table::Simple; say 'ok'\"\n    ok\n\n    # or simply include it as needed\n    $ raku -Iinst#/home/raku/custom -e \"use Text::Table::Simple; say 'ok'\"\n    ok\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fugexe%2Fzef","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fugexe%2Fzef","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fugexe%2Fzef/lists"}