Publishing a Package in Onyx

Onyx Package Management

Onyx does not have a centrally managed package repository like JavaScript's npm, Ruby's Gem, or Python's PyPI. You simply publish your libraries as Git repositories, such as on GitHub.

Publishing Packages

module.onyx

There is a simple convention for publishing a package repository. You must create and place a module.onyx file that loads all the Onyx programs you want to expose as a library. The minimum configuration for this file is as follows, for example:

module.onyx

package package_name_here
#load_all "./src"

onyx pkg Command and onyx-pkg.kdl

In addition to the convention above, the onyx pkg command is provided for publishing packages.

1. Initialize the project structure with onyx pkg init. This command can also automatically create the project management configuration file onyx-pkg.kdl.
2. Publish the package with onyx pkg publish.

Since there is no central repository, management is very easy and comfortable. On the other hand, there is no centralized information for a set of packages, so you cannot search for them. Probably. At least, that seems to be the case at the moment.

onyx-pkg.kdl looks something like this. ^[1]

onyx-pkg.kdl

package {
    name "<any package name>" 
    author "<your name>" 
    url "https://github.com/<GitHub account or organization name>/<repository name>.git" 
    description "<any description>" 
    version "0.3.0" // SemVer format 
}

config {
    dependency_source_path "./lib" 
    dependency_binary_path "./bin" 
}

The onyx pkg publish command actually acts like a wrapper for git commands, and what it does is simple. First, it updates the package.version value in onyx-pkg.kdl appropriately. You will be asked interactively whether to update the major, minor, or patch version according to SemVer.

Then, it simply tags it with that updated version number in git and pushes it.

Using Packages

Using packages is also simple; you just reference the published Git repository as described above.

1. Create onyx-pkg.kdl using onyx init.
2. Add the dependency package setting to onyx-pkg.kdl using onyx pkg add <any Git repository URL> ^[2].
3. onyx pkg sync: Downloads the source code for each package according to the dependencies in onyx-pkg.kdl.
4. Since each dependency is added under the lib folder, load them as needed. For example, if you want to try loading everything roughly, you can use #load_all "lib" and then use use as appropriate.

Supplementary Information / Notes

Sample Code

• Library publisher side: https://github.com/hatappo/pkg-example-onyx
• Library consumer side: https://github.com/hatappo/pkg-load-example-onyx

Package Manager

The code for the package manager can be found at https://github.com/onyx-lang/onyx/blob/master/scripts/onyx-pkg.onyx.

Adding 3rd Party Packages Fails

In Onyx v0.1.8, using 3rd party libraries might not work correctly, so you need to use the nightly version. You can install the nightly version by adding nightly to the execution argument of the installation script as follows:

sh <(curl https://get.onyxlang.io -sSfL) nightly

The PR to fix this bug has already been merged, so it should be included in the next release.

• Issue: https://github.com/onyx-lang/onyx/issues/92
• PR: https://github.com/onyx-lang/onyx/pull/93

脚注

1. Official documentation for the KDL format → https://kdl.dev/

2. For official packages starting with github.com/onyx-lang/pkg-*, you can use a shorthand onyx pkg add by specifying only the * name.