Publish custom packages¶
We've previously learned how to share environments.
In short: this is done by pushing your environment
(with flox push
) to your floxmeta
repository.
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.
Like your floxmeta
repository, a flox channel is simply a repository you
push to.
By convention, we call this repository floxpkgs
.
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
While the 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.
2. flox publish
- publish package to a channel¶
Once the package builds successfully, it can be published to a flox channel.
$ flox publish \ # (1)! \
hello-python \ # (2)! \
--cache-url s3://flox-examples \ # (3)! \
--public-cache-url https://examples-cache.flox.dev # (4)! \
--signing-key /path/to/binary_cache_secret_key \ # (5)! \
--stability unstable # (6)!
-
If the
flox publish
command is run without any command line options,flox
will infer or prompt for (if possible) the package to publish and expect all other required arguments to be provided via the user's config (seeflox-config(1)
)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:
packages.<system>.hello-python
.#packages.<system>.hello-python
/home/USER/dev/hello-python#packages.<system>.hello-python
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
https://github.com/flox-examples/hello-python
.Packages referred to by a
github:<user>/<owner>[#<package>]
URL are resolved tossh://[email protected]
by default orhttps://github.com
, if--prefer-https
is provided. -
The binary cache to upload the build artifacts to. Must be provided by any of the following in decreasing priority:
- The
--cache-url
option - The
FLOX_CACHE_URL
environment variable - The
cache_url
config key (set using e.g.flox config --set cache_url s3://flox-examples
)
- The
-
(Optional) The binary cache URL to download the build artifacts from, if it is different from the
--cache-url
.Optionally provided by any of the following in decreasing priority: - The
--public-cache-url
option - TheFLOX_PUBLIC_CACHE_URL
environment variable - Thepublic_cache_url
config key (set using e.g.flox config --set public_cache_url https://examples-cache.flox.dev
)If omitted,
cache_url
is used. -
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-key
option - TheFLOX_SIGNING_KEY
environment variable - Thesigning_key
config 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
repository (https://github.com/flox-examples/hello-python
).
3. 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
flox
itself, including pre-releases. -
The channel where you can find all the packages from upstream
NixOS/nixpkgs
.nixpkgs-flox
is a floxified version ofnixpkgs
.
4. flox subscribe
- subscribe to a channel¶
To be able to use a package from a channel, we need to subscribe to that channel.
$ flox subscribe hello-example git+https://github.com/flox-examples/hello-python
subscribed channel 'example'
When listing our channels we can now see that the hello-example
channel is listed.
$ flox channels
CHANNEL │ TYPE │ URL
───────────────┼──────┼────────────────────────────────────────────────────
hello-example │ user │ git+https://github.com/flox-examples/hello-python
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 hello-example.hello-python
Installed 'hello-example.hello-python' package(s) into 'default' environment.
$ flox activate -- hello-python
Hello world!
5. 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.