Publishing Packages¶
elba dependencies can be hosted on registries, which are online package repositories which host packages (think crates.io or npm) that are associated with indices. The process of publishing a package involves multiple steps (some of which are handled for you).
Package registries are specified in the configuration of an index; for users, this means a registry can be added by just adding the corresponding package index. See the relevant reference docs for more details.
Logging in¶
Before you can upload a package to a registry, you must be authenticated with that registry. Each package registry might do authentication in a slightly different way, but all authentication systems revolve around you being given an authentication token which can be used in the elba command-line interface.
For the official registry, logging in can be done by clicking the “Log in” button at the top of the page and authenticating with Github (other authentication methods aren’t currently being implemented, but we’re open to contributions!). After this is done, you can add an auth token which can be used to log into the elba cli.
For any other potential registries, the process might differ, but the end result should be that you get an auth token.
In order to log into a registry, use the elba login
subcommand. If you
have multiple indices specified in your configuration, you can specify
the index to use with the --index
flag. For example:
$ elba login a67fc893bccfea2141 --index index+git+https://github.com/elba/index
Otherwise, elba will use the default index (the first index specified in configuration).
Login information is saved to the logins.toml
file in the platform-
specific data directory:
- On Linux, this is either
$XDG_DATA_HOME/elba
or~/.local/share/elba
. - On Windows, this is at
%ROAMINGAPPDATA\elba
. - On macOS, this is at
~/Library/Application/Support/elba
.
Packaging/archiving¶
Before a package is published, it must be compressed into a tarball with
the tar.gz
extension. The elba publish
command will do this
automatically for you; however, you can also do this step yourself with
the elba package
subcommand.
When run in an elba project directory or subdirectory, this command will build all targets of a project to make sure it builds successfully, then package the source code of the project into a tarball.
If you’d like to skip the verification process, you can pass the
--no-verify
flag to the command.
Ignoring files¶
In some cases, you might not want to include every file in the current
directory in the tarball. For one thing, elba will automatically ignore
any files specified in a .gitignore
file in the current project.
Additionally, you can specify files to ignore in the manifest file of
your project, under the package.ignore
key.
package.ignore
is a list which accepts individual “lines” of a
.gitignore files as list elements. An example is provided below:
[package]
# snip: other package metadata
# ignoring files that end with .out or .dev
ignore = ["*.out", "*.dev"]
Uploading a package¶
Uploading a package can be accomplished with the corresponding command:
elba publish
, which verifies that a package builds, packages it into
a tarball, and uploads it to a registry. Similar to elba login
, you
can pass the --index
flag to specify which index this command should
apply to. Unlike elba package
, you can’t disable package
verification: all targets must build in order to upload your package
to an index.
Yanking: for when things go wrong¶
After a package has been published to a package registry, there is no API endpoint or elba feature which allows for deleting a package (this circumvents the “left-pad” problem). However, there is a yanking feature (similar to crates.io), which lets you disable a version of a package from being dependended on or retrieved by any future package consumers.
The relevant subcommand is elba yank
, and it takes one positional
argument: the package and package version to yank, specified in the form
group/name|version
. It also takes the optional --index
flag,
like elba login
and elba publish
.
You can also provide the --unyank
flag, which does exactly what it
says on the tin.