This document details how to build and share your own charm libraries.
You’ve been unable to find an existing library with the intended functionality for your charm. As such, it’s time to learn how to create your own.
Let’s start from a charm that has no libraries at all:
$ ll lib
ls: cannot access 'lib': No such file or directory
The first step is create the bare library template using
# Initialise a charm library named 'demo'
$ charmcraft create-lib demo
Before creating a library, you must first register ownership of your charm’s name. See How to publish your charm to Charmhub.
This will create a file at
Developers can import the library from within their charm code using its fully-qualified path minus the
See also: Library > Location
That file is just a template we must fill, though. For guidance see Library > Structure, which also links to some excellent examples that you can follow.
You’ve created your library and you’d like to share it with the world. To publish your library, run
charmcraft publish-lib followed by the full library path. This will upload the library content and also make it available for consumption by other charm authors.
$ charmcraft publish-lib charms.demo.v0.demo
Library charms.demo.v0.demo sent to the store with version 0.1
In order to be able to publish a charm library, you need to be signed into Charmcraft as a user that has permissions to publish libraries to this charm. In particular you need to be the owner of this charm or registered as a contributor to the charm—a status that can be requested via Discourse.
You will eventually need to evolve the library’s content (new functionalities, bug fixing, documentation improvements, etc.). Every time you want to offer a new version of your library, call the
publish-lib command again.
However, before publishing new versions, make sure to update the
LIBPATCH metadata fields inside the library file. Most times it is enough to just increment
LIBPATCH but, if you’re introducing breaking changes, you must work with the major API version.
Additionally, be mindful of the fact that users of your library will update it automatically to the latest PATCH version with the same API version. To avoid breaking other people’s library usage, make sure to increment the
LIBAPI version but reset
0. Also, before adding the breaking changes and updating these values, make sure to copy the library to the new path; this way you can maintain different major API versions independently, being able to update, for example, your v0 after publishing v1.
To share your charm library with developers:
- Access your charm page on charmhub.io.
- Go to the Libraries tab.
- Click on your library.
- Use the URL to share your library with other charm developers.