stack - Symbolic Element for dependency grouping

Stack elements are simply a symbolic element used for representing a logical group of elements.

All dependencies declared in stack elements must always be both build and runtime dependencies.

Example:

kind: stack

# Declare all of your dependencies in the `depends` list.
depends:
- libc.bst
- coreutils.bst

Note

Unlike other elements, whose cache keys are a unique identifier of the contents of the artifacts they produce, stack elements do not produce any artifact content. Instead, the cache key of an artifact is a unique identifier for the assembly of its own dependencies.

Using intermediate stacks

Using a stack element at intermediate levels of your build graph allows you to abstract away some parts of your project into logical subsystems which elements can more conveniently depend on as a whole.

In addition to the added convenience, it will allow you to more easily change the implementation of a subsystem later on, without needing to update many reverse dependencies to depend on new elements, or even allow you to conditionally implement a subsystem with various implementations depending on what project options were specified at build time.

Using toplevel stacks

Stack elements can also be useful as toplevel targets in your build graph to simply indicate all of the components which need to be built for a given system to be complete, or for your integration pipeline to be successful.

Checking out and deploying toplevel stacks

In case that your software is built remotely, it is possible to checkout the built content of a stack on your own machine for the purposes of inspection or further deployment.

To accomplish this, you will need to know the cache key of the stack element which was built remotely, possibly by inspecting the remote build log or by deriving it with an equally configured BuildStream project, and you will need read access to the artifact cache server which the build was uploaded to, this should be configured in your user configuration file.

You can then checkout the remotely built stack using the bst artifact checkout command and providing it with the artifact name:

Example:

bst artifact checkout --deps build --pull --integrate \
    --directory `pwd`/checkout \
    project/stack/788da21e7c1b5818b7e7b60f7eb75841057ff7e45d362cc223336c606fe47f27

Note

It is possible to checkout other elements in the same way, however stack elements are uniquely suited to this purpose, as they cannot have runtime only dependencies, and consequently their cache keys are always a unique representation of their collective dependencies.