Skip to content

Latest commit

 

History

History
90 lines (63 loc) · 7.66 KB

parts-lifecycle.md

File metadata and controls

90 lines (63 loc) · 7.66 KB

Parts lifecycle

Parts, alongside plugins, are a key component in any Snapcraft project.

See Adding parts for a general overview of what parts are and how to use them, Scriptlets for details on how they can be scripted outside of snapcraft.yaml, and Parts lifecycle reference for the summarised information of this page.

All parts within a project, by means of the logic encoded the plugins they're using, all go through the same series of steps. Knowing these steps, and which directories are used for each step, can help when creating more advanced snaps, and when troubleshooting build issues.

Lifecycle steps⚓

The steps of a part goes through are as follows:

  1. pull: downloads or otherwise retrieves the components needed to build the part. You can use the source-* keywords of a part to specify which components to retrieve. If source points to a git repository, for example, the pull step will clone that repository.
  2. build: constructs the part from the previously pulled components. The plugin of a part specifies how it is constructed. The meson plugin, for example, executes meson and ninja to compile source code. Each part is built in a separate directory, but it can use the contents of the staging area if it specifies a dependency on other parts using the after keyword. See Step dependencies for more information.
  3. stage: copies the built components into the staging area. This is the first time all the different parts that make up the snap are actually placed in the same directory. If multiple parts provide the same file with differing contents, you will get a conflict. You can avoid these conflicts by using the stage keyword to enable or block files coming from the part. You can also use this keyword to filter out files that are not required in the snap itself, for example build files specific to a single part.
  4. prime: copies the staged components into the priming area, to their final locations for the resulting snap. This is very similar to the stage step, but files go into the priming area instead of the staging area. The prime step exists because the staging area might still contain files that are required for the build but not for the snap. For example, if you have a part that downloads and installs a compiler, then you stage this part so other parts can use the compiler during building. You can then use the prime filter keyword to make sure that it doesn't get copied to the priming area, so it's not taking up space in the snap. Some extra checks are also run during this step to ensure that all dependencies are satisfied for a proper run time. If confinement was set to classic, then files will be scanned and, if needed, patched to work with this confinement mode.
  5. pack: takes the entire contents of the prime directory and packs it into a snap.

Steps commands⚓

Each of these lifecycle steps can be run from the command line, and the command can be part specific or apply to all parts in a project.

  1. snapcraft pull [<part-name>]
  2. snapcraft build [<part-name>]
  3. snapcraft stage [<part-name>]
  4. snapcraft prime [<part-name>]
  5. snapcraft pack or snapcraft

Note that each command also executes the previous lifecycle steps, so snapcraft executes all the lifecycle steps chained together.

To access the part environment at any stage, add the --shell argument. For example, snapcraft prime --shell will run up to the prime step and open a shell. See Iterating over a build for more details.

Steps dependencies⚓

Each lifecycle step depends on the completion of the previous step for that part, so to reach a desired step, all prior steps need to have successfully run. By default, snapcraft runs the same lifecycle step of all parts before moving to the next step. However, you can change this behavior using the after keyword in the definition of a part in snapcraft.yaml. This creates a dependency chain from one part to another.

 grv:
    plugin: go
    go-channel: 1.11/stable
    after:
      - libgit2

In the above example, the part named grv will be built after the part named libgit2 has been successfully built and staged.

Overriding a step⚓

Each plugin defines the default actions that happen during a step. This behavior can be changed in two ways.

  • By using override-<step-name> in snapcraft.yaml. See Overriding steps for more details.
  • By using a local plugin. This can inherit the parent plugin or scaffolding from the original. See Local plugins for more details.

See Parts environment variables for a list of part-specific environment variables that can be accessed to help build a part.

Parts directories⚓

When running through its build steps, a part will use different working directories. These closely follow the step names for the lifecycle.

The directories are specified by their environment variables:

  • Snapcraft 7+: environment variables start with CRAFT_
  • Snapcraft 6, and earlier: variables start with SNAPCRAFT_ but are otherwise identical

See Parts environment variables for more details.

Environment variable Directory Purpose
CRAFT_PART_SRC parts/<part-name>/src the location of the source during the pull step
CRAFT_PART_BUILD parts/<part-name>/build the working directory during the build step
CRAFT_PART_INSTALL parts/<part-name>/install contains the results of the build step and the stage packages.
CRAFT_STAGE stage shared by all parts, this directory contains the development libraries, headers, and other components (e.g.; pkgconfig files) that need to be accessible from other parts
CRAFT_PRIME prime shared by all parts, this directory holds the final components for the resulting snap.