Makefile Build System

A StartOS package’s Makefile carries only project-specific configuration and includes the shared build logic (s9pk.mk) that ships inside the SDK.

File Structure

my-service-startos/
└── Makefile     # Project-specific config; includes the SDK's s9pk.mk

The s9pk.mk file contains all the common build logic shared across StartOS packages. It ships inside the published SDK (@start9labs/start-sdk), so your Makefile includes it straight from node_modules — there’s nothing to vendor or copy into the package, and bumping the SDK delivers build-system fixes automatically.

Targets

Target	Description
`make` or `make all`	Build for all architectures (default)
`make x86`	Build for x86_64 only
`make arm`	Build for aarch64 only
`make riscv`	Build for riscv64 only
`make universal`	Build a single package containing all architectures
`make format`	Format `startos/` with the SDK’s Prettier config
`make install`	Build for your server’s architecture and install
`make clean`	Remove build artifacts

Variables

Variable	Default	Description
`ARCHES`	`x86 arm riscv`	Architectures to build by default
`TARGETS`	`$(ARCHES)`	Default build targets
`VARIANT`	(unset)	Optional variant suffix for package name
`TS_CHECK`	`npx tsc --noEmit`	Type-check step of the build gate
`FORMAT`	`npx prettier --write startos`	Formatting step of the build
`JS_BUNDLE`	`npx ncc build …`	Bundle step producing `javascript/index.js`

Makefile

The project Makefile is minimal and just includes s9pk.mk:

include node_modules/@start9labs/start-sdk/s9pk.mk

Adding Custom Targets

For services with variants (e.g., GPU support), extend the Makefile:

TARGETS := generic rocm
ARCHES := x86 arm

include node_modules/@start9labs/start-sdk/s9pk.mk

.PHONY: generic rocm

generic:
	$(MAKE) arches VARIANT=generic

rocm:
	ROCM=1 $(MAKE) arches VARIANT=rocm ARCHES=x86_64

This produces packages named myservice_generic_x86_64.s9pk and myservice_rocm_x86_64.s9pk.

Warning

Each variant must declare a distinct hardware requirement in the manifest (with at most one empty fallback), or publishing the second variant fails with a registry metadata mismatch. See GPU/Hardware Acceleration.

Overriding Defaults

Override variables before include node_modules/@start9labs/start-sdk/s9pk.mk:

# Build only for x86 and arm
ARCHES := x86 arm

include node_modules/@start9labs/start-sdk/s9pk.mk

Build Commands

# Build for all architectures
make

# Build for a specific architecture
make x86
make arm

# Install to StartOS server (requires a workspace whose .startos/config.yaml points at your device)
make install

# Format startos/ before committing
make format

# Clean build artifacts
make clean

Chaining Commands

You can chain multiple targets in a single invocation:

make clean arm          # Clean, then build ARM package
make clean install      # Clean, build for your server, then install
make clean universal    # Clean, then build a universal package

Prerequisites

Building signs the package with your workspace signing key, so the package must live inside a packaging workspace. If you haven’t created one yet, do that first — see Environment Setup — Set Up Your Packaging Workspace. Running make without a workspace fails with a message telling you to run start-cli s9pk init-workspace.

The build also needs the tools from Environment Setup — Docker (running), make, Node.js/npm, start-cli, git, and jq.

Installation

make install queries your StartOS device’s architecture, builds the current variant for that architecture when its inputs have changed or the artifact is missing, and installs that exact .s9pk. It resolves the device from your workspace .startos/config.yaml (the host.default profile).

Point your workspace at the device. Edit .startos/config.yaml (at the workspace root, not ~/.startos/config.yaml) so host.default is your device’s address:
```
host:
  default: https://your-device.local
```
Log in once. start-cli needs a session on the device:
```
start-cli auth login
```
Enter your StartOS master password when prompted.
Build and install for your device’s architecture:
```
make install
```
For packages with variants, use make install VARIANT=<variant> to build and install that variant. With VARIANT unset, this builds the package’s default variant. Other .s9pk files in the directory do not affect which artifact is installed.

Note

make install talks to the device over HTTPS, so your computer must trust the device’s certificate — the same trust you set up to open its web interface in a browser. If it isn’t trusted yet, import the device’s root CA into your system trust store; or, for a one-off, sideload the .s9pk through the web interface instead (see Sideloading), which needs no certificate setup.

To install to a device other than host.default, run start-cli directly with -H (a profile name or URL): start-cli -H prod package install -s <your-package>.s9pk.

Example Output

Building an ARM package:

$ make arm
   Re-evaluating ingredients...
   Packing 'albyhub_aarch64.s9pk'...
Build Complete!

  Alby Hub   v1.19.3:1
  Filename:   albyhub_aarch64.s9pk
  Size:       7M
  Arch:       aarch64
  SDK:        0.4.0-beta.36
  Git:        78c30ec776f6a9d55be3701e9b82093c866a382c

Note

If you have uncommitted changes, the Git hash will be shown in red.

Installing a package:

$ make install

Installing to working-finalist.local ...
Sideloading 100%
  Uploading...
  Validating Headers...
  Unpacking...

Keyboard shortcuts

Service Packaging