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='.')[source]

The project’s main work directories.

Parameters:
  • work_dir (Union[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)[source]

Get the stage directory for the given partition.

Parameters:

partition (Optional[str]) –

Return type:

Path

get_stage_dir(partition=None)[source]

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, **custom_args)[source]

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) –

property application_name: str

Return the name of the application using craft-parts.

Return type:

str

property arch_build_for: str

The architecture we are building for.

Return type:

str

property arch_build_on: str

The architecture we are building on.

Return type:

str

property arch_triplet: str

Return the machine-vendor-os platform triplet definition.

Return type:

str

property arch_triplet_build_for: str

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

Return type:

str

property arch_triplet_build_on: str

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

Return type:

str

property base: str

Return the project build base.

Return type:

str

property cache_dir: Path

Return the directory used to store cached files.

Return type:

Path

property custom_args: List[str]

Return the list of custom argument names.

Return type:

List[str]

property dirs: ProjectDirs

Return the project’s work directories.

Return type:

ProjectDirs

get_project_var(name, *, raw_read=False)[source]

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.

Return type:

str

property is_cross_compiling: bool

Whether the target and host architectures are different.

Return type:

bool

property parallel_build_count: int

Return the maximum allowable number of concurrent build jobs.

Return type:

int

property partitions: Optional[List[str]]

Return the project’s partitions.

Return type:

Optional[List[str]]

property project_name: Optional[str]

Return the name of the project using craft-parts.

Return type:

Optional[str]

property project_options: Dict[str, Any]

Obtain a project-wide options dictionary.

Return type:

Dict[str, Any]

property project_vars_part_name: Optional[str]

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

Return type:

Optional[str]

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

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.

Return type:

bool

property target_arch: str

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

Return type:

str

class craft_parts.infos.PartInfo(project_info, part)[source]

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)[source]

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.

Return type:

Path

property part_build_subdir: Path

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

Return type:

Path

property part_cache_dir: Path

Return the subdirectory containing this part’s cache directory.

Return type:

Path

property part_install_dir: Path

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

Return type:

Path

property part_name: str

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

Return type:

str

property part_src_dir: Path

Return the subdirectory containing the part’s source code.

Return type:

Path

property part_src_subdir: Path

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

Return type:

Path

property part_state_dir: Path

Return the subdirectory containing this part’s lifecycle state.

Return type:

Path

property project_info: ProjectInfo

Return the project information.

Return type:

ProjectInfo

set_project_var(name, value, *, raw_write=False)[source]

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)[source]

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.