SmartOS smartos-live: Building the Platform Image

What smartos-live Builds, and Who Needs It

smartos-live solves a platform assembly problem rather than a single application-development problem. Its root build system produces a SmartOS platform image containing the illumos core operating system components, additional software required by illumos or SmartOS, and utilities with SmartOS-specific behavior under `projects/local/`.

The intended user is a developer or operator who must compile the SmartOS platform or change code that becomes part of its image. It is not presented as an installer for an already built SmartOS system. The build has strict environmental requirements: the documentation says compilation must happen on SmartOS, inside a non-global zone, using a SmartOS Platform Image dated 20220728 or newer. A supported image can be created in VMware, on an existing SmartOS machine, or another virtualization environment.

The distinction matters for adoption. If the goal is to run SmartOS in a virtual machine, smartos-live is the wrong layer. If the goal is to inspect or modify SmartOS-specific system tools such as `vmadm` and `imgadm`, or to rebuild the platform around changes in illumos-joyent, the repository is the correct starting point. Its scope is broad because the result is an operating system image rather than a developer package installed into an arbitrary Linux environment.

illumos-joyent, illumos-extra, and the Local Project Layer

The build is assembled from components with different responsibilities. The README identifies illumos-joyent as SmartOS's fork of illumos-gate and the source of the kernel, libraries, and user commands. Its code is placed under `projects/illumos`. The README also draws a firm boundary: SmartOS supports illumos-joyent, not stock illumos-gate.

illumos-extra supplies pinned or patched third-party software. Its stated categories include GNU binutils, which the platform requires for building, OpenSSL and libz, which are needed both to build and at run time, and software such as bash, curl, and Node.js that belongs in the resulting image. This component follows a different mechanism from the rest of the tree. Rather than modifying third-party source directly, the project applies maintained patches from directories conventionally named `Patches`.

A single package can require multiple builds. The README gives 32-bit, 64-bit, and bootstrap variants as examples, with names such as `zlib-1.2.3-64strap`. This accommodates software that cannot build in both architectures and tools that need to run against the host while constructing the platform image. Some upstream archives are being moved out of the repository and downloaded during setup, reducing repository size but adding an acquisition step that builders must account for.

The local-project system adds another dependency layer. Each project under `projects/local` must implement prescribed Makefile targets. The named examples include illumos-kvm, illumos-kvm-cmd, mdata-client, and ur-agent. These are separate repositories represented in the root tree, so a source checkout alone does not remove the need to resolve the configured project set.

Build Outputs, Proto Areas, and Manifest Boundaries

The repository layout exposes the build's central model: source trees, dependencies, projects, tools, manifests, and generated installation areas coexist in one root. The root Makefile defines separate directories for normal and bootstrap installations, manifests, boot content, images, and tests. These paths include `proto`, `proto.strap`, `manifest.d`, `boot.manifest.d`, `proto.boot`, `proto.images`, and `proto.tests`.

That separation reflects how a platform image is assembled. Sources and third-party archives do not become the final operating system simply by being present. The build processes them into destination roots, then combines those roots according to platform and boot manifests. The test staging area is also distinct from the image area, which keeps test inputs from being mistaken for production content merely because they share a build root.

The top-level Makefile also controls build parallelism. Its default is 8 for hosts with less than 16 GB of memory, while larger systems default to 128 jobs. This is not a cosmetic setting. SmartOS compiles a wide kernel and userland platform, and the available memory affects whether an aggressive job count is usable. The documented override is `MAX_JOBS=32`, passed through the normal `gmake` target syntax.

The Makefile includes `build.env` for normal goals. It makes an exception for the `check` goal so generic checks can be requested before `./configure` has produced that file. This is useful for automation, but it also means that `make check` acceptance is not equivalent to a configured full build. A successful quick check does not establish that the platform image can be produced.

Building smartos-live from the Documented Quickstart

The README's quickstart starts with a clone, configuration, full world build, live-image build, and inspection of `output/`. These commands describe the basic sequence, but they are only usable after the SmartOS-specific environment requirements have been met. Build on SmartOS, use a supported platform image, and enter a non-global zone before running them.

The following block fetches the repository and creates the initial build configuration:

git clone https://github.com/TritonDataCenter/smartos-live.git
cd smartos-live
./configure

The clone should place you in a directory named `smartos-live`, while `./configure` creates the environment expected by the main Makefile. The README notes that external storage is being used for some third-party contents, so configuration and subsequent setup must retain access to the required upstream downloads.

After configuration, build the world and then the live target:

gmake world
gmake live
ls output/

`gmake world` performs the broad platform build, and `gmake live` produces the SmartOS live image flow described by the quickstart. Listing `output/` is the first documented indication of generated artifacts. The repository does not provide a short output transcript or promise that this directory is the only build output, because intermediate installation and manifest trees remain elsewhere in the root.

On systems with substantial memory, parallelism can be selected explicitly:

gmake world live MAX_JOBS=32

The Makefile documents this override, but the memory available to the build zone still governs whether a chosen job count is practical. The documented quickstart does not provide a lightweight build for evaluation, so even a first complete build carries the cost of the full platform toolchain and dependency graph.

Maintenance Signals and Licensing Boundaries

The repository is not archived, and its last push was on 2026-10-12. That is recent activity in the repository record, although the project has no GitHub releases. There is therefore no release tag in this repository from which to derive an upgrade path or compare packaged artifacts. The README directs questions to the SmartOS discussion list and suggests that uncertain bugs can be filed on the smartos-live issue tracker even when another repository may ultimately own the fix.

That tracker guidance is important for maintenance cost. smartos-live is the root build system, while illumos-joyent, illumos-extra, and local projects have separate origins. A platform build can depend on several repositories, patched third-party archives, and downloaded source contents. The cost of upgrading is consequently not represented by changes to this root alone.

The repository metadata lists the overall project license as unknown. The root Makefile, however, carries a Common Development and Distribution License version 1.0 notice, also identified as CDDL 1.0, and points to the illumos copy of the CDDL text. That establishes a license statement for that file, not a conclusion covering every source archive, patch, downloaded dependency, or separately maintained repository in the assembled platform. License compatibility and redistribution obligations therefore need review at the individual component level rather than inference from the Makefile header.

Constraints and a Different Build Approach

The clearest failure mode is attempting the documented build in the wrong execution environment. The README requires SmartOS and a non-global zone, and it identifies Python 3 changes through OS-8397 as a platform constraint. A machine with a compiler or a Linux virtual machine is not equivalent to the documented build host. Attempting to reproduce the quickstart elsewhere can fail before project code is compiled.

A second constraint is breadth. `gmake world` is not an incremental package install. It coordinates illumos-joyent, illumos-extra, local projects, staged destinations, and manifests. Developers seeking a quick change to a single C program may find this excessive. The build's scope is justified when producing a coherent platform image, but it is a poor fit when the intended result is only a standalone binary.

The alternative approach is to use illumos-joyent directly as the illumos development tree. illumos-joyent still contains the core kernel, libraries, and user commands, but it does not by itself describe the full SmartOS-specific image assembly performed by smartos-live. Conversely, a conventional distribution build tool is not a direct substitute because this repository relies on its own Makefile conventions, local-project targets, proto areas, boot manifests, patch handling, and external source acquisition. The practical distinction is scope: illumos-joyent develops the OS core, while smartos-live coordinates that core with the additional software and SmartOS-specific image components.

Editorial conclusion

Adopt smartos-live when you need to build or modify the complete SmartOS platform image and have a supported SmartOS build environment available. Do not choose it for running SmartOS, building one isolated user-space package, or using stock illumos-gate, which the README explicitly says is unsupported. Before starting, verify the required SmartOS platform image, build inside a non-global zone, and confirm that the external local projects needed by the build can be resolved.

Frequently asked questions

Official sources

1. Issues
2. README
3. TritonDataCenter/smartos-live on GitHub