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 |
---|---|
|
Debian package |
|
Git repository |
|
Red Hat package |
|
Snap container format |
|
Tarball archive |
|
ZIP file |
|
Local directory or file in the project directory |
|
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.