diff --git a/apinotes/README.md b/apinotes/README.md new file mode 100644 index 0000000000000..f5d8858d4dedf --- /dev/null +++ b/apinotes/README.md @@ -0,0 +1,81 @@ +# API Notes README + +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. + +# API Notes YAML Format + +TBD... + +# Compiling API notes + +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 +:------------- | :------------- + OSX | `$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 + +### OSX +``` +xcrun swift -apinotes -yaml-to-binary -target x86_64-apple-macosx10.10 -o $SWIFT_EXEC/lib/swift/macosx/$MODULE.apinotesc $MODULE.apinotes +``` + +### iOS (32-bit) +``` +xcrun swift -apinotes -yaml-to-binary -target armv7-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphoneos/32/$MODULE.apinotesc $MODULE.apinotes +``` + +### iOS (64-bit) +``` +xcrun swift -apinotes -yaml-to-binary -target arm64-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphoneos/$MODULE.apinotesc $MODULE.apinotes +``` + +### iOS Simulator (32-bit) +``` +xcrun swift -apinotes -yaml-to-binary -target i386-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphonesimulator/32/$MODULE.apinotesc $MODULE.apinotes +``` + +### iOS Simulator (64-bit) +``` +xcrun swift -apinotes -yaml-to-binary -target x64_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`. Newly-added API notes will require +re-running CMake. 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. diff --git a/apinotes/README.txt b/apinotes/README.txt deleted file mode 100644 index 43def03f148eb..0000000000000 --- a/apinotes/README.txt +++ /dev/null @@ -1,74 +0,0 @@ -//===----------------------------------------------------------------------===// -// API Notes README -//===----------------------------------------------------------------------===// - -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. - -//------------------------------------------------------------------------------ -// API Notes YAML Format -//------------------------------------------------------------------------------ - -TBD... - -//------------------------------------------------------------------------------ -// Compiling API notes -//------------------------------------------------------------------------------ -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 - - OSX $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 - - # OSX - xcrun swift -apinotes -yaml-to-binary -target x86_64-apple-macosx10.10 -o $SWIFT_EXEC/lib/swift/macosx/$MODULE.apinotesc $MODULE.apinotes - - # iOS (32-bit) - xcrun swift -apinotes -yaml-to-binary -target armv7-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphoneos/32/$MODULE.apinotesc $MODULE.apinotes - - # iOS (64-bit) - xcrun swift -apinotes -yaml-to-binary -target arm64-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphoneos/$MODULE.apinotesc $MODULE.apinotes - - # iOS Simulator (32-bit) - xcrun swift -apinotes -yaml-to-binary -target i386-apple-ios7.0 -o $SWIFT_EXEC/lib/swift/iphonesimulator/32/$MODULE.apinotesc $MODULE.apinotes - - # iOS Simulator (64-bit) - xcrun swift -apinotes -yaml-to-binary -target x64_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. Newly-added API notes will require -re-running CMake. 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.