Parts environment variables

degville · July 12, 2019, 12:56pm

When building a part to construct a snap, Snapcraft creates the following sets of environment variables that can optionally be used by a part’s build mechanism:

Locating directories
- core | core18 | core20
- core22 | core24
Snapcraft configuration
Build flags
Plugin variables

Environment variables can be accessed via the override- keywords with shell commands and Scriptlets, or more generally within your project’s build infrastructure.

See Adding parts for a general overview of what parts are and how to use them, and for more details on how parts are built within the snapcraft environment, including build stages and the directories they use, see Parts lifecycle.

ⓘ For the various environment variables available to running snap applications, see Environment variables.

Locating directories

See Parts lifecycle and Parts directories for details on which directories are created and used when building a part.

core | core18 | core20

Snapcraft exposes the following directory related environment variables when building a part with bases core, core18, or core20. These can help when moving or locating files:


`SNAPCRAFT_PART_SRC`	absolute path to where a part’s sources are pulled. It’s also the part’s working directory for the pull step
`SNAPCRAFT_PART_BUILD`	absolute path to the sources used for the part’s build step. It is also the working directory of the build step.
`SNAPCRAFT_PART_INSTALL`	absolute path to the results of the part’s build step. It also contains the staged packages of that part.
`SNAPCRAFT_PRIME`	absolute path to where files are primed
`SNAPCRAFT_PROJECT_DIR`	absolute path to the root of the snapcraft project
`SNAPCRAFT_STAGE`	absolute path to where files are staged

core22 | core24

Snapcraft exposes the following directory-related environment variables when building with bases core22 and core24. These can help when moving or locating files:


`CRAFT_PART_SRC` `SNAPCRAFT_PART_SRC`	absolute path to where a part’s sources are pulled. It’s also the part’s working directory for the pull step
`CRAFT_PART_SRC_WORK` `SNAPCRAFT_PART_SRC`	absolute path to the part source subdirectory, if any. Defaults to the part source directory.
`CRAFT_PART_BUILD` `SNAPCRAFT_PART_BUILD`	absolute path to the sources used for the part’s build step. It is also the working directory of the build step.
`CRAFT_PART_BUILD_WORK` `SNAPCRAFT_PART_BUILD_WORK`	absolute path to the part build subdirectory in case of out-of-tree builds. Defaults to the part source directory.
`CRAFT_PART_INSTALL` `SNAPCRAFT_PART_INSTALL`	absolute path to the results of the part’s build step. It also contains the staged packages of that part.
`CRAFT_PRIME` `SNAPCRAFT_PRIME`	absolute path to where files are primed
`CRAFT_PROJECT_DIR` `SNAPCRAFT_PROJECT_DIR`	absolute path to the root of the snapcraft project
`CRAFT_STAGE` `SNAPCRAFT_STAGE`	absolute path to where files are staged
`CRAFT_OVERLAY`	absolute path the part’s layer directory during the `OVERLAY` step if overlays are enabled.

Snapcraft configuration

For all environment variables related to system architectures, Snapcraft uses the debian-style naming convention. See this page for a list of supported architectures.

#supported-architectures

core | core18

When building a part with bases core or core18, the following snapcraft environment variables are set:


`SNAPCRAFT_ARCH_TRIPLET`	The deb-style architecture triplet specified by `--target-arch`. If a target arch is not provided, then the architecture of the build-on platform is used.
`SNAPCRAFT_PARALLEL_BUILD_COUNT`	the preferred number of jobs the project is to be built with
`SNAPCRAFT_PROJECT_NAME`	the snapcraft project name as set by `name` in `snapcraft.yaml`
`SNAPCRAFT_PROJECT_VERSION`	the snapcraft project version as set by `version` in `snapcraft.yaml`
`SNAPCRAFT_PROJECT_GRADE`	the snapcraft project grade as set in `snapcraft.yaml`
`SNAPCRAFT_TARGET_ARCH`	the deb-style architecture that snap is being built for, e.g. “amd64”, “armhf”, “arm64”, etc.

core20

When building a part with base core20, the following snapcraft environment variables are set:


`SNAPCRAFT_ARCH_BUILD_FOR`	the deb-style architecture of the platform the snap is built for.
`SNAPCRAFT_ARCH_BUILD_ON`	the deb-style architecture of the platform the snap is built on.
`SNAPCRAFT_ARCH_TRIPLET_BUILD_FOR`	the deb-style architecture triplet of the platform the snap is built for
`SNAPCRAFT_ARCH_TRIPLET_BUILD_ON`	the deb-style architecture triplet of the platform the snap is built on
`SNAPCRAFT_ARCH_TRIPLET`	The deb-style architecture triplet specified by `--target-arch`. If a target arch is not provided, then the architecture of the build-on platform is used.
`SNAPCRAFT_PARALLEL_BUILD_COUNT`	the preferred number of jobs the project is to be built with
`SNAPCRAFT_PROJECT_NAME`	the snapcraft project name as set by `name` in `snapcraft.yaml`
`SNAPCRAFT_PROJECT_VERSION`	the snapcraft project version as set by `version` in `snapcraft.yaml`
`SNAPCRAFT_PROJECT_GRADE`	the snapcraft project grade as set in `snapcraft.yaml`
`SNAPCRAFT_TARGET_ARCH`	The deb-style architecture specified by `--target-arch`. If a target arch is not provided, then the architecture of the build-on platform is used.

core22

When building a part with base core22, the following snapcraft environment variables are set:


`CRAFT_ARCH_BUILD_FOR`	the deb-style architecture of the platform the snap is built for (available in snapcraft 8.0+)
`CRAFT_ARCH_BUILD_ON`	the deb-style architecture of the platform the snap is built on (available in snapcraft 8.0+)
`CRAFT_ARCH_TRIPLET_BUILD_FOR`	the deb-style architecture triplet of the platform the snap is built for (available in snapcraft 8.0+)
`CRAFT_ARCH_TRIPLET_BUILD_ON`	the deb-style architecture triplet of the platform the snap is built on (available in snapcraft 8.0+)
`CRAFT_ARCH_TRIPLET` `SNAPCRAFT_ARCH_TRIPLET`	The deb-style architecture triplet specified by `--target-arch`. If a target arch is not provided, then the architecture of the build-on platform is used. (deprecated in snapcraft 8.0, use `CRAFT_ARCH_TRIPLET_BUILD_FOR` instead)
`CRAFT_TARGET_ARCH` `SNAPCRAFT_TARGET_ARCH`	The deb-style architecture specified by `--target-arch`. If a target arch is not provided, then the architecture of the build-on platform is used. (deprecated in snapcraft 8.0, use `CRAFT_ARCH_BUILD_FOR` instead)
`CRAFT_PARALLEL_BUILD_COUNT` `SNAPCRAFT_PARALLEL_BUILD_COUNT`	the preferred number of jobs the project is to be built with
`CRAFT_PROJECT_NAME` `SNAPCRAFT_PROJECT_NAME`	the snapcraft project name as set by `name` in `snapcraft.yaml`
`SNAPCRAFT_PROJECT_VERSION`	the snapcraft project version as set by `snapcraft.yaml`
`SNAPCRAFT_PROJECT_GRADE`	the snapcraft project grade as set in `snapcraft.yaml`
`CRAFT_PART_NAME`	the part currently being processed, as set by the part’s name in `snapcraft.yaml`
`CRAFT_STEP_NAME`	the step currently being executed (i.e. `PRIME`)

core24

When building a part with base core24, the following snapcraft environment variables are set:


`CRAFT_ARCH_BUILD_FOR`	the deb-style architecture of the platform the snap is built for
`CRAFT_ARCH_BUILD_ON`	the deb-style architecture of the platform the snap is built on
`CRAFT_ARCH_TRIPLET_BUILD_FOR`	the deb-style architecture triplet of the platform the snap is built for
`CRAFT_ARCH_TRIPLET_BUILD_ON`	the deb-style architecture triplet of the platform the snap is built on
`CRAFT_PARALLEL_BUILD_COUNT` `SNAPCRAFT_PARALLEL_BUILD_COUNT`	the preferred number of jobs the project is to be built with
`SNAPCRAFT_PROJECT_NAME`	the snapcraft project name as set by `name` in `snapcraft.yaml`
`SNAPCRAFT_PROJECT_VERSION`	the snapcraft project version as set by `snapcraft.yaml`
`SNAPCRAFT_PROJECT_GRADE`	the snapcraft project grade as set in `snapcraft.yaml`
`CRAFT_PART_NAME`	the part currently being processed, as set by the part’s name in `snapcraft.yaml`
`CRAFT_STEP_NAME`	the step currently being executed (i.e. `PRIME`)

Build flags

The following specific build flags are also set:


`CFLAGS`	empty unless `after` is used in the part and headers are staged in the common include paths for which they will be included (i.e.; paths added with `-I`)
`CPPFLAGS`	same behavior as CFLAGS
`CXXFLAGS`	same behavior as CFLAGS
`LDFLAGS`	empty unless `after` is used in the part and headers are staged in the common library paths (i.e.; paths added with `-L`)
`PKG_CONFIG_PATH`	empty unless `after` is used in the part and .pc files are staged in the common pkgconfig paths

Plugin variables

A part’s plugin can add its own set of environment variables, or expand on the above build related flags.

The build-environment keyword can be used to either override the default environment variables or define new ones. Here is a basic example:

parts:
  hello-part:
    source: gnu-hello.tar.gz
    plugin: autotools
    build-environment:
      - CFLAGS: "$CFLAGS -O3"  # add -O3 to the existing flags
      - LDFLAGS: "-L$SNAPCRAFT_STAGE/non-standard/lib"

The above example will override default flags and search for libraries in a non-standard path.

For a complete list of environment variables, see Environment variables exposed by Snapcraft.

nteodosio · August 24, 2022, 5:27pm

I propose to change

The build-environment keyword can be used to override or expand on the default environment variables. Here is a basic example:

to

The build-environment keyword can be used to override the default environment variables or define new ones. Here is a basic example:

degville · August 25, 2022, 8:16am

Thanks for the suggestion. I’ve updated the text match your words.

nuccitheboss · September 20, 2022, 2:06am

Hey Graham! I hope that you are doing well. Browsing through this documentation page, I have noticed that the core22 hyperlink in the Snapcraft configuration section of the table of contents is broken; if you click on it, nothing happens. It does not take you to the core22 section of Snapcraft configuration.

All the other hyperlinks in the table of contents seem to be working however. Probably just some small misconfiguration in the heading.

degville · September 20, 2022, 1:58pm

Hello! Thanks so much for letting me know. This has now been fixed.

Saphyel · November 15, 2022, 12:07am

What would be the way to use secrets?

Let’s say you want users of your app has the credentials of their account as an ENV VAR, how should this work?

vvavrychuk · January 19, 2024, 4:59am

List should be properly indented, like this:

degville · January 19, 2024, 5:41pm

Very good point, thanks for taking the trouble to comment. This is fixed now. Thanks!

dilyn · June 10, 2024, 4:06pm

The language on this page is a little ambiguous. The only differentiator mentioned for what is supported and what isn’t is the base used. However, the version of snapcraft also matters. For instance, see snapcraft 7.x fails to replace new variables · Issue #4677 · canonical/snapcraft · GitHub

Instead, the particular version of SnapCraft which supports these variables should be mentioned. Perhaps a third column showing the range of versions supporting that variable?

@mr_cal for thoughts.

mr_cal · June 10, 2024, 8:10pm

Thanks @dilyn, adding another column made the table crowded, hopefully the change I made is readable

dilyn · June 10, 2024, 8:29pm

It’s workable. Thank you!

sed-i · October 7, 2024, 6:43am

Hi! From a quick search I didn’t stumble upon a list of valid values for “deb-style architecture”. Would be nice to have a link.

mr_cal · October 8, 2024, 12:30pm

Thanks for the suggestion, I added a link to the page that has a list of supported architectures in deb syntax.

@degville - is it possible to link to a specific heading if the heading is in markdown? That heading got converted from html to markdown and I’m not sure how to link to it now.

degville · November 7, 2024, 5:17pm

is it possible to link to a specific heading if the heading is in markdown? That heading got converted from html to markdown and I’m not sure how to link to it now.

Good question. This has only just become possible, and it’s actually the way we should now be linking to headings (now that the on-page navigation is part of the published docs). You can link to a markdown heading by adding #heading-name-with-spaces-replaced-by-hyphens. eg.

See [this page](/t/36758#supported-architectures) for a list of supported architectures.

(I’ve done the edit)