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 (Optional[Sequence[str]]) – 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 (Optional[str])

Return type:

Path

get_stage_dir(partition=None)

Get the stage directory for the given partition.

Parameters:

partition (Optional[str])

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, base_layer_dir=None, base_layer_hash=None, **custom_args)

Project-level information containing project-specific fields.

Parameters:

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

• project_name (Optional[str]) – 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 (Optional[ProjectDirs]) – The project work directories.

• project_name – The name of the project.

• project_vars_part_name (Optional[str]) – Project variables can be set only if the part name matches this name.

• project_vars (Optional[dict[str, str]]) – A dictionary containing the project variables.

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

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

• base (str)

• base_layer_dir (Optional[Path])

• base_layer_hash (Optional[bytes])

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 dirs: ProjectDirs

Return the project’s work directories.

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.

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 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_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 (Optional[str]) – 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 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.

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_install_dir: Path

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

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 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.