API notes provide a mechanism by which Objective-C APIs can be annotated with additional semantic information not present within the original Objective-C headers. This semantic information can then be used by the Swift compiler when importing the corresponding Objective-C module to provide a better mapping of Objective-C APIs into Swift.
API notes are organized into a set of .apinotes files. Each .apinotes file contains annotations for a single Objective-C module, written in YAML (FIXME: to be) described below. These YAML sources must be manually compiled into a binary representation (.apinotesc) that the Swift compiler will lazily load when it builds code, also described below.
TBD...
The Swift compiler lazily loads API notes from compiled API notes files (.apinotesc files) and uses these annotations to affect the Swift signatures of imported Objective-C APIs. Compiled API notes files reside in the Swift module directory, i.e., the same directory where the .swiftmodule file would reside for the Swift overlay of that module. For system modules, the path depends on the platform and architecture.
| Platform | Path |
|---|---|
| macOS | $SWIFT_EXEC/lib/swift/macosx/ |
| iOS (32-bit) | $SWIFT_EXEC/lib/swift/iphoneos/32 |
| iOS (64-bit) | $SWIFT_EXEC/lib/swift/iphoneos |
| iOS Simulator (32-bit) | $SWIFT_EXEC/lib/swift/iphonesimulator/32 |
| iOS Simulator (64-bit) | $SWIFT_EXEC/lib/swift/iphonesimulator |
where $SWIFT_EXEC/bin/swift is the path to the Swift compiler executable.
When updating API notes for a system module, recompile the API notes and place the result in the appropriate directories listed above. The Swift compiler itself need not be recompiled except in rare cases where the changes affect how the SDK overlays are built. To recompile API notes for a given module $MODULE and place them into their
xcrun swift -apinotes -yaml-to-binary -target x86_64-apple-macosx10.10 -o $SWIFT_EXEC/lib/swift/macosx/$MODULE.apinotesc $MODULE.apinotes
xcrun swift -apinotes -yaml-to-binary -target armv7-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphoneos/32/$MODULE.apinotesc $MODULE.apinotes
xcrun swift -apinotes -yaml-to-binary -target arm64-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphoneos/$MODULE.apinotesc $MODULE.apinotes
xcrun swift -apinotes -yaml-to-binary -target i386-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphonesimulator/32/$MODULE.apinotesc $MODULE.apinotes
xcrun swift -apinotes -yaml-to-binary -target x86_64-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphonesimulator/$MODULE.apinotesc $MODULE.apinotes
To add API notes for a system module $MODULE that does not have them yet, create a new source file $MODULE.apinotes and update CMakeLists.txt. Updated API notes will be found by the build system during the next build.
Note that Swift provides decompilation of binary API notes files via the -apinotes -binary-to-yaml option, which allows one to inspect the information the compiler is using internally. The order of the entities in the original YAML input is not preserved, so all entities in the resulting YAML output are sorted alphabetically.