# Building and shipping > Package an app for every platform, make installers, sign and notarize it, publish it on GitHub and embed it in other apps. ## Build ```sh go tool nsgo build ``` `build` writes a stripped release package for each target `nsgo.yaml` lists, into `dist/--`: an `.app`, an `.ipa`, an `.apk`, Windows' and Linux's directories, or a web site, whose page fetches each TSX module an `import()` names when the import runs. `-target` replaces the list, and `all` means every target that needs only Go and Xcode; add `android_x64` when an Android NDK is installed, and `miniprogram`, or `miniprogram_wechat`, `miniprogram_qq`, `miniprogram_alipay` or `miniprogram_douyin` alone, for [mini programs](#mini-programs). `-run` starts the package built for this machine, or installs it on the iPhone, simulator or Android device `-device` picks. Everything to hand out lands in `dist/releases`, the only directory to look in: | In `dist/releases` | What | | --- | --- | | `*.dmg`, `*-setup.exe`, `*.deb`, `*.pkg.tar.gz`, `*.AppImage` | [Installers](#installers) for macOS, Windows and Linux | | `*-ios.ipa`, `*-tvos.ipa`, `*.apk` | The iOS, tvOS and Android packages, for the stores or devices | | `*.pkg`, `*.msix`, `*.aab`, `*.tar.gz` and `flatpak/` | A `store` build's [store packages](#store-packages) | | `install.sh`, `install.ps1` | Scripts installing the app from [GitHub releases](#publish-on-github) | | `appcast-.xml` | The feeds [updating](#updates) apps read | | `*-web.zip` | The site, to unpack and serve as it is | | `miniprogram//` | Each mini program's project, to upload from its developer tool | Each file is named `---`, such as `hello-1.2.0-windows-x64-setup.exe`, so users find their system's on a release page, and has its `.sha256` beside it. A build of another version empties the directory first; builds of the same version, on other machines too, add to it. Simulators' and watchOS's packages stay in their `dist/--` directories. ## nsgo.yaml ```yaml name: Hello id: dev.example.hello version: 0.1.0 build_number: 1 # CFBundleVersion and Android's versionCode; else from version # appearance: dark # light or dark whatever the system's # theme: theme.json # a TSX app's theme: NSGo's or a shadcn/ui one # i18n: { dir: locales, source: en } # the app's catalogs and the language they are written in icon: apple: assets/AppIcon.icon # macOS, iOS and watchOS, or an .icns for macOS png: assets/Icon.png # every other target tvos: assets/AppIconTV.brandassets # the Apple TV's layered icon and top shelf art, or a wide PNG watchos: assets/AppIconWatch.icon # the Apple Watch's own, drawn in circles, or a square PNG dev: target: native # native, web, ios, ios_simulator, tvos, tvos_simulator, watchos, watchos_simulator, android or miniprogram_ hot_reload: true # false builds once, watching no files # icon: { png: assets/Icon-dev.png } # replaces icon's files in dev's builds; defaults to assets/*-dev.* build: output: dist open: false # true opens the output directory after building installers: true # false leaves out the disk image, the Windows installer and the Linux packages jobs: 0 # how many targets build at once; 0 is half the CPUs, 1 one after another targets: [macos_arm64, macos_x64, windows_arm64, windows_x64, linux_arm64, linux_x64, ios, ios_simulator, tvos, tvos_simulator, watchos, watchos_simulator, android_arm64, web] # android: { permissions: [REQUEST_INSTALL_PACKAGES] } # manifest permissions beyond the runtime's # windows: { command_line: true } # add .com, a console companion that forwards arguments and streams to .exe; not in store builds # linux: { maintainer: "Jane Doe " } # the Linux packages' maintainer, else the app's name # release: { github: me/hello } # the GitHub repository the install scripts and updates install from, else the Git remote origin's; tag_prefix: v by default # updates: { key: } # how the app updates, by platform and channel: see Updates # miniprogram: { appid: { wechat: wx0123456789abcdef, alipay: "2021000000000000" }, custom_navigation: false } # the mini programs' ``` Flags replace the values they name, such as `-target`, `-version` or `-output`; `-h` lists them all. An Apple TV's icon is a layered card, not a square: `tvos` takes Xcode's `.brandassets`, its `App Icon` stacks and top shelf images, or a wide image such as 1280×768, which the tool draws to fit the card over its edge color and centers on the top shelf images. Without either, the PNG sits at three quarters of the card's height. An Apple Watch masks its icon to a circle, so `watchos` takes an `.icon` drawn for watchOS's circles or a square PNG; without it the app uses `apple`, then `png`. Both fall back to `assets/AppIconTV.*` and `assets/AppIconWatch.*`, as `apple` and `png` do. Every build also takes NSGo's own flags as it starts, such as `--nsgo-fps` ([Running and debugging](https://nsgo.dev/docs/debugging.md#flags-of-every-build)). ## Installers For the desktop targets, `build` writes what users install the app from into `dist/releases`, each with a `.sha256` checksum: | Target | Installer | | --- | --- | | macOS | `--macos-.dmg`, a disk image showing the app, an arrow and a link to Applications to drag it to, signed with `sign.identity` and [notarized](#notarize) | | Windows | `--windows--setup.exe`, an [NSIS](https://nsis.sourceforge.io) installer that installs for the user, again in the folder the user chose before, closing the app if it runs, with a Start menu shortcut, an optional desktop one and an uninstaller that removes only what it installed; `windows.command_line` also installs the `.com` companion and puts the app's folder on the user's `Path`, so consoles opened after installing run the app's command, while Win+R, which finds the companion too, starts the app and closes the console it opened | | Linux | `--linux-.deb` for Debian and Ubuntu, and `--linux-.pkg.tar.gz` for Arch Linux, which install the app in `/opt/` with a command, its desktop entry and icon, and `--linux-.AppImage`, which runs on any distribution without installing | The Windows installer needs NSIS's compiler, on a Mac `brew install makensis`, so a Mac builds every installer; without it `build` leaves the script, `.nsi`, in the package, which compiles anywhere as it is. The installer speaks the languages of the app's catalogs that NSIS translates, Simplified and Traditional Chinese included, picking the system's. `-installers=false` or `build.installers: false` builds the packages alone. The installers take pictures and icons of the app's own; each is the app's icon or the built-in picture otherwise: ```yaml macos: dmg_background: assets/DMGBackground.png # the disk image's window, which takes its size in points dmg_icon: assets/DMGIcon.png # the disk image's icon: an .icns or a square PNG windows: installer_icon: assets/Setup.png # the setup program's icon: an .ico or a square PNG uninstaller_icon: assets/Uninstall.png # the uninstaller's ``` A background PNG with a twin twice its size, such as `DMGBackground@2x.png`, stays sharp on Retina screens. The app's icon sits a quarter in from the left, Applications a quarter in from the right, each with its name centered from top to bottom, where the built-in picture draws its arrow; leave room for them in a background of your own. The Linux packages have no pictures of their own; they install the app's icon. The AppImage needs FUSE, which most distributions have, and takes GTK 4 from the system, as the packages do; its runtime is downloaded once into the user cache. ## Store packages `-channel store`, or `updates.channel: store`, builds the desktop and Android targets for their stores, which update them, in place of the installers and install scripts: | Target | Store package | | --- | --- | | macOS | `--macos-.pkg` for the Mac App Store: the app in the App Sandbox, signed with the provisioning profile's identity and packaged with your team's installer identity | | Windows | `--windows-.msix` for the Microsoft Store, which signs it on publishing | | Linux | `--linux-.tar.gz` with the app's AppStream metadata, and `flatpak/.yml`, the manifest Flathub builds the Flatpak from, which downloads those archives from the release on GNOME's runtime | | Android | `--android-.aab`, an App Bundle for Google Play signed with `sign.keystore`, the upload key | ```yaml macos: category: public.app-category.productivity # LSApplicationCategoryType, which the Mac App Store requires # entitlements: { com.apple.security.files.downloads.read-write: true } # beyond the network, the files the user picks and what apple.info explains windows: store: # as Partner Center's Product identity lists them identity: 12345Example.Hello publisher: CN=00000000-0000-0000-0000-000000000000 publisher_name: Example # device_capabilities: [microphone, webcam] # the devices the app uses, which Windows asks the user for linux: summary: Says hello # one line for software centers license: MIT # an SPDX expression; LicenseRef-proprietary by default # flatpak_runtime: "51" # GNOME's runtime version android: target_sdk: 35 # the targetSdkVersion Google Play requires sign: macos_profile: assets/MacAppStore.provisionprofile # the Mac App Store's profile # installer: "3rd Party Mac Developer Installer: Example (ABCDE12345)" # by default the keychain's of the profile's team ``` Without `sign.macos_profile` the Mac package is unsigned: it runs sandboxed on your Mac, which tests the sandbox, but uploads nowhere. A sandboxed app reaches only its own container, the network and the files the user picks; widgets cannot share timelines from the sandbox yet, so a store build refuses them. Upload the `.pkg` with Transporter, the `.msix` in Partner Center, the `.aab` in Play Console, and submit `flatpak/.yml` to Flathub once the release holds the archives it names; `flatpak-builder` builds it locally too. Windows installs an MSIX outside the Store only when it is signed, which the Store does. On macOS, a scroll view's edge effects (`Scroll.EdgeEffects`) blur through Core Animation's private `CABackdropLayer` and `CAFilter`, as AppKit's own edge effects do, since no public API varies a blur across a view. App Store review may reject apps that use private APIs: NSGo calls them only for scroll views with edge bars, but every macOS build contains their names. ## Publish on GitHub When the build has a macOS, Windows or Linux target, `dist/releases` also holds `install.sh` and `install.ps1`, which install the app from the releases of the GitHub repository `release.github` names, else the one the app's Git remote `origin` is on; without either `build` writes none and says so. Upload its files, the top level without `miniprogram/`, to the release tagged `v`: ```sh gh release create v1.2.0 dist/releases/*.* ``` Users then install or update the app with one line, which the build prints: ```sh curl -fsSL https://github.com/me/hello/releases/latest/download/install.sh | sh # macOS and Linux ``` ```powershell irm https://github.com/me/hello/releases/latest/download/install.ps1 | iex # Windows ``` On macOS the script copies the app from the disk image into `/Applications`, or `~/Applications` when it cannot write there; on Linux it installs the Arch package with `pacman`, else the Debian one with `apt-get` or `dpkg`, through `sudo`; on Windows it runs the installer silently, which installs where the app already is. Each checks the file against its checksum first. `_VERSION`, the app's name in capitals, such as `HELLO_VERSION=1.1.0`, installs another release, and `_DOWNLOAD_URL` downloads from a mirror. ## Updates `updates` has the app keep itself up to date the way its platform and the channel users get it from do: ```yaml updates: key: zE0hx2FZwwHy6X7LbEP3GjTTE3KWfCAp5gsaBysC+vg= # the public key nsgo keygen prints # channel: store # direct, store or none; direct by default with a key, none without # feed: https://example.com/hello/ # where the appcasts and installers are; by default the latest GitHub release # automatic: false # check only when asked; true by default ``` `nsgo keygen` prints a key pair and writes no file: put the public key in `updates.key` and commit it, and keep the secret one out of the repository, in a password manager and in `NSGO_UPDATES_KEY` where releases build, such as a GitHub Actions secret. Each direct build signs the installers with the secret key and writes `appcast-.xml` beside them, a feed in [Sparkle](https://sparkle-project.org)'s format that the app reads under `feed`: upload the appcasts with the installers. Without the secret key, `build` writes no macOS or Windows appcast, as those install only signed installers, and Linux and Android apps reading an unsigned appcast open the release's page instead of installing its package. | Target | How a direct build updates | | --- | --- | | macOS | Sparkle, which `build` puts into the app, checks daily, offers the new version, downloads the disk image, checks its signature, installs it and restarts the app | | Windows | WinSparkle, beside the executable, does the same and runs the installer silently, which starts the new version | | Linux, Android | The app reads its appcast, and once the user chooses Update downloads and verifies the signed package and installs it through `pkexec dpkg`, restarting, or Android's package installer; an app from the Arch package or the AppImage, or an unsigned appcast, offers the release's page instead | | iOS | The app asks the App Store, which updates it, and offers its page there | ### Channels The channel decides who updates the app. `-channel` replaces `updates.channel` for one build, so one project builds for each: | Channel | For | The packages | | --- | --- | --- | | `direct` | GitHub, a website, Homebrew casks and winget, which install the release's own files | Update themselves as above | | `store` | The App Store, the Mac App Store, the Microsoft Store, Google Play, Flathub and other stores | Are the [store packages](#store-packages) and carry no updater; iOS asks the App Store, which needs no key | | `none` | Linux distributions and anyone who repackages the app | Check nothing | Stores reject apps that update themselves, so upload a `store` build, never a direct one. A Homebrew cask for a direct app says `auto_updates true`. Wherever the system tells who installed the app, the app checks that too: an Android app from Google Play or another store, a Flatpak or Snap, and a TestFlight build check nothing, as their store updates them. ### Checking from the app `updater.Check(cx)` checks as a *Check for Updates…* menu item does, and shows what it finds; `updater.CheckInBackground(cx)` shows only a newer version, and `updater.CheckDaily(cx)` does that at most once a day. While `automatic` is on, the app checks that way on Linux, Android and iOS as it starts and whenever the user comes back to it; a check that fails, as one offline does, is tried again an hour later. Development builds never update. ## File types `file_types` makes a macOS app open its documents from the Finder, the Dock and Open With: ```yaml file_types: - name: Flow File extensions: [flow] # id: dev.example.hello.flow # . by default; another's ID imports its type # icon: assets/Flow.icns # or a square PNG # role: viewer # editor by default # conforms: [public.json] # public.data by default ``` The app hears the files with `desktop.OnOpenFiles`, which also takes those named on the command line on Windows and Linux. Files that launched the app wait for the first handler: ```go desktop.OnOpenFiles(cx, func(paths []string) { open(paths[0]) }) ``` ## Mini programs ```sh go tool nsgo build -target miniprogram_wechat -run go tool nsgo dev -target miniprogram_alipay ``` Each target writes a project for its platform's developer tool, also in `dist/releases/miniprogram/`, which `-run` and `dev` open; `dev` builds again as you save, and the tool reloads: | Target | Platform | Tool | | --- | --- | --- | | `miniprogram_wechat` | WeChat | [WeChat DevTools](https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html), with its service port on (Settings, Security) | | `miniprogram_qq` | QQ | [QQ's developer tool](https://q.qq.com/wiki/tools/devtool/), on macOS | | `miniprogram_alipay` | Alipay | [Alipay's Mini Program Studio](https://opendocs.alipay.com/mini/ide/download), on macOS | | `miniprogram_douyin` | Douyin and ByteDance's other apps | [Douyin's developer tool](https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/developer-instrument/download/developer-instrument-update-and-download), on macOS | `miniprogram.appid` gives the mini program's AppID on each platform (`wechat`, `qq`, `alipay`, `douyin`); without one, WeChat DevTools previews it with its tourist AppID and the other tools ask for one. The platform's navigation bar shows the app's title; with `custom_navigation`, the app fills the page and its safe area keeps it clear of the menu button. QQ, Alipay and Douyin have not been tried in their tools yet, and Alipay does not yet take back through the app, keyframes or the keyboard's height. Mini programs are experimental. A mini program runs Go apps alone, not TSX, and the platforms hold the app's compressed module to 2 MB: an app of a few screens fits, larger ones do not yet, and `build` says when one does not. Shaders draw nothing there, and web views, videos, native components and the app's font files are not shown yet. ## Sign ```yaml sign: identity: "Apple Development: you@example.com (ABCDE12345)" # signs the macOS app, else ad hoc profile: assets/AppStore.mobileprovision # signs the IPA keystore: assets/release.p12 # signs APKs, with key_alias # widgets_profile: assets/Widgets.mobileprovision # signs the IPA's widget extension # clip_profile: assets/Clip.mobileprovision # signs the IPA's App Clip ``` The keystore's passwords come from `NSGO_KEYSTORE_PASSWORD` and `NSGO_KEY_PASSWORD`. `-team` signs the iPhone's package. ### Notarize Apps downloaded on a Mac open without Gatekeeper's warning once Apple has notarized them. Sign with a Developer ID and name the credentials notarytool keeps in your keychain: ```sh xcrun notarytool store-credentials hello --apple-id you@example.com --team-id ABCDE12345 ``` ```yaml sign: identity: "Developer ID Application: Example Inc (ABCDE12345)" notarize: hello # the keychain profile above; or -notarize hello ``` `build` then signs with the hardened runtime, submits the disk image, waits for Apple's verdict, a few minutes, and staples the ticket to the image and the app; a rejection prints Apple's log. In CI, `NSGO_NOTARY_KEY`, `NSGO_NOTARY_KEY_ID` and `NSGO_NOTARY_ISSUER`, an App Store Connect API key's `.p8` file, ID and issuer, take the profile's place. The hardened runtime denies the microphone, the camera and the calendars unless the app claims them, which `build` does when `apple.info` has `NSMicrophoneUsageDescription`, `NSCameraUsageDescription`, or a calendars or reminders usage description. ## Widgets and Live Activities `build` and `dev` compile the extension that draws the app's widgets and Live Activities into the macOS and iOS packages with Xcode's Swift compiler, with no separate step. On iOS the app and its widgets share an app group: `-run` on an iPhone has Xcode sign both and register the group; for an IPA, enable it for both `` and `.widgets`, and sign the extension with `sign.widgets_profile`. Android 16 shows Live Activities as Live Updates, which need no extension. [Widgets](https://nsgo.dev/docs/widgets.md) and [Live Activities](https://nsgo.dev/docs/live-activities.md) cover their configuration and API. ## App Clips An App Clip is a small part of an iOS app that runs from a link, a code or an NFC tag without installing the app. `app_clip` builds one into the iOS package, from a main package of its own so it links only what it shows: ```yaml app_clip: main: ./clip # the clip's main package, the app's own by default domains: [example.com] # whose links open it # name: Hello Clip # " Clip" by default # id: dev.example.hello.Clip # .Clip by default # minimum: "17.0" # 16.0 by default; 17.0 allows 100 MB when only links open it # notifications: true # ask for notifications for a day # location: true # let the clip confirm where it was opened ``` The clip reads the link that opened it with `mobile.OpenedURL`, which changes as another link opens it again, and `mobile.IsAppClip` says whether the code runs as one. The system downloads a clip of up to 15 MB, or 100 MB from iOS 17 when only links open it, and `build` refuses a larger one; a clip linking `ui` takes about 11 MB. `dev -target ios_simulator -clip https://example.com/order?table=12` runs the clip alone in the simulator, opened from that link, and `-target ios` on an iPhone, printing the link's QR code: list the link in Settings > Developer > Local Experiences and the camera opens the clip from it. Apple signs App Clips only for teams of the Apple Developer Program, not personal teams. For the App Store, enable App Clips for ``, sign the clip with `sign.clip_profile`, and serve the apple-app-site-association file of the domains. The repository's `examples/appclip` is a café whose clip orders at a table. ## Embed in another app `-embed` packages the app for an iOS or Android app of your own: an XCFramework, of dynamic frameworks with `-dynamic`, or an AAR whose `NSGoView` or `NsgoView` shows it. Go desktop programs show apps with `nsgo.NewView`, and web pages with the site's `nsgo.js`, whose host is the page's or the one `web.host` in `nsgo.yaml` names. The repository's `examples/embed-*` show each; [Embedding](https://nsgo.dev/docs/embedding.md) covers the host side.