Building and Signing

Building and signing

For hosted downloads, start with Installing. This page describes the source checkout, not release-specific installation instructions.

Source of truth and prerequisites

Use Xcode with the SDKs required by the checked-out configuration and install XcodeGen. Inspect project.yml for current SDK/deployment targets; app and DriverKit deployment settings are distinct.

project.yml owns targets, build settings, entitlements wiring, and schemes. ASFW.xcodeproj is generated and committed for Xcode Cloud. Never hand-edit its project file. Update YAML, run xcodegen generate, and include the regenerated project when sources/settings change. The AudioDriverKit lab has its own project specification.

Build from the project root

./build.sh --config Release --no-bump
./build.sh --verbose --config Debug --no-bump

build.sh regenerates the project and invokes Xcode. Normal builds currently pass CODE_SIGNING_ALLOWED=NO; the result is unsigned, regardless of a signing team configured in YAML. The default configuration is Debug. Release output is normally:

build/DerivedData/Build/Products/Release/ASFW.app

Without --no-bump, a normal build increments version metadata. Use that only when you intend the change; do not accidentally modify tracked version files for a check. --derived PATH changes the output location. See ./build.sh --help for supported flags.

Current DriverKit architecture settings are x86_64 arm64e for Debug and x86_64 arm64 for Release, with Release ONLY_ACTIVE_ARCH=NO. A build slice is not proof of installability. Production .iig generation and installable .dext output require Xcode; host CMake builds do not replace this workflow.

Signing paths and their limits

Hosted builds use Developer ID signing, the required provisioning profiles and entitlements, and notarization. A paid developer account alone does not grant every restricted DriverKit entitlement. Ordinary users should use the hosted distribution.

sign.sh ad-hoc signs the embedded dext first and then the enclosing app, using repository entitlement plists. It checks that relevant entitlements were embedded; that is not proof of launch, matching, runtime stability, or compatibility with SIP enabled.

./sign.sh /absolute/path/to/ASFW.app

Warning

The current ad-hoc path needs validation before installation. project.adhoc.yml sets ad-hoc signing and Hardened Runtime enabled, while repository engineering guidance requires Hardened Runtime disabled for ad-hoc DriverKit testing under the documented AMFI bypass conditions. build.sh --adhoc still invokes an unsigned build, and sign.sh contains historical setup claims. Do not treat these as a verified end-to-end recipe. Resolve the mismatch and validate the exact build/profile locally before recommending installation. This documentation cleanup does not change settings.

Direct Xcode signing depends on the selected configuration, available identities, profiles, and entitlement approval. Inspect the final app and dext rather than assuming Xcode made a distributable artifact.

Tests and analysis

./build.sh --test-only
./build.sh --test-only --test-filter Pattern
./build.sh --test-only --asan
./build.sh --swift-test-only
./build.sh --swift-coverage
./build.sh --commands --no-bump

C++ host tests use ASFW_HOST_TEST and do not exercise real hardware or DriverKit service lifetime. Swift tests cover app behavior and decoding. --commands performs an Xcode build to emit compilation commands; it is not a read-only source scan. AudioDriverKit lifecycle questions require empirical validation, not an assumption from host tests or API signatures. The maintainer keeps an isolated local lab for this; it is no longer tracked here and is intended for a separate project.

Read CONTRIBUTING.md and Architecture Overview before changing shared behavior.