toolchain

package
v0.0.14 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 10, 2026 License: MIT Imports: 50 Imported by: 0

Documentation

Overview

Package toolchain builds Nimbus Native apps for iOS and Android. Single directory apps (the examples) build with the platform tools directly: go build (c-archive / c-shared), Xcode's clang and swiftc, the NDK's clang, and the Android SDK's aapt2, d8, zipalign and apksigner. Projects made by New hold real Xcode and Gradle projects, which call Lib to build the Go side. No gomobile either way.

Index

Constants

View Source 
const (
	OnSimulator = iota // shares this Mac's network
	OnEmulator         // reaches this Mac at 10.0.2.2
	OnPhone            // reaches this Mac over the local network
)

Where a built app runs, for LocalServer.

View Source 
const IOSGeneratedSwift = "native/ios/Runner/Generated/NimbusGenerated.swift"

IOSGeneratedSwift is where a project's generated Swift lives.

View Source 
const MinAndroidAPI = 26

MinAndroidAPI is the lowest Android version (API 26, Android 8.0) apps run on.

View Source 
const MinIOS = "15.0"

MinIOS is the lowest iOS version apps run on.

View Source 
const RoutesFile = "routes_gen.go"

RoutesFile is the generated table, in the pages package.

Variables

View Source 
var (
	IOSSimulator = IOSTarget{"iphonesimulator", "arm64-apple-ios" + MinIOS + "-simulator"}
	IOSDevice    = IOSTarget{"iphoneos", "arm64-apple-ios" + MinIOS}
)
View Source 
var AndroidABIs = map[string]AndroidABI{
	"arm64-v8a":   {"arm64-v8a", "arm64", "", "aarch64-linux-android"},
	"armeabi-v7a": {"armeabi-v7a", "arm", "7", "armv7a-linux-androideabi"},
	"x86_64":      {"x86_64", "amd64", "", "x86_64-linux-android"},
	"x86":         {"x86", "386", "", "i686-linux-android"},
}
View Source 
var ErrKitUpdated = errors.New("the native kit was updated to match go.mod; build again")

ErrKitUpdated means the project's copy of the host kit changed to match the nimbus-native version in go.mod; the IDE has to build again.

View Source 
var Templates = []string{"counter"}

Templates are the apps New can start from.

Functions

func AddFont added in v0.0.9 

func AddFont(root, file, family string) (string, error)

AddFont copies a .ttf or .otf into the project's iOS app (Runner/Fonts, registered at launch), Android app (assets/fonts) and, in a project with a Nimbus server, public/fonts for the web, named family. It returns the family name to use in Style.FontFamily.

func AndroidProjectID 

func AndroidProjectID(root string) (string, error)

AndroidProjectID is the application id in native/android's app module.

func Choose added in v0.0.13 

func Choose(question string, options []string) (int, error)

Choose asks which of options to use, with the arrow keys. It needs a terminal on stdin; the answer stays on screen.

func DefaultIcon added in v0.0.8 

func DefaultIcon(fg color.RGBA) image.Image

DefaultIcon is a new project's icon: a white plus on fg, on a transparent square (the background color fills behind it).

func Errorf added in v0.0.13 

func Errorf(w io.Writer, format string, args ...any)

Errorf writes a failure. Only its first line is colored: the rest is usually a tool's own output, there to be read.

func HasServer added in v0.0.13 

func HasServer(root string) bool

HasServer reports whether the project has a Nimbus server of its own.

func IOSProjectID 

func IOSProjectID(root string) (string, error)

IOSProjectID is the bundle id in native/ios's Xcode project.

func IOSTeam added in v0.0.4 

func IOSTeam(root, want string) (string, error)

IOSTeam is the Apple team that signs device builds: want (the -team flag or NIMBUS_IOS_TEAM), else the Xcode project's own, else the only team signed in to Xcode.

func Infof added in v0.0.13 

func Infof(w io.Writer, format string, args ...any)

Infof writes a line of what is happening.

func InstalledKotlinc 

func InstalledKotlinc() string

InstalledKotlinc is the kotlinc that Kotlinc would use, without downloading: "" if it is not installed yet.

func IsProject 

func IsProject(dir string) bool

IsProject reports whether dir is a project made by `nimbus native new`: a Go module with native/ios or native/android.

func LaunchColor added in v0.0.8 

func LaunchColor(root string) color.RGBA

LaunchColor is the project's current launch screen color (white if unset).

func LocalServer added in v0.0.13 

func LocalServer(root string, target int) string

LocalServer is where an app on target reaches the project's server on this Mac, or "" when this Mac isn't on a network.

func NameIOSBundle added in v0.0.13 

func NameIOSBundle(root string) error

NameIOSBundle gives a project from before this its app's name on iOS.

func Panel added in v0.0.13 

func Panel(w io.Writer, title, body string)

Panel writes a title and body in a rounded box.

func ParseColor added in v0.0.8 

func ParseColor(s string) (color.RGBA, error)

ParseColor reads "#rrggbb" (or "rrggbb").

func ReadIcon added in v0.0.8 

func ReadIcon(path string) (image.Image, error)

ReadIcon loads a square PNG or JPEG, ideally 1024×1024 or larger.

func SaveIOSTeam added in v0.0.6 

func SaveIOSTeam(root, team string) error

SaveIOSTeam writes team into the project's Xcode app target, so Xcode and later device builds sign with it without asking.

func ServerSet added in v0.0.13 

func ServerSet() bool

ServerSet reports whether an address was given for this build.

func SetServer added in v0.0.13 

func SetServer(url string) error

SetServer has this process's builds use url as the app's server.

func Successf added in v0.0.13 

func Successf(w io.Writer, format string, args ...any)

Successf writes a line that something worked.

func Warnf added in v0.0.13 

func Warnf(w io.Writer, format string, args ...any)

Warnf writes a line that something needs attention.

func WriteIcons added in v0.0.8 

func WriteIcons(root string, icon image.Image, bg, launch color.RGBA) error

WriteIcons writes the project's app icons from icon over bg, and sets its launch screens' background to launch.

func XcodeTeams added in v0.0.6 

func XcodeTeams() map[string]string

XcodeTeams are the teams of the accounts signed in to Xcode, by id.

Types

type AndroidABI 

type AndroidABI struct {
	Name   string // arm64-v8a
	GOARCH string // arm64
	GOARM  string // only for arm
	Clang  string // NDK compiler prefix, without the API level
}

AndroidABI maps an Android ABI to the Go architecture and NDK compiler.

type AndroidDevice added in v0.0.6 

type AndroidDevice struct {
	Serial   string
	Model    string
	Emulator bool
}

AndroidDevice is a phone, tablet or emulator adb can reach.

type AndroidLib 

type AndroidLib struct {
	ABIs   []string
	JNI    string // jniLibs directory: <abi>/libnimbusapp.so
	Kotlin string // source directory for the generated Kotlin
	Kit    string // the project's copy of the kit's Kotlin sources ("" skips)
}

AndroidLib says what LibAndroid builds, usually from Gradle.

type App 

type App struct {
	Dir  string // absolute
	Name string // display and executable name, e.g. "Hello"
	ID   string // bundle id / application id, e.g. "space.nimbusgo.hello"

	// Root is the project's module root; empty for a single directory.
	// Schemas anywhere under it are generated, and build output goes there.
	Root string

	// For dev shells: the Go package compiled into the app instead of Dir,
	// whose schemas also count toward the hash.
	GoDir string
}

App is the app being built, in one of two layouts. A single directory (the examples): 

<dir>/*.go             the Go app (package main)
<dir>/ios/*.swift      the iOS host code
<dir>/android/*.kt     the Android host code (package <id>, MainActivity)

or a project made by `nimbus native new`, where Root is the Go module and Dir its phone entry package: 

<root>/app/mobile      the phone's package main (Dir)
<root>/native/ios      an Xcode project
<root>/native/android  a Gradle project

func LoadApp 

func LoadApp(dir, name, id string) (*App, error)

LoadApp describes the app in dir. Name and ID default from the directory name when empty.

func LoadProject 

func LoadProject(root, entry, id string) (*App, error)

LoadProject describes the project whose Go module is at root, with its phone entry package at root/entry. id may be empty; IOSProjectID and AndroidProjectID read it from the native projects.

func (*App) BuildDir 

func (a *App) BuildDir(platform string) string

BuildDir is where build output for a platform goes.

type DevTarget added in v0.0.7 

type DevTarget struct {
	Phone *IOSPhone
	Team  string // signs the phone build
	// NoServer leaves a project's Nimbus server (go run .) out of dev mode.
	NoServer bool
}

DevTarget is where dev mode runs its shell: the simulator or the device Env.Serial names by default, or an iPhone or iPad.

type Env 

type Env struct {
	Verbose bool
	Out     io.Writer

	Repo string // the nimbus-native module checkout (hosts/, bridge/include/)

	Xcode string // `xcode-select -p`

	AndroidSDK string
	NDK        string // newest ndk/<version>
	BuildTools string // newest build-tools/<version>
	AndroidJar string // newest platforms/android-*/android.jar
	Javac      string
	Keystore   string // debug keystore used to sign dev builds

	// Serial is the Android device to use (adb -s); empty for adb's default.
	Serial string
}

Env is the set of platform tools found on this machine. Empty fields mean the tool was not found; Doctor explains what is missing.

func Detect 

func Detect(appDir string) *Env

Detect finds the platform tools. It never fails; Doctor reports gaps.

func (*Env) AddPluginModules added in v0.0.13 

func (e *Env) AddPluginModules(a *App, modules []string, values map[string]string, out io.Writer) error

AddPluginModules downloads plugin modules, stages their native handlers in the project, adds the Go dependency, then enables them like bundled plugins.

func (*Env) AddPlugins added in v0.0.13 

func (e *Env) AddPlugins(a *App, names []string, values map[string]string, out io.Writer) error

AddPlugins enables plugins: their sources reach the kit, and the app asks for what they need.

func (*Env) AndroidDevices added in v0.0.6 

func (e *Env) AndroidDevices() ([]AndroidDevice, error)

AndroidDevices lists what `adb devices` reaches, ready to use.

func (*Env) BuildAndroid 

func (e *Env) BuildAndroid(a *App, abis []string) (string, error)

BuildAndroid compiles the Go app into a shared library per ABI, compiles the Java host and app code to dex, and assembles a signed, 16 KB-aligned APK. It returns the APK path.

func (*Env) BuildAndroidProject 

func (e *Env) BuildAndroidProject(a *App, abis []string) (string, error)

BuildAndroidProject builds native/android's debug APK for the given ABIs and returns its path.

func (*Env) BuildIOS 

func (e *Env) BuildIOS(a *App, t IOSTarget) (string, error)

BuildIOS compiles the Go app into a static library, links it with the NimbusNativeKit host and the app's Swift code, and produces a signed .app. It returns the .app path.

func (*Env) BuildIOSProject 

func (e *Env) BuildIOSProject(a *App, t IOSTarget, dev ...IOSDeviceBuild) (string, error)

BuildIOSProject builds native/ios for the simulator, or for a phone when dev is set (signed automatically with its team), and returns the .app path.

func (*Env) Dev 

func (e *Env) Dev(a *App, platform string, port int, target ...DevTarget) error

Dev runs the app's Go code on this machine against a dev shell on the simulator or emulator, and restarts it on every save: 

shell (device) ⇄ relay (here) ⇄ app process (here, rebuilt on change)

The shell is the real app with its Go library replaced by a proxy (dev/client), so the native side is exactly what ships.

func (*Env) Doctor 

func (e *Env) Doctor() bool

Doctor prints what was found and returns false if anything required for the given platforms is missing.

func (*Env) Gen 

func (e *Env) Gen(a *App) (*Generated, error)

Gen regenerates the folder routes (pages/routes_gen.go, when the app has pages/) and every wire schema the app links from its own code (directories whose Go files carry //wire: directives), writing wire_gen.go next to each, and host code under build/gen. The combined hash covers every schema package the app links, including ones from its dependencies.

func (*Env) GenRoutes 

func (e *Env) GenRoutes(root string) error

GenRoutes generates pages/routes_gen.go for the module at root. It does nothing when there is no pages directory.

func (*Env) Kotlinc 

func (e *Env) Kotlinc() (string, error)

Kotlinc returns the kotlinc to build with: NIMBUS_KOTLINC if set, else the pinned compiler, downloading and verifying it on first use.

func (*Env) LibAndroid 

func (e *Env) LibAndroid(a *App, o AndroidLib) error

LibAndroid builds libnimbusapp.so for each ABI and writes the generated Kotlin.

func (*Env) LibIOS 

func (e *Env) LibIOS(a *App, o IOSLib) error

LibIOS builds the app's Go code into libapp.a (one architecture, or a fat simulator library) and writes the generated Swift as one file.

func (*Env) ListPlugins added in v0.0.13 

func (e *Env) ListPlugins(a *App, out io.Writer) error

ListPlugins shows the plugins that come with this version.

func (*Env) MakeKeystore added in v0.0.8 

func (e *Env) MakeKeystore(a *App) (string, error)

MakeKeystore creates the project's Android release key (an "upload key" for Google Play) with keytool, and keystore.properties pointing at it. Both stay out of git; back them up.

func (*Env) New 

func (e *Env) New(p NewProject) error

New creates a project: the shared UI and the phone entry, and native/ios and native/android projects that open in Xcode and Android Studio; with a Nimbus server, also the web app it serves.

func (*Env) ReleaseAndroid added in v0.0.8 

func (e *Env) ReleaseAndroid(a *App, r Release) (aab, apk string, signed bool, err error)

ReleaseAndroid builds the project's Play Store bundle (.aab) and a release APK for every ABI. It returns both paths, and whether they are signed with a release key (false: the debug key, which Play refuses).

func (*Env) ReleaseIOS added in v0.0.8 

func (e *Env) ReleaseIOS(a *App, r Release) (string, error)

ReleaseIOS archives the project's Xcode app and exports it as an .ipa, signed automatically with the team. It returns the .ipa path.

func (*Env) RemovePlugins added in v0.0.13 

func (e *Env) RemovePlugins(a *App, names []string, out io.Writer) error

RemovePlugins disables plugins, and takes away what only they asked for.

func (*Env) RunAndroid 

func (e *Env) RunAndroid(a *App, apk string) error

RunAndroid installs the APK on a connected device or emulator (booting the first AVD if none is connected), launches it and streams its logs.

func (*Env) RunIOS 

func (e *Env) RunIOS(a *App, appPath string) error

RunIOS installs the app on a simulator (booting one if needed), launches it and streams its console until it exits or the command is interrupted.

func (*Env) RunIOSPhone added in v0.0.4 

func (e *Env) RunIOSPhone(a *App, appPath string, p IOSPhone) error

RunIOSPhone installs the app on a phone and opens it (once the phone is unlocked), streaming its output until it exits or the command is interrupted.

func (*Env) Sync added in v0.0.10 

func (e *Env) Sync(a *App) (bool, error)

Sync brings a project's copies up to date with the nimbus-native its go.mod requires: the kits under native/ and the generated Swift (which Xcode compiles only if it exists when the build starts). It reports whether a kit changed.

func (*Env) Upgrade added in v0.0.10 

func (e *Env) Upgrade(root, version string) (from, to string, err error)

Upgrade moves a project to another nimbus-native release: version is "latest" or a tag like v0.0.10. go.mod changes, then the new release's own toolchain syncs the project's copies (nimbus native sync), so the kits and generated code come from the version the app now builds with. It returns the versions before and after.

type Generated 

type Generated struct {
	Combined    uint64   // every schema the native library links: what hosts pass to nn_start
	AppCombined uint64   // only the schemas the app's own package links
	Hashes      []uint64 // the schemas behind Combined
	SwiftFiles  []string // compile into the iOS app
	KotlinFiles []string // compile into the Android app
}

Generated holds the host code produced by Gen.

type IOSDeviceBuild added in v0.0.4 

type IOSDeviceBuild struct {
	Team     string   // Apple team id
	Phone    IOSPhone // the device to register and build for
	Settings []string // extra build settings, NAME=value
}

IOSDeviceBuild is how to sign a build for a phone.

type IOSLib 

type IOSLib struct {
	SDK   string   // iphonesimulator | iphoneos
	Archs []string // arm64, x86_64 (simulator only)
	MinOS string   // deployment target, e.g. "15.0"
	Out   string   // directory for libapp.a
	Swift string   // the generated Swift file to write, inside the app's sources
	Kit   string   // the project's copy of NimbusNativeKit, kept in sync ("" skips)
}

IOSLib says what LibIOS builds, usually from Xcode's build settings.

type IOSPhone added in v0.0.4 

type IOSPhone struct {
	Name string
	ID   string // CoreDevice identifier, for devicectl
	UDID string // hardware UDID, for xcodebuild
	Wifi bool
}

IOSPhone is an iPhone or iPad this Mac can install on, over USB or Wi-Fi (paired in Xcode's Devices window), as devicectl lists it.

func IOSPhones added in v0.0.4 

func IOSPhones() ([]IOSPhone, error)

IOSPhones lists the paired iPhones and iPads that can be reached now.

func PickIOSPhone added in v0.0.4 

func PickIOSPhone(want string) (IOSPhone, error)

PickIOSPhone is the phone matching want (a name or id), or the only one.

type IOSTarget 

type IOSTarget struct {
	SDK    string // iphonesimulator | iphoneos
	Triple string // clang/swiftc target
}

IOSTarget is where an iOS build runs.

type NewProject 

type NewProject struct {
	Dir    string // created; must not exist or be empty
	Name   string // display name, e.g. "Shop"
	Module string // Go module path, e.g. "shop"
	ID     string // bundle id / application id, e.g. "space.nimbusgo.shop"

	// Template is the starting app; "counter", the only one for now.
	Template string

	// Server is what the app talks to. "none" (the default) makes the phone
	// app alone, for any backend (Node, Go, anything that speaks HTTP).
	// "nimbus" adds the app to Dir, a Nimbus app that `nimbus new` just
	// made: its server also serves the app's pages to browsers.
	Server string

	// The nimbus-native the project requires: a version, or a local
	// checkout (Replace) for working on nimbus-native itself.
	Version string
	Replace string
}

NewProject describes a project for New to create.

func NewProjectFor 

func NewProjectFor(dir, name, module, id string) (NewProject, error)

NewProjectFor fills in a project's names from its directory, and the nimbus-native version from this toolchain's own build: the project gets the version that made it. A toolchain run from a checkout has no version, so the project points at that checkout.

type Release added in v0.0.8 

type Release struct {
	Version string // shown to users, e.g. "1.2.0"; empty keeps the project's
	Build   string // a number that grows with every upload, e.g. "42"
	Team    string // iOS: the Apple team that signs
	// Export is how the iOS app is signed: "app-store" (the default, for App
	// Store Connect and TestFlight), "ad-hoc" (registered devices) or
	// "development".
	Export string
}

Release says how to build for a store.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.