craft_parts.overlays package

Submodules

• craft_parts.overlays.chroot module
  • chroot()
• craft_parts.overlays.errors module
  • OverlayChrootExecutionError
  • OverlayError
  • OverlayMountError
  • OverlayUnmountError
• craft_parts.overlays.layers module
  • LayerHash
    • LayerHash.for_part()
    • LayerHash.hex()
    • LayerHash.load()
    • LayerHash.save()
  • LayerStateManager
    • LayerStateManager.compute_layer_hash()
    • LayerStateManager.get_layer_hash()
    • LayerStateManager.get_overlay_hash()
    • LayerStateManager.set_layer_hash()
• craft_parts.overlays.overlay_fs module
  • OverlayFS
    • OverlayFS.mount()
    • OverlayFS.unmount()
  • is_opaque_dir()
  • is_whiteout_file()
• craft_parts.overlays.overlay_manager module
  • LayerMount
    • LayerMount.install_packages()
  • OverlayManager
    • OverlayManager.base_layer_dir
    • OverlayManager.cache_level
    • OverlayManager.download_packages()
    • OverlayManager.install_packages()
    • OverlayManager.mkdirs()
    • OverlayManager.mount_layer()
    • OverlayManager.mount_pkg_cache()
    • OverlayManager.refresh_packages_list()
    • OverlayManager.unmount()
  • PackageCacheMount
    • PackageCacheMount.download_packages()
    • PackageCacheMount.refresh_packages_list()
• craft_parts.overlays.overlays module
  • is_oci_opaque_dir()
  • is_oci_whiteout()
  • is_oci_whiteout_file()
  • oci_opaque_dir()
  • oci_whited_out_file()
  • oci_whiteout()
  • visible_in_layer()

Module contents

Overlay filesystem management and helpers.

class craft_parts.overlays.LayerHash(layer_hash)

Bases: object

The layer validation hash for a part.

Parameters:

layer_hash (bytes)

classmethod for_part(part, *, previous_layer_hash)

Obtain the validation hash for a part.

Parameters:

• part (Part) – The part being processed.

• previous_layer_hash (LayerHash | None) – The validation hash of the previous layer in the overlay stack.

Return type:

LayerHash

Returns:

The validation hash computed for the layer corresponding to the given part.

hex()

Return the current hash value as a hexadecimal string.

Return type:

str

classmethod load(part)

Read the part layer validation hash from persistent state.

Parameters:

part (Part) – The part whose layer hash will be loaded.

Return type:

LayerHash | None

Returns:

A layer hash object containing the loaded validation hash, or None if the file doesn’t exist.

save(part)

Save the part layer validation hash to persistent storage.

Parameters:

part (Part) – The part whose layer hash will be saved.

Return type:

None

class craft_parts.overlays.LayerMount(overlay_manager, top_part, pkg_cache=True)

Bases: object

Mount the overlay layer stack for step processing.

Parameters:

• overlay_manager (OverlayManager) – The overlay manager.

• top_part (Part) – The topmost part to mount.

• pkg_cache (bool) – Whether to mount the overlay package cache.

install_packages(package_names)

Install the specified packages on the local system.

Parameters:

package_names (list[str]) – The list of packages to install.

Return type:

None

class craft_parts.overlays.LayerStateManager(part_list, base_layer_hash)

Bases: object

An in-memory layer state management helper for action planning.

Parameters:

• part_list (list[Part]) – The list of parts in the project.

• base_layer_hash (LayerHash | None) – The verification hash of the overlay base layer.

compute_layer_hash(part)

Calculate the layer validation hash for the given part.

Parameters:

part (Part) – The part being processed.

Return type:

LayerHash

Returns:

The validation hash of the layer corresponding to the given part.

get_layer_hash(part)

Obtain the layer hash for the given part.

Parameters:

part (Part)

Return type:

LayerHash | None

get_overlay_hash()

Obtain the overlay validation hash.

Return type:

bytes

set_layer_hash(part, layer_hash)

Store the value of the layer hash for the given part.

Parameters:

• part (Part)

• layer_hash (LayerHash | None)

Return type:

None

class craft_parts.overlays.OverlayManager(*, project_info, part_list, base_layer_dir, cache_level)

Bases: object

Execution time overlay mounting and package installation.

Parameters:

• project_info (ProjectInfo) – The project information.

• part_list (list[Part]) – A list of all parts in the project.

• base_layer_dir (Path | None) – The directory containing the overlay base, or None if the project doesn’t use overlay parameters.

• cache_level (int) – The number of part layers to be mounted before the package cache.

property base_layer_dir: Path | None

Return the path to the base layer, if any.

property cache_level: int

The cache layer index above the base layer.

download_packages(package_names)

Download packages and populate the overlay package cache.

Parameters:

package_names (list[str]) – The list of packages to download.

Return type:

None

install_packages(package_names)

Install packages on the overlay area using chroot.

Parameters:

package_names (list[str]) – The list of packages to install.

Return type:

None

mkdirs()

Create overlay directories and mountpoints.

Return type:

None

mount_layer(part, *, pkg_cache=False)

Mount the overlay step layer stack up to the given part.

Parameters:

• part (Part) – The part corresponding to the topmost layer to mount.

• cache (pkg) – Whether the package cache layer is enabled.

• pkg_cache (bool)

Return type:

None

mount_pkg_cache()

Mount the overlay step package cache layer.

Return type:

None

refresh_packages_list()

Update the list of available packages in the overlay system.

Return type:

None

unmount()

Unmount the overlay step layer stack.

Return type:

None

class craft_parts.overlays.PackageCacheMount(overlay_manager)

Bases: object

Mount and umount the overlay package cache.

Parameters:

overlay_manager (OverlayManager) – The overlay manager.

download_packages(package_names)

Download the specified packages to the local system.

Parameters:

package_names (list[str]) – The list of packages to download.

Return type:

None

refresh_packages_list()

Update the list of available packages in the overlay system.

Return type:

None

craft_parts.overlays.is_oci_opaque_dir(path)

Verify if the given path corresponds to an opaque directory.

Parameters:

path (Path) – The path of the file to verify.

Return type:

bool

Returns:

Whether the given path is an overlayfs opaque directory.

craft_parts.overlays.is_oci_whiteout(path)

Verify if the given path corresponds to an OCI whiteout file.

Parameters:

path (Path) – The path of the file to verify.

Return type:

bool

Returns:

Whether the given path is an OCI whiteout file.

craft_parts.overlays.is_oci_whiteout_file(path)

Verify if the given path corresponds to an OCI whiteout file hiding a file.

Parameters:

path (Path) – The path of the file to verify.

Return type:

bool

Returns:

Whether the given path is an OCI whiteout file hiding a file.

craft_parts.overlays.is_opaque_dir(path)

Verify if the given path corresponds to an opaque directory.

Overlayfs opaque directories are represented by directories with the extended attribute trusted.overlay.opaque set to y.

Parameters:

path (Path) – The path of the file to verify.

Return type:

bool

Returns:

Whether the given path is an overlayfs opaque directory.

craft_parts.overlays.is_whiteout_file(path)

Verify if the given path corresponds to a whiteout file.

Overlayfs whiteout files are represented as character devices with major and minor numbers set to 0.

Parameters:

path (Path) – The path of the file to verify.

Return type:

bool

Returns:

Whether the given path is an overlayfs whiteout.

craft_parts.overlays.oci_opaque_dir(path)

Return the OCI opaque directory marker.

Parameters:

path (Path) – The directory to mark as opaque.

Return type:

Path

Returns:

The corresponding OCI opaque directory marker path.

craft_parts.overlays.oci_whited_out_file(whiteout_file)

Find the whited out file corresponding to a whiteout file.

Parameters:

whiteout_file (Path) – The whiteout file to process.

Return type:

Path

Returns:

The file that was whited out.

craft_parts.overlays.oci_whiteout(path)

Convert the given path to an OCI whiteout file name.

Parameters:

path (Path) – The file path to white out.

Return type:

Path

Returns:

The corresponding OCI whiteout file name.

craft_parts.overlays.visible_in_layer(lower_dir, upper_dir)

Determine the files and directories that are visible in a layer.

Given a pair of directories containing lower and upper layer entries, list the files and subdirectories in the lower layer that would be directly visible when the layers are stacked (i.e. the visibility is not “blocked” by an entry with the same name that exists in the upper directory). The upper directory may contain OCI whiteout files and opaque dirs.

Parameters:

• lower_dir (Path) – The lower directory.

• upper_dir (Path) – The upper directory.

Return type:

tuple[set[str], set[str]]

Returns:

A tuple containing the sets of files and directories that are visible.