Part properties¶

This reference describes the purpose and usage of all keys that can be declared for a part.

Top-level keys¶

plugin¶

Type

str

Description

The plugin to build the part with.

During the build step, the plugin prepares the part’s files with the build system of its language or framework.

For more details on plugin-specific keys and dependencies, see Plugins.

Examples

plugin: python

plugin: dump

Pull step keys¶

The following keys define the part’s external dependencies and how they are retrieved from the declared location.

source¶

Type

str

Description

The location of the source files for the part.

During the pull step, these files are placed in the part’s build environment.

Enter either an HTTP/HTTPS URL or the path to the local project directory.

Examples

source: .

source: https://github.com/canonical/dqlite

source-type¶

Type

str

Description

The format of the part’s source.

During the pull step, the part expects the source to behave like the specified format.

If unset, the part attempts to auto-detect the format.

Supported formats include container types like .tar files and Debian packages, version-controlled directories like Git repositories, and local files.

Values

Value	Description
`deb`	Debian package
`git`	Git repository
`rpm`	Red Hat package
`snap`	Snap container format
`tar`	Tarball archive
`zip`	ZIP file
`local`	Local directory or file in the project directory
`file`	A “plain” file retrieved from the internet

Examples

source-type: git

source-type: local

source-checksum¶

Type

str

Description

The checksum of the downloaded source, to ensure integrity.

During the pull step, the part compares the checksum against that of the downloaded files.

Checksums can be generated with any of the hashing algorithms supported by Python’s hashlib.

Examples

source-checksum: sha256/1451d01ee3a21100340aed867d0b799f46f0b1749680028d38c3f5d0128fb8a7

source-branch¶

Type

str

Description

If the source is a Git repository, this key specifies the target branch.

During the pull step, the part fetches the repository from the earliest available commit up to the tip of this branch.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-commit and source-tag.

Examples

source-branch: main

source-branch: hotfix/2.10

source-tag¶

Type

str

Description

If the source is a Git repository, this key specifies the target tag.

During the pull step, the part fetches the repository from the earliest available commit up to the commit with this tag.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-branch and source-commit.

Examples

source-tag: 1.0.1

source-commit¶

Type

str

Description

If the source is a Git repository, this key specifies the target commit. Both short and long SHA hashes are supported.

During the pull step, the part fetches the repository from the earliest available commit up to this commit.

The commit history can be truncated by specifying a source-depth.

This key is mutually incompatible with source-branch and source-tag.

Examples

source-commit: 36086af03fc4941a8ac219648ce77401743f3ae0

source-depth¶

Type

int

Description

If the source is a Git repository, this key specifies how far back in the commit history to fetch.

During the pull step, the part fetches the repository from the specified commit up to the target commit, the target tag, or the tip of the target branch.

Equivalent to the --depth parameter of git fetch.

If unset, the part fetches the full repository history up to the target commit, the target tag, or the tip of the target branch.

Examples

source-depth: 1

source-submodules¶

Type

list[str]

Description

If the source is a Git repository, this key specifies the registered Git submodules that the project also needs.

During the pull step, the part fetches these submodules.

Equivalent to the --recurse-submodules parameter of git clone.

If unset, the part will fetch all of the repository’s submodules.

Examples

source-submodules:
  - third_party/googletest
  - third_party/jsoncpp

source-submodules:
  - libbpf

source-subdir¶

Type

str

Description

The subdirectory of the unpacked source where the build will occur.

During the pull step, the build will be restricted to the specified path.

If unset, the build can access the entire file tree of the source.

Examples

source-subdir: src

source-subdir: demo_nodes_cpp

override-pull¶

Type

str

Description

The commands to run instead of the default behavior of the pull step.

The standard pull step actions can be performed by calling craftctl default.

For more details on overriding lifecycle steps and using craftctl, see Override a step.

Examples

override-pull: |
craftctl default
rm $CRAFT_PART_SRC/pyproject.toml

Overlay step keys¶

For craft applications that support filesystem overlays, the following keys modify the part’s overlay layer and determine how the layer’s contents are represented in the stage directory.

overlay¶

Type

list[str]

Description

The files to copy from the part’s overlay filesystem to the stage directory.

For more details on file paths, see Specifying paths.

Examples

overlay:
  - bin
  - usr/bin

overlay:
  - -etc/cloud/cloud.cfg.d/90_dpkg.cfg

overlay-packages¶

Type

list[str]

Description

The packages to install in the part’s overlay filesystem.

During the overlay step, these packages are installed into the part’s overlay filesystem using the base layer’s package manager.

Examples

overlay-packages:
  - ed

overlay-script¶

Type

str

Description

The commands to run after the part’s overlay packages are installed.

If unset, the part’s overlay filesystem will only contain the packages specified in overlay-packages.

Examples

overlay-script: |
rm -f ${CRAFT_OVERLAY}/usr/bin/vi ${CRAFT_OVERLAY}/usr/bin/vim*
rm -f ${CRAFT_OVERLAY}/usr/bin/emacs*
rm -f ${CRAFT_OVERLAY}/bin/nano

Build step keys¶

The following keys modify the build step’s behavior and the contents of the part’s build environment.

after¶

Type

list[str]

Description

The parts to process before starting this part’s build.

During the build step, this part waits for all of the listed parts to reach the stage step before it begins building.

The purpose of this key is to stagger the part processing order so that interrelated parts can provide data to each other.

When this key is set, the part queue follows modified rules during the lifecycle:

Parts are processed alphabetically by name.
When the build reaches a part that another depends on, the dependent part will only start its build and stage steps after the initial part finishes its stage step.
After the string of dependent parts completes their lifecycles, the queue continues to the next part in alphabetical order.

Examples

after:
  - build-deps
  - daemon

disable-parallel¶

Type

bool

Description

Whether to disable CPU multithreading during the build step.

If unset, the build defaults to multithreading.

Examples

disable-parallel: true

build-environment¶

Type

list[dict[str, str]]

Description

The environment variables to define for the build step, as key-value pairs.

Examples

build-environment:
  - MESSAGE: Hello world!
  - NAME: Craft Parts

build-packages¶

Type

list[str]

Description

The packages to install during the build step, before the build starts. The part installs them into the build environment using the host’s native package manager.

Build packages must be listed by their name on the host system.

Examples

build-packages:
  - git
  - libffi-dev
  - libssl-dev

build-snaps¶

Type

list[str]

Description

The snaps to install during the build step, before the build starts. The part makes them available in the build environment.

Entries can be listed in one of three formats.

<snap-name>
<snap-name>/<channel-name>
<snap-name>/<channel-name>/<version-name>

If no version or channel is provided, latest/stable is used.

Examples

build-snaps:
  - go/latest/stable
  - node/stable

organize¶

Type

dict[str, str]

Description

A map of files from the build directory to their destinations in the stage directory.

Each pair of source and destination paths is represented as a nested key of the form <source-path>: <destination-path>.

At the end of the build step, the files at the source paths are copied to their destination paths in the stage directory.

Examples

organize:
  hello.py: bin/hello

override-build¶

Type

str

Description

The commands to run instead of the default behavior of the build step.

The standard build step actions can be performed by calling craftctl default.

For more details on overriding lifecycle steps and using craftctl, see Override a step.

Examples

override-build: |
cd cmd/webhook
mkdir $CRAFT_PART_INSTALL/ko-app
go build -o $CRAFT_PART_INSTALL/ko-app/webhook -a .

Stage step keys¶

The following keys modify the stage step’s behavior and determine how files from the part’s build directory are represented in the stage directory.

stage¶

Type

list[str]

Description

During the stage step, any specified files are copied from the build directory to the stage directory.

Paths support wildcards (*) and must be relative to the working directory where they will be used.

For more details on file paths, see Specifying paths.

Examples

stage:
  - usr/bin/*
  - usr/share

stage:
  - -usr
  - zfsutils-linux

stage-packages¶

Type

list[str]

Description

During the stage step, these packages are included in the stage environment alongside the build artifacts.

Chisel slices can be listed using the <package-name>_<slice-name> syntax.

Listing both packages and slices in the same stage-packages key is not currently supported.

Examples

stage-packages:
  - curl
  - libxml2

stage-snaps¶

Type

list[str]

Description

During the stage step, these snaps are included in the stage environment.

Entries can be in one of three formats:

<snap-name>
<snap-name>/<channel-name>
<snap-name>/<channel-name>/<version-name>

If an entry contains no version or channel, latest/stable is used.

Examples

stage-snaps:
  - go/1.17
  - chisel/latest/candidate
  - mir-kiosk-x11

override-stage¶

Type

str

Description

The commands to run instead of the default behavior of the stage step.

The standard stage step actions can be performed by calling craftctl default.

For more details on overriding lifecycle steps and using craftctl, see Override a step

Examples

override-stage: |
craftctl default
chown -R 499 "${CRAFT_PART_INSTALL}/entrypoint.sh"

Prime step keys¶

The following keys modify the prime step’s behavior and determine how the contents of the stage directory are reflected in the final payload.

prime¶

Type

list[str]

Description

During the prime step, any specified files are copied from the stage directory to the final payload.

Paths support wildcards (*) and must be relative to the working directory where they will be used.

For more details on file paths, see Specifying paths.

Examples

prime:
  - usr/lib/*/qt6/plugins/tls/*
  - -usr/share/thumbnailers

override-prime¶

Type

str

Description

The commands to run instead of the default behavior of the prime step.

The standard prime step actions can be performed by calling craftctl default.

For more details on overriding lifecycle steps and using craftctl, see Override a step

Examples

override-prime: |
craftctl default
mkdir -p $CRAFT_PRIME/var/lib/mysql
mkdir -p $CRAFT_PRIME/var/lib/mysqld

Permissions keys¶

permissions¶

Type

list[Permissions]

Description

The ownership and permission settings for a set of files in the part’s prime directory.

The files at path will be assigned an owner and a group, with the read, write, and execute permissions of each being determined by the value of mode.

Examples

permissions:
  - owner: 2000
    group: 2000
  - path: srv/indico/start-indico.sh
    mode: '544'
  - path: etc/
    mode: '755'

path¶

Type

str

Description

The file path, relative to the prime directory, being assigned permissions.

Wildcards (*) are supported.

If unset, the permissions will be assigned to every file in the prime directory.

owner¶

Type

int

Description

The numeric user ID (UID) of the desired owner on the host system.

This entry is required if the permissions contain a group entry.

group¶

Type

int

Description

The numeric group ID (GID) of the desired owner group on the host system.

This entry is required if the permissions contain an owner entry.

mode¶

Type

str

Description

The numeric representation of the file’s read, write, and execute permissions.

This entry must be assigned an octal number, enclosed in double-quotation marks ("), for each defined path.

This value should align with the POSIX specification for file permissions, just like one would use when calling chmod. For more detail on octal file permissions, see the chmod command reference.