Project information

Project parameters are provided to callback functions by passing an instance of the StepInfo class. It consolidates properties from the PartInfo, ProjectInfo and ProjectDirs classes, including custom application-specific parameters passed as keyword arguments when instantiating LifecycleManager.

class craft_parts.infos.ProjectDirs(*, partitions=None, work_dir='.')

The project’s main work directories.

Parameters:

  • work_dir (Path | str) – The parent directory containing the parts, prime and stage subdirectories. If not specified, the current directory will be used.

  • partitions (Sequence[str] | None) – If partitions are enabled, the list of partitions.

Variables:

  • work_dir – The root of the work directories used for project processing.

  • parts_dir – The directory containing work subdirectories for each part.

  • overlay_dir – The directory containing work subdirectories for overlays.

  • overlay_mount_dir – The mountpoint for the overlay filesystem.

  • overlay_packages_dir – The cache directory for overlay packages.

  • overlay_work_dir – The work directory for the overlay filesystem.

  • stage_dir – The staging area containing installed files from all parts.

  • prime_dir – The primed tree containing the final artifacts to deploy.

get_prime_dir(partition=None)

Get the prime directory for the given partition.

Parameters:

partition (str | None)

Return type:

Path

get_stage_dir(partition=None)

Get the stage directory for the given partition.

Parameters:

partition (str | None)

Return type:

Path

class craft_parts.infos.ProjectInfo(*, application_name, cache_dir, arch='', base='', parallel_build_count=1, strict_mode=False, project_dirs=None, project_name=None, project_vars_part_name=None, project_vars=None, partitions=None, filesystem_mounts=None, base_layer_dir=None, base_layer_hash=None, usrmerged_by_default=False, stage_packages_slice_support=True, **custom_args)

Project-level information containing project-specific fields.

Parameters:

  • application_name (str) – A unique identifier for the application using Craft Parts.

  • project_name (str | None) – Name of the project being built.

  • cache_dir (Path) – The path to store cached packages and files. If not specified, a directory under the application name entry in the XDG base directory will be used.

  • arch (str) – The architecture to build for. Defaults to the host system architecture.

  • parallel_build_count (int) – The maximum number of concurrent jobs to be used to build each part of this project.

  • strict_mode (bool) – Only allow plugins capable of building in strict mode.

  • project_dirs (ProjectDirs | None) – The project work directories.

  • project_name – The name of the project.

  • project_vars_part_name (str | None) – Project variables can be set only if the part name matches this name.

  • project_vars (dict[str, str] | ProjectVarInfo | None) – A nested dictionary containing project variables and the part that can update each variable. Project variables can also be defined with a deprecated API where project_vars must be a flat (not-nested) dictionary and project_vars_part_name defines the part that can update all project variables.

  • custom_args (Any) – Any additional arguments defined by the application when creating a LifecycleManager.

  • partitions (list[str] | None) – A list of partitions.

  • filesystem_mounts (FilesystemMounts | None) – A dict of filesystem_mounts.

  • usrmerged_by_default (bool) – Whether the parts’ install dirs should be filled with usrmerge-safe directories and symlinks prior to a part’s build.

  • stage_packages_slice_support (bool) – Whether Chisel slices can be declared in the stage-packages key.

  • base (str)

  • base_layer_dir (Path | None)

  • base_layer_hash (bytes | None)

property alias_partition_dir: Path | None

Partition directory for the default alias partition.

property application_name: str

Return the name of the application using craft-parts.

property arch_build_for: str

The architecture we are building for.

property arch_build_on: str

The architecture we are building on.

property arch_triplet: str

Return the machine-vendor-os platform triplet definition.

property arch_triplet_build_for: str

The machine-vendor-os triplet for the platform we are building for.

property arch_triplet_build_on: str

The machine-vendor-os triplet for the platform we are building on.

property base: str

Return the project build base.

property base_layer_dir: Path | None

Return the directory containing the base layer (if any).

property base_layer_hash: bytes | None

Return the hash of the base layer (if any).

property cache_dir: Path

Return the directory used to store cached files.

property custom_args: list[str]

Return the list of custom argument names.

property default_filesystem_mount: FilesystemMount

Return the project’s default filesystem mount.

property default_partition: str | None

Get the “default” partition from a partition list.

property dirs: ProjectDirs

Return the project’s work directories.

property filesystem_mounts: FilesystemMounts | None

Return the project’s filesystem mounts.

get_project_var(name, *, raw_read=False)

Get the value of a project variable.

Variables must be consumed by the application only after the lifecycle execution ends to prevent unexpected behavior if steps are skipped.

Parameters:

  • name (str) – The project variable name.

  • raw_read (bool) – Whether the variable is read without access verifications.

Return type:

str

Returns:

The value of the variable.

Raises:

  • ValueError – If there is no project variable with the given name.

  • RuntimeError – If the variable is consumed during the lifecycle execution.

property host_arch: str

Return the host architecture used for debs, snaps and charms.

property is_cross_compiling: bool

Whether the target and host architectures are different.

is_default_partition(partition)

Check if given partition is the default one.

Parameters:

partition (str | None)

Return type:

bool

property is_default_partition_aliased: bool

Check if the default partition is aliased.

property overlay_alias_symlink: Path | None

Overlay directory for the default alias partition.

property parallel_build_count: int

Return the maximum allowable number of concurrent build jobs.

property partitions: list[str] | None

Return the project’s partitions.

property parts_alias_symlink: Path | None

Parts directory for the default alias partition.

property prime_alias_symlink: Path | None

Prime directory for the default alias partition.

property project_name: str | None

Return the name of the project using craft-parts.

property project_options: dict[str, Any]

Obtain a project-wide options dictionary.

property project_vars: ProjectVarInfo

Return the project vars.

property project_vars_part_name: str | None

Return the name of the part that can set project vars.

set_project_var(name, value, raw_write=False, *, part_name=None)

Set the value of a project variable.

Variable values can be set once. Project variables are not intended for logic construction in user scripts, setting it multiple times is likely to be an error.

Parameters:

  • name (str) – The project variable name.

  • value (str) – The new project variable value.

  • part_name (str | None) – If not None, variable setting is restricted to the named part.

  • raw_write (bool) – Whether the variable is written without access verifications.

Raises:

  • ValueError – If there is no custom argument with the given name.

  • RuntimeError – If a write-once variable is set a second time, or if a part name is specified and the variable is set from a different part.

Return type:

None

property stage_alias_symlink: Path | None

Stage directory for the default alias partition.

property stage_packages_slice_support: bool

Return whether Chisel slices may be declared in stage-packages.

property strict_mode: bool

Return whether this project must be built in ‘strict’ mode.

property target_arch: str

Return the target architecture used for debs, snaps and charms.

property usrmerged_by_default: bool

Return whether parts should be usrmerged by default.

class craft_parts.infos.PartInfo(project_info, part)

Part-level information containing project and part fields.

Parameters:

  • project_info (ProjectInfo) – The project information.

  • part (Part) – The part we want to obtain information from.

get_project_var(name, *, raw_read=False)

Get the value of a project variable.

Variables must be consumed by the application only after the lifecycle execution ends to prevent unexpected behavior if steps are skipped.

Parameters:

  • name (str) – The project variable name.

  • raw_read (bool) – Whether the variable is read without access verifications.

Return type:

str

Returns:

The value of the variable.

Raises:

  • ValueError – If there is no project variable with the given name.

  • RuntimeError – If the variable is consumed during the lifecycle execution.

property part_build_dir: Path

Return the subdirectory containing the part’s build tree.

property part_build_subdir: Path

Return the subdirectory in build containing the source subtree (if any).

property part_cache_dir: Path

Return the subdirectory containing this part’s cache directory.

property part_dependencies: Sequence[str]

Return the names of the parts that this part depends on.

property part_export_dir: Path

Return the subdirectory for internal artifact output.

property part_install_dir: Path

Return the subdirectory to install the part’s build artifacts.

property part_install_dirs: Mapping[str | None, Path]

Return the subdirectories to install build artifacts in partitions.

property part_name: str

Return the name of the part we’re providing information about.

property part_src_dir: Path

Return the subdirectory containing the part’s source code.

property part_src_subdir: Path

Return the subdirectory in source containing the source subtree (if any).

property part_state_dir: Path

Return the subdirectory containing this part’s lifecycle state.

property plugin_name: str

Return the name of the part’s plugin.

property project_info: ProjectInfo

Return the project information.

set_project_var(name, value, *, raw_write=False)

Set the value of a project variable.

Variable values can be set once. Project variables are not intended for logic construction in user scripts, setting it multiple times is likely to be an error.

Parameters:

  • name (str) – The project variable name.

  • value (str) – The new project variable value.

  • raw_write (bool) – Whether the variable is written without access verifications.

Raises:

  • ValueError – If there is no custom argument with the given name.

  • RuntimeError – If a write-once variable is set a second time, or if a part name is specified and the variable is set from a different part.

Return type:

None

class craft_parts.infos.StepInfo(part_info, step)

Step-level information containing project, part, and step fields.

Parameters:

  • part_info (PartInfo) – The part information.

  • step (Step) – The step we want to obtain information from.