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
- Variables
- func AndroidProjectID(root string) (string, error)
- func IOSProjectID(root string) (string, error)
- func InstalledKotlinc() string
- func IsProject(dir string) bool
- type AndroidABI
- type AndroidLib
- type App
- type Env
- func (e *Env) BuildAndroid(a *App, abis []string) (string, error)
- func (e *Env) BuildAndroidProject(a *App, abis []string) (string, error)
- func (e *Env) BuildIOS(a *App, t IOSTarget) (string, error)
- func (e *Env) BuildIOSProject(a *App, t IOSTarget) (string, error)
- func (e *Env) Dev(a *App, platform string, port int) error
- func (e *Env) Doctor() bool
- func (e *Env) Gen(a *App) (*Generated, error)
- func (e *Env) GenRoutes(root string) error
- func (e *Env) Kotlinc() (string, error)
- func (e *Env) LibAndroid(a *App, o AndroidLib) error
- func (e *Env) LibIOS(a *App, o IOSLib) error
- func (e *Env) New(p NewProject) error
- func (e *Env) RunAndroid(a *App, apk string) error
- func (e *Env) RunIOS(a *App, appPath string) error
- type Generated
- type IOSLib
- type IOSTarget
- type NewProject
Constants ¶
const IOSGeneratedSwift = "native/ios/Runner/Generated/NimbusGenerated.swift"
IOSGeneratedSwift is where a project's generated Swift lives.
const MinAndroidAPI = 26
MinAndroidAPI is the lowest Android version (API 26, Android 8.0) apps run on.
const MinIOS = "15.0"
MinIOS is the lowest iOS version apps run on.
const RoutesFile = "routes_gen.go"
RoutesFile is the generated table, in the pages package.
Variables ¶
var ( IOSSimulator = IOSTarget{"iphonesimulator", "arm64-apple-ios" + MinIOS + "-simulator"} IOSDevice = IOSTarget{"iphoneos", "arm64-apple-ios" + MinIOS} )
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"},
}
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.
Functions ¶
func AndroidProjectID ¶
AndroidProjectID is the application id in native/android's app module.
func IOSProjectID ¶
IOSProjectID is the bundle id in native/ios's Xcode project.
func InstalledKotlinc ¶
func InstalledKotlinc() string
InstalledKotlinc is the kotlinc that Kotlinc would use, without downloading: "" if it is not installed yet.
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 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 ¶
LoadApp describes the app in dir. Name and ID default from the directory name when empty.
func LoadProject ¶
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.
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
}
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 (*Env) BuildAndroid ¶
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 ¶
BuildAndroidProject builds native/android's debug APK for the given ABIs and returns its path.
func (*Env) BuildIOS ¶
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 ¶
BuildIOSProject builds native/ios for the simulator or a device and returns the .app path.
func (*Env) Dev ¶
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 ¶
Doctor prints what was found and returns false if anything required for the given platforms is missing.
func (*Env) Gen ¶
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 ¶
GenRoutes generates pages/routes_gen.go for the module at root. It does nothing when there is no pages directory.
func (*Env) Kotlinc ¶
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 ¶
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 ¶
RunAndroid installs the APK on a connected device or emulator (booting the first AVD if none is connected), launches it and streams its logs.
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 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 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"
// 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