How to configure Charmcraft

See also:

You have installed Charmcraft. This document shows you how you can configure it.

Since Charmcraft v0.8.0 , this configuration file is mandatory for packing bundles, though optional for the rest of the commands. In a future release it will become mandatory for all project-handling commands, though remain optional for some store-related commands.

Contents:

Find the configuration file

The charmcraft tool configuration is specified in a charmcraft.yaml file located in the project’s root directory.

By default, Charmcraft will try to find that file in the current directory, but in case of needing to run charmcraft outside the project’s directory, it can be specified using the global option --project-dir.

Get acquainted with its contents

The following are the fields available in the configuration file. Everything is optional unless stated otherwise.

# (Required) The type of entity for which the present config exists
type: charm | bundle

# (Optional) Used for configuring charmcraft's interaction with store servers
charmhub:

    # (Optional) Base URL for the Charmhub API - default used if not set. 
    # Used mostly in the context of "private" charm stores.
    api-url: <api url>

    # (Optional) Base URL to push binaries to Charmhub - default used if not set.
    # Used mostly in the context of "private" charm stores.
    storage-url: <storage url>

# (Optional) List of files/directories to include in the built file. 
parts:

    # (Optional) Specify parts for a charm if `type`is set to `charm`.
    charm:

        # (Optional, new in charmcraft 1.2) The charm entry point, relative to the project
        # directory. If not defined, `src/charm.py` will be used.
        charm-entrypoint: /path/to/entrypoint

        # (Optional, new in charmcraft 1.2) Requirement files. If not defined, `requirements.txt`
        # will be used if it's present in the project directory.
        charm-requirements:
            - requirements-1.txt
            - requirements-2.txt

        # (Optional, new in charmcraft 1.4) A list of python packages to install
        # before installing requirements. These packages will be installed from
        # sources and built locally at packing time.
        charm-python-packages:
            - package1
            - package2

        # (Optional, new in charmcraft 1.4) A list of python packages to install
        # before installing requirements. Binary packages are allowed, but they
        # may also be installed from sources if a package is only available in
        # source form.
        charm-binary-python-packages:
            - package3
            - package4

        # (Optional) List of files to include. Note that `bundle.yaml`, the entry point
        # file and hooks are included automatically when packing a charm. Additionaly,
        # `config.yaml`, `metrics.yaml`, `actions.yaml`, `lxd-profile.yaml`, `templates`,
        # `version`, `lib` and `mod` will be included if they exist in the project directory.
        prime:
            - /path/to/file1
            - /path/to/file2

    # (Optional) Specify parts for a bundle if `type` is set to `bundle`.
    bundle:

        # (Optional) List of files to include. Note that `metadata.yaml` is included
        # automatically when packing a bundle.
        prime:
            - /path/to/file1
            - /path/to/file2

# A list of base configurations specifying environments charms 
# must be built on, and run on.
#
# There are two forms of base definition, both are indicated below.
bases:
    
    # (Optional) Short form base definition. Implies that the specified base is 
    # to be used for both `build-on` and `run-on`.
    - name: <name>
      channel: <channel>
      # (Optional) List of architecture strings, defaults to machine architecture
      architectures:
          - <arch>

    # (Optional) Expanded, long-form definition
    - build-on:
          - name: <name>
            channel: <channel>
            # (Optional) List of architecture strings, defaults to machine architecture
            architectures:
                - <arch>

      # (Optional) Defaults to what's specified in 'build-on'
      run-on:
          - name: <name>
            channel: <channel>
            # (Optional) List of architecture strings, defaults to machine architecture
            architectures:
                - <arch>

# (Optional, new in charmcraft 1.2) Control the analysis behaviour when explicitly running the 
# `analyze` command or implicitly running `pack`
analysis:
    # (Optional) Any attribute/lint analysis listed here (by name) will be ignored 
    ignore:
        attributes: [<check>,...]
        linters: [<check>,...]

Consult some examples

The following illustrate some implementations of the above spec:

type: bundle
charmhub:
  # these fields are set to the default value to illustrate field usage
  # likely not required in most cases
  api-url: https://api.charmhub.io
  storage-url: https://storage.snapcraftcontent.com
parts:
  bundle:
    prime: ["README.md"]

A different example, with a more comprehensive base definition:

type: charm
bases:
    - build-on:
        - name: ubuntu
          channel: "20.04"
          architectures: ["amd64"]
      run-on:
        - name: ubuntu
          channel: "21.04"
          architectures: 
              - amd64
              - aarch64
              - arm64

Start configuring!

Start modifying the examples above to suit your own needs.


Last updated 4 days ago.