Apple

Once can build libraries, frameworks, applications, and test bundles for Apple platforms. This guide starts with one iOS application and a library it depends on, then queries, builds, runs, and tests that same project.

If you already have an Xcode project or workspace, you do not need to declare these targets by hand. Xcode Projects shows how to point Once at an existing .xcodeproj or .xcworkspace and get the same targets derived for you.

Prerequisites#

On macOS, Apple targets use the developer tools selected by xcrun, swiftc, and clang. Verify that the Swift compiler is available:

bash

xcrun --find swiftc

Running this guide's iOS application also requires an installed Simulator runtime. Building a library does not require a running simulator.

Linux can cross-compile native Apple targets using Swift, xtool's Darwin SDK, and Linux resource and signing tools. See Build iOS Applications on Linux for installation, a runnable starter, and the boundaries between building, provisioning, and device deployment.

Explicit Modules and Dependency Checks#

Set explicit_modules = true in an Apple target's attributes to turn imported Swift interfaces and Clang modules into separate cacheable build actions. Once first runs the Swift compiler's dependency scanner, builds the discovered modules, then compiles the target with implicit module building disabled. Independent module actions share the command's memory budget, and identical module actions can reuse results across targets. Scans use separate, cleared scratch directories. Module output paths include their compiler commands and input identities, so different modules cannot overwrite one another merely because their names match.

toml

[[target]]
name = "Core"
kind = "apple_library"
srcs = ["Sources/Core/**/*.swift"]
deps = ["Models"]

[target.attrs]
platform = "macos"
explicit_modules = true
dependency_check = "error"

The same attributes are available on Swift macros, frameworks, applications, executables, and test bundles. Set them on a swift_package_workspace or xcode_workspace seed to propagate them to resolved Swift targets. Native Xcode targets also honor SWIFT_ENABLE_EXPLICIT_MODULES = YES.

dependency_check defaults to "off". With "error", source imports of workspace modules must name direct dependencies, even when a transitive or inferred dependency makes the module available. System modules are exempt. An error identifies the consuming target, the missing module, and a suggested manifest repair. Checking requires explicit modules and a Swift compiler whose scan reports source-import information; unsupported compilers fail clearly.

Compiler binaries, development-kit contents, Clang resources, and host Swift plugins contribute to module cache identity. Changing a declared header or interface invalidates the corresponding module action. Existing projects keep implicit modules by default.

This is not a downloadable hermetic Apple toolchain. Builds still require the selected Xcode installation on macOS or the installed Darwin SDK on Linux, and cached scanner commands retain their host paths. Module inputs outside the workspace and the identified development-kit and toolchain directories are rejected instead of being silently omitted from cache identity. Move such dependencies into the workspace or use implicit modules for those targets. Compiler scans that require auxiliary files created only inside their temporary cache are also rejected with a repair diagnostic. Keep interfaces and headers in the workspace, or leave explicit modules disabled for those targets. The scheduler currently reserves the default 250 mebibytes per module action. This is an admission estimate, not a hard limit on compiler memory use; large module builds can need more memory. Standalone C-family compilation is unchanged. Initial graph queries show the scan and deferred planning step; execution evidence records the module actions discovered at build time. Target scheduling still waits for dependency targets to complete, rather than releasing consumers as soon as one module is ready.

Declare the Application#

Create apps/Hello/once.toml with a reusable library and an application that depends on it:

toml

[[target]]
name = "AppCore"
kind = "apple_library"
srcs = ["Sources/AppCore/**/*.swift"]

[target.attrs]
platform = "ios"
minimum_os = "17.0"

[[target]]
name = "Hello"
kind = "apple_application"
srcs = ["Sources/HelloApp/**/*.swift"]
deps = ["./AppCore"]

[target.attrs]
platform = "ios"
bundle_id = "dev.once.Hello"
minimum_os = "17.0"
families = ["iphone"]

./AppCore resolves in the same package. The dependency is typed: apple_application accepts the linkable output produced by apple_library.

The smallest useful source layout is:

plaintext

apps/Hello/
├── once.toml
└── Sources/
    ├── AppCore/
    └── HelloApp/

The application source needs an entry point, such as a Swift type marked with @main. The library contains code imported by the application.

Query Before Building#

Inspect the exact targets declared above:

bash

once query targets
once query capabilities apps/Hello/AppCore
once query capabilities apps/Hello/Hello
once query schema apple_application

AppCore exposes build. Hello exposes build and run. The schema query shows the application attributes, accepted dependencies, capabilities, and outputs without starting a compiler.

Build and Run#

Build the application bundle:

bash

once build apps/Hello/Hello

Once builds AppCore first because Hello depends on it. Outputs are materialized under .once/out/<target>/; the apple_application reference lists the exact output groups.

Launch the application in an iOS simulator:

bash

once run --visible apps/Hello/Hello

Once selects or boots a simulator, installs the application bundle, and launches its bundle identifier. The launch runs on every invocation instead of replaying from the action cache. Omit --visible when Simulator does not need to be brought to the foreground.

macOS applications use the host application launcher. Launching directly on an iPhone or iPad is not supported yet.

Create a Device-Specific Size-Analysis Archive#

Size-analysis services can report confusing results when they receive a universal application. Sentry, for example, does not thin an uploaded application and recommends thinning it before upload.

Add a device application and a package target for the device model you want to measure:

toml

[[target]]
name = "HelloDevice"
kind = "apple_application"
srcs = ["Sources/HelloApp/**/*.swift"]
deps = ["./AppCore"]

[target.attrs]
platform = "ios"
sdk_variant = "device"
bundle_id = "dev.once.Hello"
minimum_os = "17.0"
families = ["iphone"]

[[target]]
name = "HelloSizeAnalysis"
kind = "apple_thinned_package"
deps = ["./HelloDevice"]

[target.attrs]
device_model = "iPhone17,1"

Build the device-specific archive:

bash

once build apps/Hello/HelloSizeAnalysis

The target writes one or more archives with the .ipa extension and a stable manifest that maps them to the requested device model. Declare another apple_thinned_package target for each additional model so builds and cache entries stay independent.

These archives use ad-hoc signing and are intended for size analysis. They do not replace distribution signing or provisioning for physical-device installation. See the apple_thinned_package reference for the exact outputs and validation rules.

Add a Test Target#

Add a test target to the same apps/Hello/once.toml:

toml

[[target]]
name = "AppCoreTests"
kind = "apple_test_bundle"
srcs = ["Tests/AppCoreTests/**/*.swift"]
deps = ["./AppCore"]

[target.attrs]
platform = "ios"
minimum_os = "17.0"
swift_testing = true
labels = ["unit"]

Place tests that use Swift Testing under Tests/AppCoreTests/, then inspect and run the new capability:

bash

once query capabilities apps/Hello/AppCoreTests
once test apps/Hello/AppCoreTests

Apple tests currently support macOS logic tests and iOS simulator bundles. An application host discovered through dependency providers is supported, while direct test_host attributes, custom destinations, test plans, and device runners are not implemented. Non-empty unsupported attributes fail during graph analysis instead of being ignored. See the apple_test_bundle reference before adding those features.

Choose Values by Configuration#

Configurable attributes can use select. For example, a library shared by an iOS and macOS target can choose the platform framework it links:

toml

[target.attrs]
sdk_frameworks = { select = { ios = ["UIKit"], macos = ["AppKit"] } }

Apple configuration keys include platform names, architectures, simulator, device, mac_catalyst, combined keys such as ios:simulator, and default. When more than one branch matches, the most specific branch wins.

Attributes that determine the configuration, including platform, sdk_variant, archs, and mac_catalyst, must remain literal. The target kind schema identifies any other non-configurable attributes.

See the configurations guide for how --config overrides these tokens per invocation and how the effective configuration scopes outputs.

Connect Native Dependencies#

Apple targets can consume native outputs from other ecosystems through normal deps entries:

kotlin_apple_framework produces a framework that an application or test can link and embed.
rust_mobile_library produces an Apple static library for an Apple consumer.

Add these only after the application builds on its own, then query the consumer again to confirm that the dependency contract is satisfied.

macOS Applications and Distribution#

Materialize the macOS starter in an empty directory:

bash

once edit materialize-example apple_application apple-application-macos
once build Hello
once run Hello

The starter loads a text resource through Bundle.main. macOS applications use the native Contents/MacOS, Contents/Resources, and Contents/Frameworks layout. Framework dependencies automatically receive the @executable_path/../Frameworks runpath. Declare system frameworks with sdk_frameworks, not custom linker or SDK search-path scripts.

Existing scripts that assumed a flat macOS bundle must use the new paths. Native Xcode script phases receive the corresponding EXECUTABLE_PATH, INFOPLIST_PATH, and UNLOCALIZED_RESOURCES_FOLDER_PATH settings. iOS bundle paths are unchanged. When an existing generated macOS bundle has a root Info.plist, Once removes that legacy product before rebuilding so obsolete flat files do not invalidate the new bundle's signature.

Versioned prebuilt frameworks retain their symlinks and nested code. Once copies and ad-hoc signs the embedded copy, without changing the imported framework. Do not add a root _CodeSignature directory or signature-forwarding symlink: signing captures the complete framework tree, including the version's actual signature. apple_xcframework_import selects a matching slice from an XCFramework. Other archive layouts still require a project module; the built-in archive_download currently accepts ZIP, not tar archives.

Keep Release Credentials Outside Cached Builds#

once build produces an ad-hoc signed bundle for local use. Developer ID signing and notarization are separate release steps, not postbuild_actions, annotated once exec scripts, or remotely cached target actions. Keep private keys, keychain passwords, provisioning profiles, and notary credentials outside the workspace and Once's declared inputs, environment, outputs, and logs.

Build first without release credentials. In a separate release job, copy the bundle into a private temporary directory. Import the authorized Developer ID Application certificate into an isolated keychain and store notarization credentials in a notarytool keychain profile. Avoid changing the machine's default keychain or search list. Disable shell tracing, delete temporary keychains on failure as well as success, and never publish the temporary directory as a build artifact.

For the starter, which has no nested code or restricted entitlements, the following release script signs and notarizes only its private copy. Supply DEVELOPER_ID_SHA1 as the selected certificate fingerprint, SIGNING_KEYCHAIN as the isolated keychain path, and NOTARY_PROFILE as its credential profile name. These selectors are not passwords. The final ZIP is written to a new dist directory, after notarization and local policy checks succeed:

bash

#!/bin/sh
set -eu
umask 077
: "${DEVELOPER_ID_SHA1:?Select a Developer ID Application certificate}"
: "${SIGNING_KEYCHAIN:?Provide an isolated signing keychain}"
: "${NOTARY_PROFILE:?Provide a notarytool credential profile}"
test ! -e dist
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
trap 'exit 130' INT
trap 'exit 143' TERM
app="$work/Hello.app"
ditto .once/out/Hello/Hello.app "$app"
codesign --force --sign "$DEVELOPER_ID_SHA1" --keychain "$SIGNING_KEYCHAIN" \
  --options runtime --timestamp "$app"
codesign --verify --deep --strict "$app"
ditto -c -k --sequesterRsrc --keepParent "$app" "$work/submission.zip"
xcrun notarytool submit "$work/submission.zip" --wait \
  --keychain "$SIGNING_KEYCHAIN" --keychain-profile "$NOTARY_PROFILE" \
  --output-format json > "$work/notarization.json"
test "$(plutil -extract status raw -o - "$work/notarization.json")" = Accepted
xcrun stapler staple "$app"
xcrun stapler validate "$app"
codesign --verify --deep --strict "$app"
spctl --assess --type execute "$app"
mkdir dist
ditto -c -k --sequesterRsrc --keepParent "$app" dist/Hello-macos.zip

Run this as an ordinary shell script, outside Once. Its caller owns keychain creation and cleanup. Never sign, change a property list, or staple the bundle under .once/out in place. Create update signatures and checksums from the final stapled ZIP, not the submission archive.

For applications with nested helpers, frameworks, XPC services, or extensions, sign each nested executable and bundle inside out before the enclosing application. Use application-specific entitlements for each component, and do not use codesign --deep to sign. Apps with restricted capabilities such as push notifications must validate the profile's team, application identifier, expiration, signing certificate, and authorized entitlements before signing. Do not strip these entitlements or replace them with ad-hoc signing to make validation pass. The minimal starter script does not implement provisioning or nested-code signing. See Apple's code signing guidance and notarization workflow for distribution requirements.

Supported Target Kinds and Limitations#

Use the target kind reference for the contract that matches the artifact:

Provisioning profiles, signing identities, and non-ad-hoc signing are accepted by the schema but are not supported yet. Using a non-empty value for one of these attributes fails validation before the build starts.

Next#

Continue with Memory once the application builds and tests. It shows how Once records durable context about graph work. If the application also contains Android or Rust code, use Ecosystems to choose the next independent integration.