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.

For more details on the overlay step, see Overlay step.

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.