`apple_application`

Apple application bundle.

Description#

Builds an Apple application bundle with a generated Info.plist property-list file, linked dependencies, embedded frameworks, and ad-hoc signing. The run capability builds the required bundle and launches it. Attributes whose names contain sdk configure the Apple software development kit (SDK) used for the build.

Framework dependencies are transitive at runtime. Declare the framework the application imports directly. Once links the direct dynamic boundary, embeds its complete framework closure, removes duplicate paths, signs every embedded framework, and then signs the application.

Attributes#

explicit_modules is a boolean, defaulting to false, that enables compiler-scanned, cacheable Swift and Clang module actions. dependency_check accepts "off" (the default) or "error"; checking requires explicit modules. See explicit modules for native propagation, dependency errors, and current limitations. The resolver-owned _declared_deps metadata preserves declarations before import inference and should not be authored manually.

Attribute	Type	Required	Default	Description
`platform`	string	yes		Apple platform for the application
`bundle_id`	string	yes		Application bundle identifier
`minimum_os`	string	no	`13.0`	Minimum supported operating system version
`target_sdk_version`	string	no	`minimum_os`	Software development kit version used in the target triple
`sdk_variant`	string	no	`simulator`	`simulator` or `device`; ignored on macOS (not configurable)
`xcode_developer_dir`	string	no	active Xcode	Xcode developer directory used to resolve build tools
`families`	list<string>	no	`[]`	Supported device families (`iphone`, `ipad`); an empty list uses `iphone`
`product_name`	string	no	target name	Application product name (not configurable)
`module_name`	string	no	product name	Swift module name (not configurable)
`resources`	list<string>	no	`[]`	Resource files and directory roots placed in the application bundle
`structured_resources`	list<string>	no	`[]`	Resource directory roots whose own basename is preserved inside the application bundle
`asset_catalogs`	list<string>	no	`[]`	Asset catalog paths compiled into the application bundle
`info_plist`	string	no		Info.plist template path
`info_plist_substitutions`	map<string,string>	no	`{}`	Values substituted into the generated Info.plist
`entitlements`	string	no		Entitlements plist path
`entitlements_substitutions`	map<string,string>	no	`{}`	Build-setting values substituted into `$(NAME)` or `${NAME}` placeholders before signing
`development_team`	string	no		Apple development team identifier used to derive simulator application identity
`provisioning_profile`	string	no		Provisioning profile label or path used for signing
`signing_identity`	string	no		Local signing identity selector used for development device signing
`signing`	string	no	`ad_hoc`	Signing mode or policy name
`sdk_frameworks`	list<string>	no	`[]`	Apple software development kit frameworks linked by name
`weak_sdk_frameworks`	list<string>	no	`[]`	Apple software development kit frameworks linked weakly
`sdk_dylibs`	list<string>	no	`[]`	Apple software development kit dynamic libraries linked by name
`linkopts`	list<string>	no	`[]`	Extra linker flags
`swift_flags`	list<string>	no	`[]`	Extra Swift compiler flags
`clang_flags`	list<string>	no	`[]`	Extra Clang compiler flags for C, C++, Objective-C, and Objective-C++ sources
`per_source_clang_flags`	map<string,string>	no	`{}`	JSON-encoded Clang compiler flag lists keyed by source path
`defines`	list<string>	no	`[]`	Compatibility conditions passed to both Swift and Clang
`swift_defines`	list<string>	no	`[]`	Swift conditional compilation conditions
`clang_defines`	list<string>	no	`[]`	C-family preprocessor definitions
`exported_header_dirs`	list<string>	no	`[]`	Header search directories exported by the application target
`private_header_dirs`	list<string>	no	`[]`	Private header search directories used while compiling the application
`private_headers`	list<string>	no	`[]`	Private header files required while compiling the application
`bridging_header`	string	no		Objective-C bridging header imported into Swift sources
`prefix_header`	string	no		Prefix header included before every C-family source
`prebuild_actions`	list<string>	no	`[]`	Adapter-owned serialized build preparation actions that run before compilation. Records may opt into caching when they declare complete inputs and outputs; always-run records remain uncached
`application_extension`	bool	no	`false`	Build as an app extension: entered through `NSExtensionMain` and compiled against the app-extension-safe interface
`app_icon`	string	no		Asset catalog app-icon set name compiled into the application icon
`enable_testing`	bool	no	`false`	Compile Swift with testability enabled so hosted test bundles can use `@testable import`

For simulator applications, processed platform entitlements are embedded in the executable's __TEXT,__entitlements and __TEXT,__ents_der sections. When development_team is set, Once also derives the application-identifier entitlement from the team and bundle identifiers so application-group containers work in the simulator. The bundle is then signed without those platform entitlements, matching Swift Build and the Apple Bazel rules. Device applications pass the processed entitlement file to code signing instead.

The prepackage_actions attribute accepts an ordered list<string> of serialized script records, defaulting to []. These run after linking and before resource processing, so generated resources feed packaging.

The postbuild_actions attribute accepts an ordered list<string> of serialized script records, defaulting to []. These actions run after product assembly and before final signing. Complete declarations may be cached; untracked scripts rerun and publish changes to known product files. See native script phases for mapped build settings and file-list variables.

Dependency Edges#

Edge	Accepts	Description
`deps`	`apple_linkable`, `apple_framework`, `apple_resource`, `apple_swift_plugin`, `native_linkable`	Libraries, frameworks, resources, native linkables, and Swift compiler plugins embedded in the app

Transitive library resource bundles are embedded at the application root. Interface files and managed object models are compiled before each resource bundle and the outer application are signed.

Providers#

The target emits apple_application and apple_bundle. Hosted test bundles also receive the application's transitive Swift module directories and exact module artifacts, header search directories, generated compatibility headers, framework inputs, and virtual file-system overlays. This keeps an application's bridging-header environment intact when the test compiler imports its testable module. The application provider also exposes its executable so a hosted test bundle can use it as the linker's bundle loader.

Capabilities#

Capability	Output groups	Requires
`build`	`default`, `bundle`, `dsyms`
`run`	`default`	`bundle`

Outputs#

Output	Location
Application bundle	`.once/out/<target>/<product_name>.app`
Executable	`.once/out/<target>/<product_name>.app/<product_name>`
Swift compatibility header	`.once/out/<target>/<module_name>-Swift.h` for mixed Swift and Objective-C targets
Property list	`.once/out/<target>/<product_name>.app/Info.plist`
Embedded frameworks	`.once/out/<target>/<product_name>.app/Frameworks` when the target depends on frameworks
Embedded resource bundles	`.once/out/<target>/<product_name>.app/*.bundle` when dependencies propagate resources
Code signature	`.once/out/<target>/<product_name>.app/_CodeSignature/CodeResources`
Run record	`.once/out/<target>/run/run.json` after `once run`
Run log	`.once/out/<target>/run/run.log` after `once run`

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

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