Publishing Libraries

This document details how to use charmcraft to interact with libraries.

Finding and using libraries

If the charm you’re writing needs to interact with another application, you can check if the relevant application charm provides a library that could aid that interaction. The easiest way to see this from the command line is using the charmcraft list-lib command, which will query Charmhub and show which libraries are published for the specified charm, along with API/patch versions:

$ charmcraft list-lib demo
Library name    API    Patch
demo            0      1

The listing will not show older API versions, ensuring that new users always start with the latest version. Once you have discovered a library you want to use, you need to fetch it from Charmhub before it can be imported by your charm code. This is done using the charmcraft fetch-lib command:

$ charmcraft fetch-lib charms.demo.v0.demo
Library charms.demo.v0.demo version 0.1 downloaded.

That command will download the library, creating the required directory layout in your charm directory:

$ ls -l lib/charms/demo/v0/
-rw-rw-r-- 1 user user 1061 Apr 06 15:24 lib/charms/demo/v0/

This file is now part of our charm’s project; it will be included with our charm (and therefore distributed with it) when the charm is packaged and published with charmcraft. Using the library is now trivial, it can just be imported in your charm’s code (note that the charm automatically has the lib directory as part of the Python import paths).

from charms.demo.v0 import demo

To update the version of the library you are consuming, you can simply run the charmcraft fetch-lib command again - the latest version will be fetched if there is an update available:

$ charmcraft fetch-lib charms.demo.v0.demo
Library charms.demo.v0.demo was already up to date in version 0.1.

Creating libraries

Charm libraries should always be initialised using the charmcraft tool. Suppose we are creating a library as part of a charm named demo:

# Initialise a charm library named 'demo'
$ charmcraft create-lib demo

Before creating a library, you must first register ownership of your charm’s name. This is covered in the Publishing section.

This will create a file at $CHARMDIR/lib/charms/demo/v0/ Charm libraries are always located according to the pattern: $CHARMDIR/lib/charms/<charm_name>/v<API>/<library_name>.py. Developers can import the library from within their charm code using its fully-qualified path:

import charms.demo.v0.demo

Publishing libraries

Once your library is complete, publishing it is simple - a single command will both publish the library to Charmhub, and 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

Last updated 3 months ago.