See also:
This document details how to build and share your own charm libraries.
Contents:
Create a charm library
See also:
charmcraft create-lib
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 charmcraft create-lib
:
# 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 $CHARMDIR/lib/charms/demo/v0/demo.py
.
Developers can import the library from within their charm code using its fully-qualified path minus the lib
part:
import charms.demo.v0.demo
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.
Publish a charm library
See also:
charmcraft publish-lib
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.
Update a charm library
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 LIBAPI
/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 LIBPATCH
to 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.
Share a charm library
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.