SDK concepts¶

SDKsLifecycle →

With SDKcraft, you can package and publish software dependencies as isolated SDKs to be used in a workshop definition by Workshop, instead of managing them system-wide or through container images. SDKs encapsulate all required functionality, keeping installations clean and limiting access to system-level capabilities. Publishers handle installation and updates for SDKs, freeing users from maintaining complex image definitions or configurations.

Most SDKs are designed by publishers and made available via the SDK Store, but some are specific to a particular project or user. A single workshop can include multiple SDKs from different sources. SDKs are distributed through channels similar to snap channels.

SDK definition¶

An SDK is described by two YAML files, one for building and one for installing:

sdkcraft.yaml, authored by the SDK publisher, is the build-time definition consumed by SDKcraft. See SDKcraft project definition.
sdk.yaml, generated by SDKcraft and embedded in the SDK package, is the runtime definition consumed by Workshop at install time. In-project SDKs skip the build step and author sdk.yaml directly.

A workshop pulls SDKs together through its own workshop.yaml.

A build-time definition looks like this:

sdkcraft.yaml¶

name: go
build-base: ubuntu@24.04
title: Go SDK
summary: The Go programming language
description: |
  Go is an open source programming language that enables the production of simple, efficient and reliable software at scale.
version: "1.25.1"
license: LGPL-2.1
platforms:
  amd64:
    build-on: [amd64]
    build-for: [amd64]
  arm64:
    build-on: [amd64]
    build-for: [arm64]
  riscv64:
    build-on: [amd64]
    build-for: [riscv64]

plugs:
  mod-cache:
    interface: mount
    workshop-target: /home/workshop/go/pkg/mod

parts:
  go:
    plugin: dump
    source: https://go.dev/dl/go$CRAFT_PROJECT_VERSION.linux-$CRAFT_ARCH_BUILD_FOR.tar.gz
    source-type: tar

Runtime hooks¶

Workshop and SDKcraft enable optional runtime hooks that let an SDK extend the workshop’s internal behavior. Hooks live in the hooks/ subdirectory next to the SDK definition and run as bash scripts at well-defined points during launch and refresh. See Runtime hooks for the contract, the per-hook environment, and how the SDK can talk back to the daemon with workshopctl. State that has to outlive an SDK refresh is handled by the save-state and restore-state hooks.

SDK platforms¶

Platforms describe where SDKs can be built and installed. Some SDKs include compiled code, which only certain families of CPUs will understand. Others depend on particular versions of software provided by the workshop’s base image.

The platforms section of the definition lists the platforms that the SDK supports. Each build corresponds to one of these platforms. By default, SDKcraft builds SDKs for every possible platform. This typically means all platforms with the same CPU architecture as the build machine.

Workshop and SDKcraft follow Debian’s naming scheme for CPU architectures. SDKs that don’t ship compiled binaries can use the all architecture instead.

SDK Store¶

The SDK Store is where an SDK stops being a local artifact and becomes something anyone can install. It is also the default source: an SDK listed in a definition by its bare name comes from the Store, and the try- and project- prefixes, or the reserved system name, are how a definition opts out of it. During workshop launch and workshop refresh, Workshop resolves only the unprefixed names against the Store.

A publisher reserves a name on the Store once. Names are global, and registration draws the ownership boundary: from then on, only the SDK’s publisher and assigned collaborators can upload or release under that name. Uploading pushes one built artifact and gets back a numbered revision, one per platform the SDK supports.

Revisions and channels are separate things, and the distinction is what the Store is built around. A revision is immutable; once uploaded, it’s a fixed artifact that never changes. A channel is a named pointer into revisions. Releasing a revision only moves that pointer, never rebuilding or re-uploading anything, which is why a revision can sit on the Store unreleased, present but invisible to everyone else.

For the user on the other side, this is why a definition names a channel rather than a revision. The channel is a standing choice of maturity, not a one-time version pin. The publisher moves the pointer forward as new revisions are released, and the workshop picks up the change on its next refresh without the definition being edited. A channel is optional; an SDK that omits one gets the default.

A channel is independent of a platform. The same channel name resolves to a different revision for each platform: requesting a channel installs the revision built for the workshop’s base and CPU architecture.

Two workshops that both request latest/stable therefore receive different builds when their bases or architectures differ. A workshop on an ubuntu@24.04 base and one on ubuntu@22.04 each install the latest/stable revision built for its own platform, not a single shared build.

Only Store SDKs have channels. The other kinds never reach the Store, so a channel means nothing to them. A published SDK is packaged once and consumed anywhere.

System SDK¶

Every workshop contains a special system SDK that exposes system resources through its slots. It cannot be installed from the SDK Store. Instead, it is automatically installed first during workshop launch and removed last during workshop remove to ensure internal consistency.

The purpose of the system SDK isn’t to add hooks or additional content; it’s only there to uniformly expose host system resources to other SDKs. As such, it can’t be removed by the user. It’s also the only SDK that can have mount interface slots on the host.

The uniformity of this approach lies in the fact that system resources and workshop resources are exposed using the same logic. You can also define additional plugs and slots for the system SDK, just as with any other SDK.

Sketch SDK¶

The sketch SDK is another special type of SDK. Like the system SDK, it’s unavailable from the SDK Store; instead, you define it inside the workshop using the workshop sketch-sdk command. Its purpose is to allow Workshop users to quickly make changes to a workshop beside the regular SDKs listed in the definition.

Unlike a regular SDK, the sketch SDK:

doesn’t carry any persistent data
doesn’t appear on the definition
is unique to the workshop where it was created

The sketch SDK can have hooks and use interfaces, which allows it to interact with other SDKs. Note that sketch is a reserved name, and the sketch SDK is always installed last.

Testing and trying SDKs¶

Once an SDK is packed, publishers have two ways to exercise it before upload.

The sdkcraft test command runs the SDK’s spread tests against a freshly packed SDK. These tests live under the SDK’s tests/ tree and are the publisher’s responsibility to author and maintain; SDKcraft only invokes the spread harness and reports results.

The sdkcraft try command allows publishers to test SDKs before uploading them to the Store. Once installed in a workshop, these SDKs behave identically to SDKs from the Store.

SDKcraft does not install SDKs in a workshop directly; it simply copies packed SDKs to a directory called the try area. Workshop looks in this directory when installing an SDK with the try- prefix.

The try area has no channels; only one version of an SDK can be tested at a time. However, this version can be tested in multiple workshops with different bases.

In-project SDKs¶

An in-project SDK resides within your project’s .workshop/ directory. Unlike regular SDKs, which are published and distributed through the SDK Store, in-project SDKs are specific to your project and are version-controlled alongside your project’s source code.

You can create an in-project SDK by ejecting a sketch SDK or by adding one manually, creating the appropriate directory structure with sdk.yaml and hooks. This approach allows you to customize the workshop to fit your project’s unique requirements, ensuring that all collaborators use the same environment and dependencies.

They are a good fit when your SDK includes project-specific dependencies, tools, interface connections, or configurations that should remain private to the project and not be published or reused elsewhere.