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.

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 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 white- or black-list 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.

Finally, snap takes the entire contents of the prime directory and pack it into a snap.

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

Step 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 a local plugin. This can inherit he 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:

  • parts/<part-name>/src: the location of the source during the pull step
  • parts/<part-name>/build: the working directory during the build step
  • parts/<part-name>/install: a private directory for install components during the build step
  • 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
  • prime: also shared across all parts, this directory holds the final components for the resulting snap.

Last updated 2 days ago. Help improve this document in the forum.