Merge pull request #592 from ddunbar/swift-3-rebranch

Rebranch swift-package-manager for swift-3.0.

Author: ddunbar

Documentation/Usage.md

@@ -11,6 +11,7 @@
   * [Build an Executable](#build-an-executable)
   * [Create a Package](#create-a-package)
   * [Distribute a Package](#distribute-a-package)
+  * [Handling version-specific logic](#version-specific-logic)
 * [Reference](Reference.md)
 * [Resources](Resources.md)
 
@@ -323,3 +324,76 @@ import Foundation
 ## Distribute a Package
 
 *Content to come.*
+
+## Handling version-specific logic
+
+The package manager is designed to support packages which work with a variety of
+Swift project versions, including both the language and the package manager version.
+
+In most cases, if you want to support multiple Swift versions in a package you
+should do so by using the language-specific version checks available in the
+source code itself. However, in some circumstances this may become
+unmanageable; in particular, when the package manifest itself cannot be written
+to be Swift version agnostic (for example, because it optionally adopts new
+package manager features not present in older versions).
+
+The package manager has support for a mechanism to allow Swift version-specific
+customizations for the both package manifest and the package versions which will
+be considered.
+
+### Version-specific tag selection
+
+The tags which define the versions of the package available for clients to use
+can _optionally_ be suffixed with a marker in the form of `@swift-3`. When the
+package manager is determining the available tags for a repository, _if_ a
+version-specific marker is available which matches the current tool version,
+then it will *only* consider the versions which have the version-specific
+marker. Conversely, version-specific tags will be ignored by any non-matching
+tool version.
+
+For example, suppose the package `Foo` has the tags
+`[1.0.0, 1.2.0@swift-3, 1.3.0]`. If version 3.0 of the package manager is
+evaluating the available versions for this repository, it will only ever
+consider version `1.2.0`. However, version 4.0 would consider only `1.0.0` and
+`1.3.0`.
+
+This feature is intended for use in the following scenarios:
+
+1. A package wishes to maintain support for Swift 3.0 in older versions, but
+   newer versions of the package require Swift 4.0 for the manifest to be
+   readable. Since Swift 3.0 will not know to ignore those versions, it would
+   fail when performing dependency resolution on the package if no action is
+   taken. In this case, the author can re-tag the last versions which supported
+   Swift 3.0 appropriately.
+
+2. A package wishes to maintain dual support for Swift 3.0 and Swift 4.0 at the
+   same version numbers, but this requires substantial differences in the
+   code. In this case, the author can maintain parallel tag sets for both
+   versions.
+
+It is *not* expected the packages would ever use this feature unless absolutely
+necessary to support existing clients. In particular, packages *should not*
+adopt this syntax for tagging versions supporting the _latest GM_ Swift version.
+
+The package manager supports looking for any of the following marked tags, in
+order of preference:
+
+1. `MAJOR.MINOR.PATCH` (e.g., `[email protected]`)
+2. `MAJOR.MINOR` (e.g., `[email protected]`)
+3. `MAJOR` (e.g., `1.2.0@swift-3`)
+
+### Version-specific manifest selection
+
+The package manager will additionally look for a version-specific marked
+manifest version when loading the particular version of a package, by searching
+for a manifest in the form of `[email protected]`. The set of markers looked
+for is the same as for version-specific tag selection.
+
+This feature is intended for use in cases where a package wishes to maintain
+compatibility with multiple Swift project versions, but requires a substantively
+different manifest file for this to be viable (e.g., due to changes in the
+manifest API).
+
+It is *not* expected the packages would ever use this feature unless absolutely
+necessary to support existing clients. In particular, packages *should not*
+adopt this syntax for tagging versions supporting the _latest GM_ Swift version.

Package.swift

@@ -43,7 +43,8 @@ let package = Package(
         Target(
             /** Abstractions for common operations, should migrate to Basic */
             name: "Utility",
-            dependencies: ["POSIX", "Basic"]),
+            dependencies: ["POSIX", "Basic", "PackageDescription"]),
+            // FIXME: We should be kill the PackageDescription dependency above.
         Target(
             /** Source control operations */
             name: "SourceControl",
@@ -111,6 +112,9 @@ let package = Package(
 
         // MARK: Additional Test Dependencies
 
+        Target(
+            name: "BasicTests",
+            dependencies: ["TestSupport"]),
         Target(
             name: "BuildTests",
             dependencies: ["Build", "TestSupport"]),

README.md

@@ -1,10 +1,10 @@
 # Swift Package Manager Project
 
-> **PLEASE NOTE** The Swift Package Manager is still in early design and development — we are aiming to have it stable and ready for use with Swift 3 but currently all details are subject to change and many important features are yet to be implemented. Additionally, it is important to note that the Swift language syntax is not stable, so packages you write will (likely) break as Swift evolves.
+> **PLEASE NOTE** The Swift Package Manager is still in early design and development — we are aiming to have it stable and ready for use with Swift 3 but currently all details are subject to change and many important features are yet to be implemented. Additionally, it is important to note that the Swift language syntax is not stable, so packages you write will (likely) break as Swift evolves.
 
 The Swift Package Manager is a tool for managing distribution of source code, aimed at making it easy to share your code and reuse others’ code. The tool directly addresses the challenges of compiling and linking Swift packages, managing dependencies, versioning, and supporting flexible distribution and collaboration models.
 
-We’ve designed the system to make it really easy to share packages on services like GitHub, but packages are also great for private personal development, sharing code within a team, or at any other granularity.
+We’ve designed the system to make it easy to share packages on services like GitHub, but packages are also great for private personal development, sharing code within a team, or at any other granularity.
 
 ---
 
@@ -52,10 +52,6 @@ The package manager is bundled with the [**Trunk Development** Snapshots availab
 
         export TOOLCHAINS=swift
 
-* Xcode 7.2:
-
-        export PATH=/Library/Toolchains/swift-latest.xctoolchain/usr/bin:$PATH
-
 * Linux:
 
         export PATH=path/to/toolchain/usr/bin:$PATH
@@ -73,7 +69,7 @@ The following indicates you have not installed a snapshot successfully:
 
 ### Managing Swift Environments
 
-The `TOOLCHAINS` environment variable on OS X can be used to control which `swift` is instantiated:
+The `TOOLCHAINS` environment variable on OS X can be used to control which `swift` is executed:
 
 ```sh
 $ xcrun --find swift
@@ -91,13 +87,13 @@ On OS X `/usr/bin/swift` is just a stub that forwards invocations to the active
 
 To use a specific toolchain you can set `TOOLCHAINS` to the `CFBundleIdentifier` in an `.xctoolchain`’s Info.plist.
 
-This feature requires Xcode 7.3.
+This feature requires Xcode 7.3 or later.
 
 ---
 
 ## Development
 
-The Package Manager is itself a Swift Package and thus can be used to build itself. However we recommend instead one of the three following options:
+The Package Manager project is itself a Swift Package and can be used to build itself. If you are interested in contributing to the package manager, however, we recommend one of the three following options:
 
 1. Using the [Swift project `build-script`](https://github.com/apple/swift/blob/master/README.md):
 
@@ -120,19 +116,19 @@ Note that either of the latter two options may not be compatible with the `maste
 
 ### Choosing a Swift Version
 
-The `SWIFT_EXEC` environment variable specifies the `swiftc` executable path used by `swift package`. If it is not set, SwiftPM will try to locate it:
+The `SWIFT_EXEC` environment variable specifies the `swiftc` executable path used by `swift package`. If it is not set, the package manager will try to locate it:
 
-1. In `swift-package`'s parent directory. 
-2. (on OS X) by calling `xcrun --find swiftc`
-3. in PATH
+1. In `swift-package`'s parent directory.
+2. On OS X, by calling `xcrun --find swiftc`.
+3. By searching the PATH.
 
 ---
 
 ## Documentation
 
-For extensive documentation on using Swift Package Manager, creating packages, and more, see [Documentation/README](Documentation/README.md).
+For extensive documentation on using Swift Package Manager, creating packages, and more, see [Documentation](Documentation).
 
-For additional documentation on developing Swift Package Manager, see [Documentation/Internals](Documentation/Internals).
+For additional documentation on developing the Swift Package Manager itself, see [Documentation/Internals](Documentation/Internals).
 
 ---
 

Sources/Basic/Condition.swift

@@ -0,0 +1,48 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright 2016 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See http://swift.org/LICENSE.txt for license information
+ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+
+// FIXME: Temporary compatibility shims.
+#if !os(macOS)
+private typealias NSCondition = Foundation.Condition
+#endif
+
+/// A simple condition wrapper.
+public struct Condition {
+    private let _condition = NSCondition()
+
+    /// Create a new condition.
+    public init() {}
+    
+    /// Wait for the condition to become available.
+    public func wait() {
+        _condition.wait()
+    }
+
+    /// Signal the availability of the condition (awake one thread waiting on
+    /// the condition).
+    public func signal() {
+        _condition.signal()
+    }
+
+    /// Broadcast the availability of the condition (awake all threads waiting
+    /// on the condition).
+    public func broadcast() {
+        _condition.broadcast()
+    }
+    
+    /// A helper method to execute the given body while condition is locked.
+    public func whileLocked<T>(_ body: () throws -> T) rethrows -> T {
+        _condition.lock()
+        defer { _condition.unlock() }
+        return try body()
+    }
+}

Sources/Basic/GraphAlgorithms.swift

@@ -31,11 +31,11 @@ public enum GraphError: Swift.Error {
 /// - Complexity: O(v + e) where (v, e) are the number of vertices and edges
 /// reachable from the input nodes via the relation.
 public func topologicalSort<T: Hashable>(
-            _ nodes: [T], successors: @noescape (T) -> [T]) throws -> [T] {
+            _ nodes: [T], successors: (T) -> [T]) throws -> [T] {
     // Implements a topological sort via recursion and reverse postorder DFS.
     func visit(_ node: T,
                _ stack: inout OrderedSet<T>, _ visited: inout Set<T>, _ result: inout [T],
-               _ successors: @noescape (T) -> [T]) throws {
+               _ successors: (T) -> [T]) throws {
         // Mark this node as visited -- we are done if it already was.
         if !visited.insert(node).inserted {
             return

Sources/Basic/Lock.swift

@@ -12,8 +12,7 @@ import Foundation
 
 // FIXME: Temporary compatibility shims.
 #if !os(macOS)
-public typealias NSLock = Foundation.Lock
-public typealias NSCondition = Foundation.Condition
+private typealias NSLock = Foundation.Lock
 #endif
 
 /// A simple lock wrapper.
@@ -25,18 +24,9 @@ public struct Lock {
     }
 
     /// Execute the given block while holding the lock.
-    public mutating func withLock<T> (_ body: @noescape () throws -> T) rethrows -> T {
+    public mutating func withLock<T> (_ body: () throws -> T) rethrows -> T {
         _lock.lock()
         defer { _lock.unlock() }
         return try body()
     }
 }
-
-public extension NSCondition {
-    /// A helper method to execute the given body while condition is locked.
-    public func whileLocked<T>(_ body: @noescape () throws -> T) rethrows -> T {
-        lock()
-        defer { unlock() }
-        return try body()
-    }
-}

Sources/Basic/OutputByteStream.swift

@@ -192,7 +192,7 @@ public class OutputByteStream: TextOutputStream {
     }
 
     /// Write an arbitrary streamable to the buffer.
-    public final func write(_ value: Streamable) {
+    public final func write(_ value: TextOutputStreamable) {
         // Get a mutable reference.
         var stream: OutputByteStream = self
         value.write(to: &stream)
@@ -260,7 +260,7 @@ precedencegroup StreamingPrecedence {
 //
 // NOTE: It would be nice to use a protocol here and the adopt it by all the
 // things we can efficiently stream out. However, that doesn't work because we
-// ultimately need to provide a manual overload sometimes, e.g., Streamable, but
+// ultimately need to provide a manual overload sometimes, e.g., TextOutputStreamable, but
 // that will then cause ambiguous lookup versus the implementation just using
 // the defined protocol.
 
@@ -318,7 +318,7 @@ public func <<<(stream: OutputByteStream, value: ByteStreamable) -> OutputByteSt
 }
 
 @discardableResult
-public func <<<(stream: OutputByteStream, value: Streamable) -> OutputByteStream {
+public func <<<(stream: OutputByteStream, value: TextOutputStreamable) -> OutputByteStream {
     stream.write(value)
     return stream
 }

Sources/Basic/SwiftShims.swift

@@ -0,0 +1,11 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright 2016 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See http://swift.org/LICENSE.txt for license information
+ See http://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+public typealias TextOutputStreamable = Streamable

Sources/Basic/SynchronizedQueue.swift

@@ -8,22 +8,19 @@
  See http://swift.org/CONTRIBUTORS.txt for Swift project authors
 */
 
-import Foundation
-
 /// This class can be used as a shared queue between multiple threads providing
 /// thread safe APIs.
 public final class SynchronizedQueue<Element> {
-
     /// Storage for queued elements.
     private var storage: [Element]
 
     /// Condition variable to block the thread trying dequeue and queue is empty.
-    private var notEmptyCondition: NSCondition
+    private var notEmptyCondition: Condition
 
     /// Create a default instance of queue.
     public init() {
         storage = []
-        notEmptyCondition = NSCondition()
+        notEmptyCondition = Condition()
     }
 
     /// Safely enqueue an element to end of the queue and signals a thread blocked on dequeue.

Sources/Basic/Thread.swift

@@ -20,15 +20,15 @@ final public class Thread {
     private var thread: ThreadImpl!
 
     /// Condition variable to support blocking other threads using join when this thread has not finished executing.
-    private var finishedCondition: NSCondition
+    private var finishedCondition: Condition
 
     /// A boolean variable to track if this thread has finished executing its task.
     private var finished: Bool
 
     /// Creates an instance of thread class with closure to be executed when start() is called.
     public init(task: @escaping () -> Void) {
         finished = false
-        finishedCondition = NSCondition()
+        finishedCondition = Condition()
 
         // Wrap the task with condition notifying any other threads blocked due to this thread.
         // Capture self weakly to avoid reference cycle. In case Thread is deinited before the task