Skip to main content

Managing SDKs

Zynx includes a built‑in SDK manager for handling cross‑compilation toolchains and sysroots.
This document explains what SDKs are, how they are stored, and how to work with them in day‑to‑day development.

What is an SDK?​

In the context of Zynx, an SDK (software development kit) is a pre‑packaged set of:

  • a target sysroot (headers, libraries, C runtime),
  • a compatible C toolchain configuration,
  • metadata describing the target triple and ABI expectations.

SDKs are used primarily for:

  • Cross‑compilation (e.g., building Linux/aarch64 binaries from macOS),
  • Reproducible builds, by decoupling toolchains from the host system,
  • Consistent ABI across developer machines and CI.

You can build projects either:

  • against the system toolchain (default), or
  • against a managed SDK installed via zynx sdk.

SDK Storage Layout​

By default, managed SDKs are stored under:

  • ~/.local/share/zynx/sdk/<triple>

where <triple> is a canonical target triple such as:

  • linux-x86_64-gnu
  • linux-aarch64-gnu
  • darwin-x86_64-apple

Note: SDK installation keys use platform-arch-abi (for example, linux-aarch64-gnu). This differs from common --target CLI input (arch-platform-abi, for example, aarch64-linux-gnu).

The exact directory layout inside each SDK is considered an implementation detail, but commonly includes:

  • bin/ – compiler and related tools (or shim wrappers),
  • include/ – C and platform headers,
  • lib/ – runtime libraries and startup objects,
  • metadata files used by zynx to construct correct --sysroot and -target flags.

You generally do not need to manipulate these directories manually; use the zynx sdk commands instead.

CLI Overview​

The SDK manager is accessed through:

zynx sdk <subcommand> [options]

Core subcommands:

  • add <triple> – install an SDK for the given target triple.
  • list – list all installed SDKs and their status.
  • del <triple> – remove an installed SDK.

All subcommands are idempotent and safe to run in CI.

Installing SDKs​

Installation from a Local Archive​

Install an SDK for a given target from a local archive:

zynx sdk add linux-aarch64-gnu --source /path/to/sdk-linux-aarch64-gnu-v1.tar.gz

This performs the following steps:

  1. Validates the provided target triple.
  2. Reads the SDK archive from --source.
  3. Unpacks it under ~/.local/share/zynx/sdk/<triple>.
  4. Records the installation in the local SDK registry.

If the SDK is already present, add is a no-op.

Note: remote SDK fetch is not implemented yet; zynx sdk add currently installs from a local archive passed with --source.

You can use this flow with previously downloaded or locally built bundles:

zynx sdk add linux-aarch64-gnu --source /path/to/sdk.tar.gz

Typical use cases:

  • Pre‑built SDKs checked into a mono‑repo tools directory.
  • Air‑gapped build environments where SDK bundles are distributed via offline media.
  • Custom internal SDKs for specialized hardware or patched libc variants.

zynx installs directly from the provided archive path.

Listing Installed SDKs​

To see which SDKs are currently installed:

zynx sdk list

A typical output might look like:

TRIPLE              LOCATION
linux-x86_64-gnu    ~/.local/share/zynx/sdk/linux-x86_64-gnu
linux-aarch64-gnu   ~/.local/share/zynx/sdk/linux-aarch64-gnu
darwin-x86_64-apple ~/.local/share/zynx/sdk/darwin-x86_64-apple

Use this to verify that the SDK required by your project’s target is available before running builds in CI or containers.

Removing SDKs​

To free disk space or remove obsolete targets, delete an SDK:

zynx sdk del linux-x86_64-gnu

This:

  • removes the corresponding directory under ~/.local/share/zynx/sdk/<triple>,
  • updates internal metadata so the SDK no longer appears in zynx sdk list.

Removing an SDK does not modify any project configuration; it only affects tool availability.

Project Configuration​

Projects opt into using managed SDKs via zynx.json.

Basic Target Configuration​

A minimal configuration:

{
  "zynx": {
    "target": {
      "arch": "aarch64",
      "platform": "linux",
      "abi": "gnu",
      "sdk": "managed"
    }
  }
}

Fields:

  • arch – CPU architecture (e.g., "x86_64", "aarch64").
  • platform – OS/platform (e.g., "linux", "darwin", "windows").
  • abi – ABI variant (e.g., "gnu", "apple", "msvc", "musl").
  • sdk – how to resolve the toolchain/sysroot:
    • "system" – use the host toolchain (default if omitted).
    • "managed" – require a managed SDK for this target.

The combination of arch, platform, and abi determines the target triple, which in turn decides which SDK directory Zynx will use.

System vs Managed Mode​

  • sdk: "system"
    Zynx expects the host system compiler and headers to be suitable for the target. This is convenient for native builds on development machines.

  • sdk: "managed"
    Zynx uses an SDK installed under ~/.local/share/zynx/sdk/<triple>.
    If the SDK is missing, zynx build will fail with a clear diagnostic, and you can resolve it with:

    zynx sdk add <triple> --source /path/to/sdk.tar.gz

Managed mode is recommended for:

  • CI pipelines,
  • cross‑platform release builds,
  • teams that need reproducible, hermetic environments.

Cross‑Compilation​

When targeting a different architecture or platform than the host, configure the project to use a managed SDK for that triple.

Example: Building Linux/aarch64 from macOS​

  1. Install the SDK:

     zynx sdk add linux-aarch64-gnu --source /path/to/sdk-linux-aarch64-gnu-v1.tar.gz

  2. Configure the project:

    {
      "zynx": {
        "target": {
          "arch": "aarch64",
          "platform": "linux",
          "abi": "gnu",
          "sdk": "managed"
        }
      }
    }

  3. Build:

    zynx build --profile release

Under the hood, Zynx:

  • infers the target triple from arch, platform, and abi,
  • locates the SDK under ~/.local/share/zynx/sdk/<triple>,
  • configures the underlying C compiler with appropriate --sysroot and -target flags,
  • links against the libraries provided by the SDK.

No manual cross‑toolchain setup is needed.

Using SDKs in CI and Containers​

For deterministic builds in CI or containerized environments:

  1. Pre‑provision SDKs in the build image, or install them during the pipeline using:

    zynx sdk add <triple> --source /path/to/sdk.tar.gz

  2. Commit zynx.json with a stable target configuration (including sdk: "managed").

  3. Avoid relying on host system toolchains; treat managed SDKs as the source of truth for headers and libraries.

A common pattern is:

# In Dockerfile or CI bootstrap
RUN zynx sdk add linux-x86_64-gnu --source /opt/sdk/sdk-linux-x86_64-gnu-v1.tar.gz

# Later in the pipeline
zynx build --profile release
zynx test

This ensures that every build uses the same headers, libraries, and ABI configuration.

Best Practices​

  • Pin targets in version control
    Always check zynx.json into your repository with explicit arch, platform, abi, and sdk values. Avoid relying on environment‑specific defaults.

  • Use managed SDKs for releases
    For production artifacts, prefer sdk: "managed" even if local development uses sdk: "system". This makes release builds reproducible and portable.

  • Align dev and CI targets
    Install the same SDKs locally and in CI. This minimizes “works on my machine” issues.

  • Clean up periodically
    If you experiment with many targets, periodically run zynx sdk list and remove unused SDKs with zynx sdk del <triple> to reclaim disk space.

Troubleshooting​

“No SDK found for target …”​

If zynx build reports that no managed SDK exists for a configured target:

  1. Check the target section in zynx.json for typos in arch, platform, or abi.

  2. Run:

    zynx sdk add <derived-triple> --source /path/to/sdk.tar.gz

  3. Re‑run zynx build.

“Using system toolchain instead of managed SDK”​

If you expected a managed SDK but see diagnostics indicating that the system toolchain is in use:

  • Confirm that sdk is set to "managed" in zynx.json.
  • Remove any local overrides that may force sdk: "system" (for example, environment‑specific configs or experimental flags).

With these tools and conventions, SDK management in Zynx should remain simple, explicit, and robust across a wide range of targets and deployment environments.