Prometheus

Charm libraries

Libraries are a mechanism for charm authors to easily share and reuse logic. This is very useful for the development of charms given the two‐sided nature of integrations because a given interface type needs logic on the providing side and on the required side, and it’s easier for the same person to be responsible for both.

Inside the charm there is a specific directory, under which there are subdirectories named as:

 $CHARMDIR/lib/charms/<charm>/v<API>/<libname>.py

$CHARMDIR is the project’s root (contains src/, hooks/, etc), and the <charm> placeholder represents the charm responsible for the library named as <libname>.py with API version <API>. So, as a more concrete example:

$CHARMDIR/lib/charms/mysql/v3/db.py

In this case, the author of charm mysql is making available the library db with major version 3. This file may be used both by the author and by any other charm authors that are interested in the offered functionality.

Fetching libraries

The management of libraries is done through the Charmcraft tool. This includes creating, publishing and fetching a library.

The fetch‐lib command will download the most recent version of the library specified via the provided import path. If the library already exists on disk, it will be updated.

$ charmcraft fetch‐lib charms.mysql.v3.foo
Library charms.mysql.v3.foo version 3.4 downloaded.

$ charmcraft fetch‐lib charms.foobar.v2.plugin
Library charms.foobar.v2.plugin updated to version 2.7.

$ charmcraft fetch‐lib charms.foobar.v3.metrics
Library charms.mysql.v3.metris was already up to date in version 3.2.

If no library name is provided, all libraries already under lib/charms/ will be updated to the most recent version available in the store, if possible, indicating what happened in each case:

$ charmcraft fetch-lib
Library charms.foobar.v2.plugin updated to version 2.7.
Library charms.mysql.v3.metris was already up to date in version 3.2.

Learn how to create publish your charm’s libraries

Libraries facilitate other charms effectively integrating with your charm. Visit our documentation if you’d like to learn how to create and publish libraries.