Publish custom packages¶
We've previously learned how to share environments.
In short: this is done by pushing your environment
flox push) to your
We've also learned how to build a custom package and now it is time to share it. We can share a package by publishing it to a flox channel to which our friends and colleagues can subscribe.
Channels solve the unfortunate requirement of Nix to access and evaluate Nix
source code in order to install a package.
floxmeta repository, a flox channel is simply a repository you
By convention, we call this repository
Whether channels are public or private depends on whether the repository is
public or private.
Let's look at an example of how we can publish a package.
If you haven't already, please install flox before continuing.
flox publish command is experimental
flox publish command is working, we know that there is a lot we need
to do to make it more appealing to use.
We wrote this tutorial with the intention to showcase the concept behind the command.
1. Example package¶
To be able to publish a package we need a repository with a flox package. For this example we will use the work we did in the previous tutorial (Custom package).
Let's clone the
floxified branch from our
hello-python example where the build
recipe for our package already exists.
$ git clone https://github.com/flox-examples/hello-python $ cd hello-python $ flox build # (1)! warning: not writing modified lock file of flake 'git+file:///home/USER/dev/hello-python' ... • Added input 'flox-floxpkgs/tracelinks/flox-floxpkgs': follows 'flox-floxpkgs' $ ./result/bin/hello Hello world!
- Let's build a package to make sure our example package is ready to be published.
flox publish - publish package to a channel¶
Once the package builds successfully, it can be published to a flox channel.
flox publishcommand is run without any command line options,
floxwill infer or prompt for (if possible) the package to publish and expect all other required arguments to be provided via the user's config (see
For the purpose of this tutorial we will provide options via command line in order to describe them.
The package we want to publish. Packages can be referred to simply by their name within the repository. If we want to publish packages for other systems or from other (remote) projects we can use more specific references. In this case, we could also use for example the following references:
For publish the package must be defined in a remote git repository and be referred to either directly by a
git+ssh://<url>[#<package>]URL or another URL that can be resolved to an upstream git resource.
In this case, the package defined in a local repository is resolved to the current branch's upstream branch at
Packages referred to by a
github:<user>/<owner>[#<package>]URL are resolved to
ssh://[email protected]by default or
The binary cache to upload the build artifacts to. Must be provided by any of the following in decreasing priority:
cache_urlconfig key (set using e.g.
flox config --set cache_url s3://flox-examples)
(Optional) The binary cache URL to download the build artifacts from, if it is different from the
Optionally provided by any of the following in decreasing priority: - The
--public-cache-urloption - The
FLOX_PUBLIC_CACHE_URLenvironment variable - The
public_cache_urlconfig key (set using e.g.
flox config --set public_cache_url https://examples-cache.flox.dev)
The binary cache private signing key. Every build artifact has to be signed to improve security.
Signing keys can be generated using
They should not be shared publically but can be reused at any scope (package, project, user/machine, team,...).
Must be provided by any of the following in decreasing priority: - The
--signing-keyoption - The
FLOX_SIGNING_KEYenvironment variable - The
signing_keyconfig key (set using e.g.
flox config --set signing-key /path/to/binary_cache_secret_key)
(Optional) The stability branch of nixpkgs to use.
Uses the locked referencs found in the repo by default.
flox publish will create a detached
catalog/<system> branch in the upstream
flox channels - list subscribed channels¶
Before we subscribe to any channel let us first explore our existing channels.
After a fresh
flox installation these are the flox channels you are
automatically subscribed to:
The channel where you can find latest releases of
floxitself, including pre-releases.
The channel where you can find all the packages from upstream
nixpkgs-floxis a floxified version of
flox subscribe - subscribe to a channel¶
To be able to use a package from a channel, we need to subscribe to that channel.
When listing our channels we can now see that the
hello-example channel is listed.
Once a user subscribes to a channel, they can search for packages in that channel.
We can also install it to a flox environment.
flox unsubscribe - unsubscribe from a channel¶
When you no longer wish to use packages from a certain channel you can always unsubscribe from that channel.
The package you installed to one of your environments from a channel you unsubscribed from will still continue to work. But upgrading that package will fail.