The Onyx package manager is intentionally very simple. Onyx does not have a central package repository like NPM, PyPI, or Cargo. Instead Onyx uses a decentralized approach, that follows this simple rule.

Every package is a Git repository, with a file called module.onyx that is responsible for including all other files in the package.

The job of the package manager is to simply clone each of these Git repositories into a known structure, and build a file for you to include in your project that loads all of your packages.

The package manager uses Git's tags feature to store version numbers. This way the package manager can clone exactly one tag, at one commit, to avoid downloading all history of the package, when all you want is a single version.

When you publish a package using onyx package publish, it simply increments the version number in the package file, commits that change, creates a new tag at that commit, and pushes all changes and tags to the Git server.

When someone else runs onyx package update, all packages will be updated to their newest compatible version.

Do note that, in order to use Onyx's package manager, you MUST have Git installed and it must be in the PATH.

To use Onyx's package manager, you must be in an Onyx project. An Onyx project is simply a directory with a file named onyx-pkg.kdl.

To create a new project in a directory, you can use the following command, and answer the prompts (or leave any them blank).

$ onyx package init
Creating new project manifest in ./onyx-pkg.kdl.

Package name: example-project
Package description: A simple example project
Package url: https://github.com/...
Package author: Brendan Hansen
Package version (0.0.1):

Once your project is created, you can add packages by running onyx package add ...

$ onyx package add http-server
$ # Or
$ onyx package add https://github.com/onyx-lang/pkg-http-server

If you want to specify a particular version of a package, you can add the version number as another argument to the command.

$ # Specify version 0.1.2
$ onyx package add http-server 0.1.2 

For the sake of convience, the package manager maintains a list of string templates to try to resolve where your package comes from. Currently by default, there is only one, https://github.com/onyx-lang/pkg-X. This means that when you try to add http-server, it will actually end up using https://github.com/onyx-lang/pkg-http-server. If you want, you can change this list of string templates at the top of ONYX_PATH/tools/onyx-pkg.onyx.

You will notice that no files were downloaded and nothing has change in your directory. This is because adding a package simply adds it to the list of dependencies in your onyx-pkg.kdl It does not synchronize all of your packages.

To do that, simply run onyx package sync.

$ onyx package sync
        Fetch  http://github.com/onyx-lang/pkg-http-server  0.2.24

This downloads all new packages, upgrades exist packages, builds native libraries, and creates a new package file to include.

Once all packages are synchroized, you can use them in your project but simplying including the package.onyx file automatically created. By default this file lives at lib/packages.onyx in your project.

Here is a simple example of using the http-server package in a project.

// main.onyx

#load "./lib/packages" // <--- Have to include the packages file!

use core
use http

main :: () {
    router := http.server.router();
    router->get("/", (req, res) => {
        res->html("
Simple server is working!
");
        res->status(200);
        res->end();
    });

    app := http.server.tcp(&router);
    app->serve(8000);
}

Once all of this is setup, your workflow will likely just look like onyx pacakge update, then onyx package sync, with a bit of onyx package add ... sprinkled in there.

Creating a new package for Onyx is incredibly simple. There just three things a project needs to become a package.

1. Be a public Git repository
2. Have an onyx-pkg.kdl file
3. Have a module.onyx file

Hosting a package on GitHub, GitLab, or any Git server is very simple if you are familiar with Git. Just make sure everyone that needs to access the package has pull access to the repository.

Every Onyx project already has an onyx-pkg.kdl file. Ensure the package section has correct information about your package, and you should be good to go there. See the guide on creating a native library for how to set that up in your project.

Finally, you need a module.onyx file. This file simply needs to include all other source files for the package. In a particularly small package, all of the code might go right inside of module.onyx.

A typical module.onyx looks like this.

// module.onyx

package package_name_here

#load_all "./src"

This file simply includes everything inside of the src folder. If needed you can conditionally load source files, depending on your package's needs.

When your package is ready for a release, you can simply run onyx package publish. This bumps the version in onyx-pkg.kdl, creates a new commit, tags that commit with the new version, then pushes all of the changes to the Git server, assuming you have push access.

$ onyx package publish
  Publishing  Creating new published version
   Published  Successfully published new version.