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.
The steps a part goes through are as follows:
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
sourcepoints to a git repository, for example, the pull step will clone that repository.
build: constructs the part from the previously pulled components. The
pluginof a part specifies how it is constructed. The
mesonplugin, for example, executes
ninjato 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
afterkeyword. See Step dependencies for more information.
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
stagekeyword 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.
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
primestep 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
primefilter 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.
Finally, snap takes the entire contents of the
prime directory and packs 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.
snapcraft pull [<part-name>]
snapcraft build [<part-name>]
snapcraft stage [<part-name>]
snapcraft prime [<part-name>]
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.
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
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.
When running through its build steps, a part will use different working directories. These closely follow the step names for the lifecycle.
||the location of the source during the pull step|
||the working directory during the build step|
||contains the results of the build step and the stage packages.|
||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|
||shared by all parts, this directory holds the final components for the resulting snap.|
The following table gives an overview of which directories each step uses. The directories are specified by their environment variables.
|pull||downloads and retrieves the sources specified by the
|build||builds the sources in SNAPCRAFT_PART_BUILD and places the result in SNAPCRAFT_PART_INSTALL|
|organize||renames built files in SNAPCRAFT_PART_INSTALL|
|stage||copies built files from SNAPCRAFT_PART_INSTALL to the shared SNAPCRAFT_STAGE|
|prime||copies the staged files from the shared SNAPCRAFT_STAGE to the shared SNAPCRAFT_PRIME|
|snap||packs contents of SNAPCRAFT_PRIME into a snap and puts the snap in SNAPCRAFT_PROJECT_DIR|