starling-build/starling

starling.build · GitHub releases

Starling is an open software factory building world-class applications and the shared foundation behind them. A fast terminal, an office suite, a desktop, and a Swift SDK are part of the same project. The Linux desktop is where Starling began; it is one of the products we build today.

Our ambition is great software that everyone can use, study, change, and build on. Free to use. Open source. Starling's own code is Apache-2.0; the framework port and engine retain their upstream licenses (see Licensing).

The applications have different platform support and levels of maturity. Terminal has macOS, Windows, and Linux builds; Office can be tried directly in the browser; Desktop targets Ubuntu and Windows through WSL2. Follow each product's guide for its supported setup. These are actively developed projects, and features and interfaces continue to evolve.

Starling applications are written in Swift against the SDK in this repository. Native hosts use the Flutter engine's C core through starling-engine. Browser builds use Swift WebAssembly and the skwasm renderer. Applications can run in their own host windows or in the Starling desktop; they are not limited to a Linux desktop session.

The desktop brings the same approach to the whole workspace: its dock, menus, and windows are widgets in one tree. That architecture supports everyday app use, dedicated agent workspaces, and new views such as the 3D city.

Start with the SDK guide for the shared framework or the Office build guide for native and browser builds. Desktop setup is documented in docs/BUILDING.md; its common commands follow. Product-specific instructions take precedence over these Linux desktop commands.

Building both halves on a machine that has neither — toolchains, gclient, apt packages, timings, and the Ubuntu 26.04 workarounds — is docs/BUILDING.md. The short version follows.

Clone starling-engine next to this repo (a built one — see its README), then:

./bootstrap.sh            # creates the `engine` symlink -> ../starling-engine/engine

Every engine reference (bridge headers, libflutter_engine.so, libflutter_linux_drm.so, icudtl.dat) goes through that symlink; point it at any engine checkout with ./bootstrap.sh <path>.

cd shell && swift build -c release          # the shell (+ sdk as dependency)
cd apps/TerminalApp && swift build -c release   # each app is its own package

Engine C++ changes rebuild in the engine repo (ninja -C engine/src/out/...); the shell needs no relink — it binds only the engine's stable C API.

build/run-desktop.sh

Stages everything into one self-contained tree and runs the desktop from it — the same layout the package installs, so the dev loop exercises the shipping configuration. Needs the GPU free (no display manager or compositor). Uses the distro's Mesa; takes the unprivileged libseat path when a seat manager is reachable, else sudo. --no-stage reuses the existing .stage/.

Drive it and take screenshots with sudo build/shell-drive.py "dock settings" click "shot /tmp/x.png" (run with no args for the action list).

Do not run straight out of .build: child apps are spawned with LD_LIBRARY_PATH scrubbed and resolve libraries through their own $ORIGIN, so they only work when the libraries sit next to them — which is what staging does.

build/stage.sh [outdir]               # the assembled tree (defaults to .stage/)
build/package-desktop.sh [outdir]     # -> starling-desktop_<ver>_amd64.deb

stage.sh is the single definition of the layout; package-desktop.sh wraps its output with control metadata, the polkit policy, and the session entry. Prereqs: shell + apps built (swift build -c release), engine host_release built. The deb installs under /usr/lib/starling + /usr/share/starling and adds a "Starling" session to the login screen.

Packages are maintained as Starling <dev@starling.build> — the same project identity every commit here uses. Use it rather than a personal address for the Maintainer: field and anywhere else the project needs a contact.

This repo starts from a fresh snapshot, with no history before it. The code was developed in two private repos and re-imported here: the framework port and shell came from a working branch (flutter_swift/ → sdk/, apps/DesktopShellApp/ → shell/, apps/* → apps/), the packaging tools from a second one. Neither is public, so the pre-import history is not reachable — everything since is in this repo's log.

The framework port lives in this repo at sdk/ (it spent a stretch as the separate starling-sdk repo; that history came back with it as a subtree). It is a derivative of Flutter and keeps Flutter's licence. The C++ half lives in starling-engine, a fork of flutter/flutter whose starling branch carries the Starling delta on top of real upstream history.

Starling is a small amount of new code sitting on a great deal of other people's work. Named here with thanks — the legally required attributions are in NOTICE, but these deserve saying out loud:

• Flutter — the engine Starling runs on, and the framework design sdk/ is a port of. The embedder API is a genuinely well-drawn seam: it let a desktop shell supply its own surface, input and vsync without forking the renderer. Skia and Impeller do the drawing; Dart's tooling built the assets.
• Wayland and wayland-protocols — the compositor implements these. Kristian Høgsberg, Collabora, Intel, Red Hat, Samsung, Purism, Simon Ser, Jonas Ådahl, Kenny Levinsen and others wrote the protocol definitions in shell/Sources/WaylandServer/*-protocol.c.
• Mesa — EGL, GBM and the gallium drivers; every frame Starling puts on screen goes through it.
• libinput, libseat/seatd, libxkbcommon, libdrm, libevdev — Peter Hutterer, Kenny Levinsen and the freedesktop.org maintainers. libseat in particular is why the desktop runs unprivileged instead of as root.
• Swift — the language, and the corelibs Foundation, Dispatch and Observation the whole tree is written against.
• FreeType, HarfBuzz and ICU — text rendering and internationalisation, bundled inside the engine.
• PDFium — PDF rendering in the Image Viewer.
• Roboto Mono and Cupertino Icons for the typefaces and glyphs, and Daniel Lloyd Blunk-Fernández for the Golden Gate photograph the desktop ships as its wallpaper, via Unsplash.
• Debian and Ubuntu — the packaging conventions this ships under, and the distribution it is developed and tested on.

Starling's own contribution is the DRM/KMS embedder, the Wayland compositor, the Swift port of the framework, and the shell and apps built on top. None of it would exist without the above.

Starling's own code is Apache-2.0 (LICENSE). Two subtrees keep their upstream license instead, because they are ports and forks rather than original work — matching upstream keeps rebasing and contributing back possible:

NOTICE lists the third-party components the binaries redistribute — the Swift runtime, the Flutter engine and its bundled libraries, fonts, and the wallpaper. The .deb ships it as /usr/share/doc/starling-desktop/copyright.

No third-party application artwork is shipped: those logos are their owners' trademarks. When such an app is installed, the launcher reads its icon from the host at runtime via the freedesktop lookup, recorded into the app registry at install time (registry/); otherwise the shell draws its own generic glyph.

Apache-2.0 is not GPLv2-compatible, which costs nothing today: the shipped desktop links no GPL code at all (MIT/BSD, dynamically-linked LGPL for glibc and sd-bus, and the GCC runtime under its Runtime Library Exception).