SDK concepts¶

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.

When installing an SDK, Workshop will check its platform metadata for compatibility.

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

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.