toolchain

package
v0.0.6 Latest Latest
Warning

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

 Go to latest Published: Oct 29, 2026 License: MIT Imports: 38 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 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", "shop"}

Templates are the apps New can start from.

Functions

func AndroidProjectID 

func AndroidProjectID(root string) (string, error)

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

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 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 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 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 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) 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) 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) New 

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

New creates a project: a Go module with the server, the shared UI and the phone entry, and native/ios and native/android projects that open in Xcode and Android Studio.

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.

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
}

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 default) or "shop".
	Template 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.

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.