How to find and use a charm library

doc
1

This document shows how to take advantage of existing charm libraries.

Contents:

Discover an existing charm library

You’ve come to the conclusion that you’d like a charm library. The first thing to do is check if there is already an existing one that you can use. For example, if the charm you’re writing needs to interact with another service, you should check if that service provides any library that would help in that interaction.

The easiest way to find an existing library for a given charm is via charmcraft list-lib, as shown below. This will query Charmhub and show which libraries are published for the specified charm, along with API/patch versions.

jdoe@machine:/home/jane/autoblog$ charmcraft list-lib blogsystem
Library name    API    Patch
superlib        1      0

The listing will not show older API versions; this ensures that new users always start with the latest version.

Another good way to search for libraries is to explore the charm collection on Charmhub.

See more: charmcraft list-lib

Fetch a charm library

  1. In your charm’s charmcraft.yaml, use the charm-libs key to declare all the libraries you want to fetch. For example:
charm-libs:
    # Fetch postgres_client lib with API version 1 and latest patch:
    - lib: postgresql.postgres_client
      version: "1"

    # Fetch mysql lib with API version 0 and patch version 5:
    - lib: mysql.mysql
      version: "0.5"

See more: File charmcraft.yaml > charm-libs

  1. Run charmcraft fetch-libs. Charmcraft will fetch the libraries.

If a library already exists on your machine, and you only specify the API version, Charmcraft will check for the latest patch version.

Either way, the library will be placed in your charm’s lib/charms directory and become part of your charm’s project – that is, it will be packed inside your charm and distributed with it when the charm is packaged and published with charmcraft.

Charm libraries are always located according to the pattern: $CHARMDIR/lib/charms/<charm_name>/v<API>/<library_name>.py. See The location of a charm library inside a charm.

See more: charmcraft fetch-libs

Import a charm library

You’ve fetched a library—it’s now time to use it! To use the library, you need to import it in your charm’s code, as shown below. (Note that the charm automatically has the lib directory as part of the Python import paths.)

from charms.demo.v0 import demo

Update a charm library

  1. Update your charm’s charmcraft.yaml’s charm-libs key with the desired library version.

See more: File charmcraft.yaml > charm-libs

  1. Run charmcraft fetch-libs. Charmcraft will update the libraries.

See more: charmcraft fetch-libs

2
3
4

Hey, this leads to a private discourse page which looks like a 404 (Oops! That page doesn’t exist or is private.) when not logged in.

5

Fixed it now, thanks!

1 Like