apple_library

Swift, Objective-C, C, and C++ static library.

Description#

Routes each source file through the driver that matches its extension and emits a .a archive together with the Swift module triple, ObjC interop header, and (optionally) a clang modulemap and binary header map. Multi-arch targets fan out per-arch compiles and merge them with lipo.

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.

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#

A dependency that exposes a compiler-plugin executable (see swift_macro) is auto-detected and loaded with its declaring module. The resulting transitive_plugin_executables field keeps the host tool available to downstream targets that use a macro declared by the library. Library-style compiler plugins remain supported through transitive_plugin_dylibs.

When resource_bundle_name is set, the target creates a resource bundle and propagates it through static library dependencies to the final application. Directory roots are merged at the bundle root unless listed in structured_resources. Localized directories retain their structure, interface files are compiled, and managed object models are compiled into runtime model bundles. The final application embeds and signs each propagated resource bundle before signing its outer bundle.

Providers#

The target emits apple_linkable and apple_module.

Capabilities#

Compile pipeline#

Each source extension routes to a different driver:

• Swift sources use one compiler action to emit the module, compatibility header, and object files. A separate archive action packages the objects. A bridging_header plumbs in via -import-objc-header so Swift can see Objective-C symbols.
• ObjC, C, and C++ sources each become an independent xcrun --sdk <sdk> clang -c action that writes one .o per source. The clang invocation pulls the SDK sysroot from xcrun --show-sdk-path, targets the active triple, and enables ARC for ObjC.
• Mixed-language libraries combine the Swift archive and per-source Clang objects with the platform archive tool. Swift-only libraries use their Swift archive directly, while Clang-only libraries archive their objects once.
• Multi-arch targets repeat the swift + clang + libtool chain per architecture, then run xcrun lipo -create on the per-arch archives to produce the final universal archive. Single-arch targets skip lipo entirely.

Dep swiftmodule directories are forwarded as -I search paths so import statements resolve. With enable_modules = true the impl writes a module.modulemap from exported_headers, threads it into consumers through the provider, and also writes a binary header map (<module_name>.hmap) mapping each exported header's basename and <module_name>/<basename> form to its workspace-relative path. The hmap is passed to clang and swiftc via -I, covering the #include "Foo.h" and #include <Module/Foo.h> lookup styles a modulemap alone does not.

The action cache key composes the resolved toolchain identity (each of swiftc, clang, libtool, and lipo carries its own xcrun-resolved path, version banner, and any DEVELOPER_DIR override), source content, and declared generated inputs. Imported Swift modules are fingerprinted by their artifact content. A private implementation edit that preserves a module can therefore reuse downstream compilation, while the changed archive still participates in later link actions.

Provider record#

apple_library returns a record consumers read through ctx["deps"]. Fields:

Downstream Apple targets use this record to collect the complete compile and link context without inspecting the dependency's target kind. Dynamic framework dependencies continue through static libraries automatically, so a final application or test does not repeat dependencies that it never imports.

Configurable attributes#

Every attribute except module_name, archs, platform, sdk_variant, and mac_catalyst accepts a select value. Configuration tokens for matching come from the target's resolved literal values:

Branch keys can combine tokens with : (e.g. ios:simulator); when several branches match the longest matching key wins. A default branch is selected when no other branch matches.

See Choose Values by Configuration for the guided overview.

Outputs#

Example#