Merge branch 'master' into feature/easier-install

Author: BrandonMathis

.gitignore

@@ -36,3 +36,9 @@ docs/_build
 
 # Finder metadata
 .DS_Store
+
+#==============================================================================#
+# Ignore CMake temporary files
+#==============================================================================#
+CMakeCache.txt
+CMakeFiles

CMakeLists.txt

@@ -289,7 +289,7 @@ if(NOT EXISTS "${CLANG_MAIN_INCLUDE_DIR}/clang/AST/Decl.h")
 endif()
 
 # This could be computed using ${CMAKE_CFG_INTDIR} if we want to link Swift
-# against a mathing LLVM build configuration.  However, we usually want to be
+# against a matching LLVM build configuration.  However, we usually want to be
 # flexible and allow linking a debug Swift against optimized LLVM.
 set(LLVM_RUNTIME_OUTPUT_INTDIR "${LLVM_BINARY_DIR}")
 set(LLVM_LIBRARY_OUTPUT_INTDIR "${LLVM_LIBRARY_DIR}")

README.md

@@ -2,7 +2,7 @@
 
 **Welcome to Swift!**
 
-Swift is a high performance systems programming language.  It has a clean
+Swift is a high-performance system programming language.  It has a clean
 and modern syntax, and offers seamless access to existing C and Objective-C code
 and frameworks, and is memory safe (by default).
 
@@ -18,20 +18,20 @@ modules, eliminating the need for headers and the code duplication they entail.
 To read the documentation, start by installing the Sphinx documentation
 generator tool (http://sphinx-doc.org, just run `easy_install -U Sphinx` from
 the command line and you're good to go).  Once you have that, you can build the
-swift documentation by going into `swift/docs` and typing `make`.  This compiles
-the 'rst' files in the docs directory into HTML in the `swift/docs/_build/html`
+Swift documentation by going into `docs` and typing `make`.  This compiles
+the `.rst` files in the `docs` directory into HTML in the `docs/_build/html`
 directory.
 
-Once built, the best place to start is with the swift whitepaper, which gives a
-tour of the language (in `swift/docs/_build/html/whitepaper/index.html`).
+Once built, the best place to start is with the Swift white paper, which gives a
+tour of the language (in `docs/_build/html/whitepaper/index.html`).
 Another potentially useful document is `docs/LangRef`, which gives a low level
 tour of how the language works from the implementation perspective.
 
 Many of the docs are out of date, but you can see some historical design
 documents in the `docs` directory.
 
-Another source of documentation is the standard library itself, located at
-`swift/stdlib`.  Much of the language is actually implemented in the library
+Another source of documentation is the standard library itself, located in
+`stdlib`.  Much of the language is actually implemented in the library
 (including `Int`), and the standard library gives some examples of what can be
 expressed today.
 
@@ -66,9 +66,31 @@ compiler for C++14 support and create a symlink:
 
 ### Getting Sources for Swift and Related Projects
 
+	For those checking out sources as read-only:
+
      git clone https://github.com/apple/swift.git swift
-     cd swift
-     ./utils/update-checkout --clone
+     git clone https://github.com/apple/swift-llvm.git llvm
+     git clone https://github.com/apple/swift-clang.git clang
+     git clone https://github.com/apple/swift-lldb.git lldb
+     git clone https://github.com/apple/swift-cmark.git cmark
+     git clone https://github.com/apple/swift-llbuild.git llbuild
+     git clone https://github.com/apple/swift-package-manager.git swiftpm
+     git clone https://github.com/apple/swift-corelibs-xctest.git
+     git clone https://github.com/apple/swift-corelibs-foundation.git
+
+	For those who plan on regular making direct commits, cloning over
+	SSH may provide a better experience (which requires uploading 
+	SSH keys to GitHub):
+
+     git clone [email protected]:apple/swift.git swift
+     git clone [email protected]:apple/swift-llvm.git llvm
+     git clone [email protected]:apple/swift-clang.git clang
+     git clone [email protected]:apple/swift-lldb.git lldb
+     git clone [email protected]:apple/swift-cmark.git cmark
+     git clone [email protected]:apple/swift-llbuild.git llbuild
+     git clone [email protected]:apple/swift-package-manager.git swiftpm
+     git clone [email protected]:apple/swift-corelibs-xctest.git
+     git clone [email protected]:apple/swift-corelibs-foundation.git
 
 [CMake](http://cmake.org) is the core infrastructure used to configure builds of
 Swift and its companion projects; at least version 2.8.12.2 is required. Your
@@ -79,18 +101,22 @@ command line tools to your `PATH`:
 
     export PATH=/Applications/CMake.app/Contents/bin:$PATH
 
-[Ninja](http://martine.github.io/ninja/) is the current recommended build system
+[Ninja](https://ninja-build.org) is the current recommended build system
 for building Swift and is the default configuration generated by CMake. If
 you're on OS X or don't install it as part of your Linux distribution, clone
 it next to the other projects and it will be bootstrapped automatically:
 
     git clone [email protected]:martine/ninja.git
 
-You can also use a third-party packaging tool like [Homebrew](http://brew.sh) to
-install CMake and Ninja on OS X:
+You can also install CMake and Ninja on OS X using a third-party
+packaging tool like [Homebrew](http://brew.sh)…
 
     brew install cmake ninja
 
+…or [MacPorts](https://macports.org).
+
+    sudo port install cmake ninja
+
 ### Building Swift
 
 The `build-script` is a high-level build automation script that supports basic
@@ -100,30 +126,30 @@ supports presets which you can define for common combinations of build options.
 
 To find out more:
 
-    swift/utils/build-script -h
+    utils/build-script -h
 
 Note: Arguments after "--" above are forwarded to `build-script-impl`, which is
 the ultimate shell script that invokes the actual build and test commands.
 
 A basic command to build Swift and run basic tests with Ninja:
 
-    swift/utils/build-script -t
+    utils/build-script -t
 
-## Develop Swift in Xcode
+## Developing Swift in Xcode
 
 The Xcode IDE can be used to edit the Swift source code, but it is not currently
 fully supported as a build environment for SDKs other than OS X. If you'd like
 to build for other SDKs but still use Xcode, once you've built Swift using Ninja
 or one of the other supported CMake generators, you can set up an IDE-only Xcode
 environment using the build-script's `-X` flag:
 
-    swift/utils/build-script -X --skip-build -- --reconfigure
+    utils/build-script -X --skip-build -- --reconfigure
 
-The `--skip-build` flag tells build-script to only generate the project,
+The `--skip-build` flag tells `build-script` to only generate the project,
 not build it in its entirety. A bare minimum of LLVM tools will build in order
 to configure the Xcode projects.
 
-The `--reconfigure` flag tells build-script-impl to run the CMake configuration
+The `--reconfigure` flag tells `build-script-impl` to run the CMake configuration
 step even if there is a cached configuration. As you develop in Xcode, you may
 need to rerun this from time to time to refresh your generated Xcode project,
 picking up new targets, file removals, or file additions.
@@ -135,3 +161,14 @@ See [docs/Testing.rst](docs/Testing.rst).
 ## Contributing to Swift
 
 Contributions to Swift are welcomed and encouraged! Please see the [Contributing to Swift guide](https://swift.org/contributing/).
+
+To be a truly great community, Swift.org needs to welcome developers from all
+walks of life, with different backgrounds, and with a wide range of experience.
+A diverse and friendly community will have more great ideas, more unique
+perspectives, and produce more great code. We will work diligently to make the
+Swift community welcoming to everyone.
+
+To give clarity of what is expected of our members, Swift has adopted the
+code of conduct defined by the Contributor Covenant. This document is used
+across many open source communities, and we think it articulates our values
+well. For more, see [the website](https://swift.org/community/#code-of-conduct).

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.

apinotes/README.txt

@@ -1,6 +1,6 @@
 include(CMakeParseArguments)
 
-# Use ${cmake_2_8_12_KEYWORD} intead of KEYWORD in target_link_libraries().
+# Use ${cmake_2_8_12_KEYWORD} instead of KEYWORD in target_link_libraries().
 # These variables are used by LLVM's CMake code.
 set(cmake_2_8_12_INTERFACE INTERFACE)
 set(cmake_2_8_12_PRIVATE PRIVATE)
@@ -29,7 +29,7 @@ endif()
 #     Path to llvm include directory.
 #
 #   [OBJ_ROOT_DIR objRootDir]
-#     Path tp llvm build tree.
+#     Path to llvm build tree.
 #
 #   [SOURCE_DIR srcDir]
 #     Path to llvm source tree.

cmake/modules/SwiftSharedCMakeConfig.cmake

@@ -12,7 +12,7 @@ Hard Constraints on Resilience
 ------------------------------
 
 The root of a class hierarchy must remain stable, at pain of
-invalidating the metaclass hierarchy.  Note a Swift class without an
+invalidating the metaclass hierarchy.  Note that a Swift class without an
 explicit base class is implicitly rooted in the SwiftObject
 Objective-C class.
 
@@ -992,7 +992,7 @@ mangled in to disambiguate.
     impl-callee-convention impl-function-attribute* generic-signature? '_'
     impl-parameter* '_' impl-result* '_'
   impl-callee-convention ::= 't'              // thin
-  impl-callee-convention ::= impl-convention  // thick, callee transfered with given convention
+  impl-callee-convention ::= impl-convention  // thick, callee transferred with given convention
   impl-convention ::= 'a'                     // direct, autoreleased
   impl-convention ::= 'd'                     // direct, no ownership transfer
   impl-convention ::= 'D'                     // direct, no ownership transfer,

docs/ABI.rst

@@ -62,7 +62,7 @@ Identity`` (RC Identity) and RC Identity preserving instructions. An instruction
 ``I`` with n SSA arguments and m SSA results is (i,j) RC Identity preserving if
 performing a ``retain_value`` on the ith SSA argument immediately before ``I``
 is executed is equivalent to performing a ``retain_value`` on the jth SSA result
-of ``I`` immediately following the exection of ``I``. For example in the
+of ``I`` immediately following the execution of ``I``. For example in the
 following, if::
 
     retain_value %x
@@ -151,7 +151,7 @@ referent. Consider the following sequence of rules:
     is deallocated.
 
 (3) A different source-level variable pointing at the same referent
-    must not be changed/invalidated by such a call
+    must not be changed/invalidated by such a call.
 
 (4) If such a variable exists, the compiler must guarantee the
     refcount is > 1 going into the call.