Snapcraft parts metadata

The main building blocks of a snap are parts. They are used to declare pieces of code that will be pulled into your snap package. The parts keys and values in snapcraft.yaml detail how parts are configured and built by the snapcraft command.

See Snapcraft top-level metadata and Snapcraft apps and services metadata for details on how apps and parts are configured within snapcraft.yaml.

parts

Type: dict

A set of independent building blocks.

These independent building blocks are known as parts, and consist of either code or pre-built packages.

parts.<part-name>

Type: dict

The name of the part building block.

<part-name> represents the specific name of a building block which can be then referenced by the command-line tool (i.e. snapcraft).

Keys for parts

The following are keys that can be used within parts. (for example, parts.<part-name>.plugin):

after

Type: list[string]

Ensures that all the <part-names> listed in after are staged before this part begins its lifecycle.

build-attributes

Type: enum

A list of named attributes to modify the behaviour of plugins.

Supported attributes:

  • debug: Plugins that support the concept of build types build in Release mode by default. Setting the ‘debug’ attribute requests that they instead build in debug mode.
  • keep-execstack: Do not remove the “executable stack” bit from ELF files.
  • no-patchelf: Do not patch ELF files, even when Snapcraft believes it is required (e.g. for classic snaps)
  • enable-patchelf: Do patch ELF files, even when Snapcraft does not believe it’s required (e.g. for strict snaps)
  • no-install: Do not run the install target provided by the plugin’s build system.
    (Only supported by the kbuild plugin)

For more information, refer to the output of snapcraft help plugins.

build-environment

Type: Array

A list of environment variable assignments that are applied during the build step, it is exported in order which allows for later values to override (or modify) earlier values.

This entry supports additional syntax, for more information refer to Advanced grammar.

parts:
  _part_name_:
    build-environment:
      - LANG: C.UTF-8
      - LC_ALL: C.UTF-8

build-packages

Type: list[string]

A list of packages required to build a snap.

Packages are installed using the host’s package manager, such as apt or dnf, and are required for <part-name> to build correctly. This entry supports additional syntax, for more information refer to Advanced grammar.

Example: [ libssl-dev, libssh-dev, libncursesw5-dev]

build-snaps

Type: list[string]

A list of snap names to install that are necessary to build <part-name>.

If a specific channel is required, the syntax is of the form <snap-name>/<channel>. This entry supports additional syntax, for more information refer to Advanced grammar

Example: build-snaps: [go/1.13/stable]

disable-parallel

Type: boolean

Whether to disable parallelism for the build plugins.

filesets

Type: list[string]

A key to represent a group of files or a single file.

Filesets do not currently work when building snaps with core22 base snaps and Snapcraft 7.x .

See Snapcraft filesets for further details.

organize

Type: dict

A map of files to rename.

In the key/value pair, the key represents the path of a file inside the part and the value represents how the file is going to be staged.

Example: bin/snapcraftctl: bin/scriptlet-bin/snapcraftctl

override-build

Type: multiline string

Replaces a plugin’s default build process with a script.

The shell script defined here replaces the build step of the plugin, defined in parts.<part-name>.plugin. The working directory is the base build directory for the given part. The defined script is run with /bin/sh and set -e. A set of Environment Variables will be available to the script.

To run Snapcraft’s original build implementation from within override-build, run snapcraftctl build. This can be run before or after any custom script or omitted entirely.

override-prime

Type: multiline string

Replaces a plugin’s default prime process with a script.

The shell script defined here replaces the prime step of the plugin, defined in parts.<part-name>.plugin. The working directory is the base prime directory for the given part. The defined script is run with /bin/sh and set -e. A set of Environment Variables will be available to the script.

To run Snapcraft’s original prime step implementation from within override-prime, run snapcraftctl prime. This can be run before or after any custom script or omitted entirely.

override-pull

Type: multiline string

Replaces a plugin’s default pull process with a script.

The shell script defined here replaces the pull step of the plugin, defined in parts.<part-name>.plugin. The working directory is the base pull directory for the given part. The defined script is run with /bin/sh and set -e. A set of Environment Variables will be available to the script.

To run Snapcraft’s original pull stage implementation from within override-pull, run snapcraftctl pull. This can be run before or after any custom script or omitted entirely.

override-stage

Type: multiline string

Replaces a plugin’s default stage process with a script.

The shell script defined here replaces the stage step of the plugin, defined in parts.<part-name>.plugin. The working directory is the base stage directory for the given part. The defined script is run with /bin/sh and set -e. A set of Environment Variables will be available to the script.

To run Snapcraft’s original stage implementation from within override-stage, run snapcraftctl stage. This can be run before or after any custom script or omitted entirely.

parse-info

Type: list[string]

Defines content to adopt when using external metadata.

Each entry is a relative path to a supported metadata file from the part source, build or install directory (SNAPCRAFT_PART_SRC, SNAPCRAFT_PART_BUILD, SNAPCRAFT_PART_INSTALL).

See Using external metadata for more details.

plugin

Type: string

The plugin to drive the build process.

Every part drives its build through a plugin, this entry declares the plugin that will drive the build process for <part-name>. Refer to snapcraft plugins for more information on the available plugins and the specific attributes they add to the parts.<part-name>. namespace.

prime

Type: list[string]

A list of files from <part-name> to prime.

Rules applying to the list here are the same as those of filesets. Referencing of fileset keys is done with a $ prefixing the fileset key, which will expand with the value of such key.

source

Type: string

A URL or path to a source tree to build.

This can be a local path or remote and can refer to a directory tree, a compressed archive, or a revision control repository. This entry supports additional syntax, for more information refer to Advanced grammar

source-branch

Type: string

Work on a specific branch for source repositories under version control.

source-checksum

Type: string

Used when source represents a file.

Takes the syntax <algorithm>/<digest>, where <algorithm> can be any of: md5, sha1, sha224, sha256, sha384, sha512, sha3_256, sha3_384 or sha3_512. When set, the source is cached for multiple uses in different snapcraft projects.

source-commit

Type: string

Work on a specific commit for source repositories under version control.

Cannot be an abbreviation. Requires the full 40-character SHA-1 hash for the commit.

source-depth

Type: integer

Depth of history for sources using version control.

Source repositories under version control are cloned or checked out with full history. Specifying a depth will truncate the history to the specified number of commits.

source-subdir

Type: string

A path within the source to set as the working directory when building. The build will not be able to access files outside of this location, such as one level up.

source-submodules

Type: dict

Configure which submodules to fetch from the source tree in snapcraft.yaml with source-submodules: <list-of-submodules>

When source-submodules is defined, only the listed submodules are fetched:

parts:
  git-test:
    plugin: dump
    source-type: git
    source: git@github.com...
    source-submodules:
      - submodule_1
      - dir1/submodule_2

If source-submodules is defined and the list is empty, no submodules are fetched:

parts:
  git-test:
    plugin: dump
    source-type: git
    source: git@github.com...
    source-submodules: []

If source-submodules is not defined, all submodules are fetched (default behaviour).

source-tag

Type: string

Work on a specific tag for source repositories under version control.

source-type

Type: enum

Used when the type of source entry cannot be detected.

Can be one of the following: [bzr|deb|git|hg|local|mercurial|rpm|subversion|svn|tar|zip|7z]

stage

Type: list[string]

A list of files from <part-name> to stage.

Rules applying to the list here are the same as those of filesets. Referencing of fileset keys is done with a $ prefixing the fileset key, which will expand with the value of such key.

stage-packages

Type: list[string]

A list of packages required at runtime by a snap.

Packages are required by <part-name> to run. They are fetched using the host’s package manager, such as apt or dnf, and are unpacked into the snap being built. This entry supports additional syntax, for more information refer to Advanced grammar.

Example: [python-zope.interface, python-bcrypt]

stage-snaps

Type: list[string]

A list of snaps required at runtime by a snap.

Snaps are required by <part-name> to run. They are fetched using snap download, and are unpacked into the snap being built. This entry supports additional syntax, for more information refer to Advanced grammar.

Example: [hello, black/latest/edge]

1 Like

I would like to ask about more info of the build-attributes key, from snapcraft help plugins:

  - build-attributes: [attribute1, attribute2]

    A list of special attributes that affect the build of this specific part.
    Supported attributes:

      - no-system-libraries:
        Do not automatically copy required libraries from the system to satisfy
        the dependencies of this part. This might be useful if one knows these
        dependencies will be satisfied in other manner, e.g. via content
        sharing from other snaps.

      - no-install:
        Do not run the install target provided by the plugin's build system.

        Supported by: kbuild

      - debug:
        Plugins that support the concept of build types build in Release mode
        by default. Setting the 'debug' attribute requests that they instead
        build in Debug mode.

Should this instead be override-build?

1 Like

You’re absolutely right - thanks. I’ve updated above and the single reference page. It was cut accidentally with some overzealous vim macros.

2 Likes

The Snapcraft plugins page doesn’t mention anything regarding the build-attributes property, it should be fixed.

This could use an update. Prepare, build, and install are all deprecated. See notices

Snapcraft is failing indicating additional properties are not allowed and prepare was unexpected. There is no mention that prepare is deprecated, so there’s a good chance the snapcraft user is going to spend a bunch of time trying to find out what’s wrong with their snapcraft.yaml, confirming it all conforms to the documentation, and getting nowhere.


1 Like

@degville see the above post about dropping or at least mentioning the deprecation of install build and prepare. AFAIK they are not available at all in snapcraft 3.x and only in 2.x

1 Like

Thanks for flagging this @ijohnson, @tejohnso (and @Lin-Buo-Ren). I’ll fix this now.

There’s no mention of snapcraftctl build inside override-build.

I’ve added the missing disable-parallel key and it may need some polish.

1 Like

Can we have some clarity on if/how globbing works? For example the organize keyword documentation doesn’t mention globbing, but the organize example in https://snapcraft.io/docs/dump-plugin suggests that it is possible.

The list claims that “install” is deprecated, but the accompanying comment claims it’s been obsolete for some time. So which is it? Deprecated or obsolete. Can’t be both. :slight_smile:

Good point, thanks! I’ve removed it entirely as I think there’s been enough time.

Issue

I don’t know how I found this, but it looks like the anchor for the build-snaps header is broken. Unlike the other headings, when I click on the anchor nothing happens.

Solution

Comparing this anchor against another anchor, it looks like there is a missing space between the anchor and the heading text. Analyzing the raw markdown, you can see the discrepancy in the spacing:

  • disable-parallel: ### disable-parallel [⚓](#heading--disable-parallel)
  • build-snaps: ### build-snaps[⚓](#build-snaps)

Changing the build-snaps markdown to the following should fix the issue with the anchor:

### build-snaps [⚓](#build-snaps)

Thanks so much for finding this, and letting us know. I’ve fixed the broken anchor. The problem was actually a missing heading-- which is a weird requirement for anchors through Discourse (briefly discussed here: Documentation guidelines). Thanks again!

1 Like

I think we can finally remove the “prepare” key.

Done. Thank you for letting us know!

I would add to the “filesets” entry that this key is not supported when using SC7 with core22 snaps, and not make the reader traverse to the filesets page to learn this.

Thanks. I’ve added the caveat as you suggested.

for source-commit, could we add a note that it must be the full 40 character commit (not an abbreviation)? That is a limitation in the git fetch origin COMMIT command used here, but (for me at least) an easy thing to overlook