How to create and share a charm library

doc
1

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:

2
3