Publish custom packages¶
In the tutorial about managing environments we learned how you
can share environments. In short: this is done by publishing 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 publish \ # (1)! \ --attr packages.aarch64-linux.hello-python \ # (2)! \ --build-repo email@example.com:flox-examples/hello-python.git \ # (3)! \ --publish-system aarch64-linux \ # (4)! \ --channel-repo firstname.lastname@example.org:flox-examples/floxpkgs.git \ # (5)! \ --upload-to s3://flox-examples \ # (6)! \ --key-file /path/to/binary_cache_secret_key \ # (7)! \ --download-from https://examples-cache.floxdev.com # (8)! \ --stability unstable # (9)!
flox publishcommand is run without any command line options, an interactive menu with open, asking you to provide the required options.
For the purpose of this tutorial we will provide options via command line in order to describe them.
The attribute path of the package we want to publish.
The repository of the build recipe for the package we are publishing.
The format is any valid git repository url or a Nix installable.
The system / platform for which we are publishing.
The flox channel repository to which we want to publish our package.
The enduser will need to subscribe to this repository.
(Optional) The binary cache to upload the build artifacts to.
(Optional) The binary cache private signing key.
Every build artifact can be signed to improve security.
(Optional) The binary cache url to download the build artifacts, if it is different from the
stable) The stability to publish under.
If the channel repository (
flox-examples/floxpkgs) does not exist, it will be
created for you.
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:
$ flox channels \ \ CHANNEL │ TYPE │ URL \ ───────────────┼──────┼────────────────────────────────── \ flox │ flox │ github:flox/floxpkgs/master # (1)! \ nixpkgs-flox │ flox │ github:flox/nixpkgs-flox/master # (2)!
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
examples channel is listed.
$ flox channels CHANNEL │ TYPE │ URL ───────────────┼──────┼────────────────────────────────── examples │ user │ github:flox-examples/floxpkgs flox │ flox │ github:flox/floxpkgs/master nixpkgs-flox │ flox │ github:flox/nixpkgs-flox/master
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 install examples.hello-python Installed 'examples.hello-python' package(s) into 'default' environment. $ flox activate -- hello-python Hello world!
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.