Merge branch 'SE-0135' of https://github.com/ddunbar/swift-package-manager

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.

Sources/Get/RawClone.swift

@@ -32,6 +32,9 @@ class RawClone: Fetchable {
         if branch.hasPrefix("v") {
             branch = String(branch.characters.dropFirst())
         }
+        if branch.contains("@") {
+            branch = branch.components(separatedBy: "@").first!
+        }
         return Version(branch)
     }
 

Sources/PackageLoading/ManifestLoader.swift

@@ -58,6 +58,14 @@ public final class ManifestLoader {
     ///   - version: The version the manifest is from, if known.
     ///   - fileSystem: If given, the file system to load from (otherwise load from the local file system).
     public func load(packagePath: AbsolutePath, baseURL: String, version: Version?, fileSystem: FileSystem? = nil) throws -> Manifest {
+        // As per our versioning support, determine the appropriate manifest version to load.
+        for versionSpecificKey in Versioning.currentVersionSpecificKeys { 
+            let versionSpecificPath = packagePath.appending(component: Manifest.basename + versionSpecificKey + ".swift")
+            if (fileSystem ?? localFileSystem).exists(versionSpecificPath) {
+                return try loadFile(path: versionSpecificPath, baseURL: baseURL, version: version, fileSystem: fileSystem)
+            }
+        }
+        
         return try loadFile(path: packagePath.appending(component: Manifest.filename), baseURL: baseURL, version: version, fileSystem: fileSystem)
     }
 

Sources/PackageLoading/PackageBuilder.swift

@@ -222,16 +222,33 @@ public struct PackageBuilder {
     // MARK: Utility Predicates
 
     private func isValidSource(_ path: AbsolutePath) -> Bool {
-        return isValidSource(path, validExtensions: SupportedLanguageExtension.validExtensions)
-    }
-    
-    private func isValidSource(_ path: AbsolutePath, validExtensions: Set<String>) -> Bool {
-        if path.basename.hasPrefix(".") { return false }
-        if path == manifest.path { return false }
-        if excludedPaths.contains(path) { return false }
+        // Ignore files which don't match the expected extensions.
+        guard let ext = path.extension, SupportedLanguageExtension.validExtensions.contains(ext) else {
+            return false
+        }
+        
+        // Ignore dotfiles.
+        let basename = path.basename
+        if basename.hasPrefix(".") { return false }
+        
+        // Ignore symlinks to non-files.
         if !fileSystem.isFile(path) { return false }
-        guard let ext = path.extension else { return false }
-        return validExtensions.contains(ext)
+        
+        // Ignore excluded files.
+        if excludedPaths.contains(path) { return false }
+
+        // Ignore manifest files.
+        if path.parentDirectory == packagePath {
+            if basename == Manifest.filename { return false }
+
+            // Ignore version-specific manifest files.
+            if basename.hasPrefix(Manifest.basename + "@") && basename.hasSuffix(".swift") {
+                return false
+            }
+        }
+
+        // Otherwise, we have a valid source file.
+        return true
     }
 
     private func shouldConsiderDirectory(_ path: AbsolutePath) -> Bool {
@@ -414,7 +431,7 @@ public struct PackageBuilder {
         }
     }
 
-    /// Private function that constructs a single Module object for the moduel at `path`, having the name `name`.  If `isTest` is true, the module is constructed as a test module; if false, it is a regular module.
+    /// Private function that constructs a single Module object for the module at `path`, having the name `name`.  If `isTest` is true, the module is constructed as a test module; if false, it is a regular module.
     private func createModule(_ path: AbsolutePath, name: String, isTest: Bool) throws -> Module {
 
         // Validate the module name.  This function will throw an error if it detects a problem.
@@ -424,9 +441,11 @@ public struct PackageBuilder {
         let walked = try walk(path, fileSystem: fileSystem, recursing: shouldConsiderDirectory).map{ $0 }
 
         // Select any source files for the C-based languages and for Swift.
-        let cSources = walked.filter{ isValidSource($0, validExtensions: SupportedLanguageExtension.cFamilyExtensions) }
-        let swiftSources = walked.filter{ isValidSource($0, validExtensions: SupportedLanguageExtension.swiftExtensions) }
-        
+        let sources = walked.filter(isValidSource)
+        let cSources = sources.filter{ SupportedLanguageExtension.cFamilyExtensions.contains($0.extension!) }
+        let swiftSources = sources.filter{ SupportedLanguageExtension.swiftExtensions.contains($0.extension!) }
+        assert(sources.count == cSources.count + swiftSources.count)
+
         // Create and return the right kind of module depending on what kind of sources we found.
         if cSources.isEmpty {
             // No C sources, so we expect to have Swift sources, and we create a Swift module.

Sources/PackageModel/Manifest.swift

@@ -20,7 +20,10 @@ import PackageDescription
 */
 public struct Manifest {
     /// The standard filename for the manifest.
-    public static var filename = "Package.swift"
+    public static var filename = basename + ".swift"
+
+    /// The standard basename for the manifest.
+    public static var basename = "Package"
 
     /// The path of the manifest file.
     //

Sources/TestSupport/misc.swift

@@ -84,6 +84,10 @@ public func fixture(name: String, tags: [String] = [], file: StaticString = #fil
 
 /// Test-helper function that creates a new Git repository in a directory.  The new repository will contain exactly one empty file, and if a tag name is provided, a tag with that name will be created.
 public func initGitRepo(_ dir: AbsolutePath, tag: String? = nil, file: StaticString = #file, line: UInt = #line) {
+    initGitRepo(dir, tags: tag.flatMap{ [$0] } ?? [], file: file, line: line)
+}
+
+public func initGitRepo(_ dir: AbsolutePath, tags: [String], file: StaticString = #file, line: UInt = #line) {
     do {
         let file = dir.appending(component: "file.swift")
         try systemQuietly(["touch", file.asString])
@@ -92,7 +96,7 @@ public func initGitRepo(_ dir: AbsolutePath, tag: String? = nil, file: StaticStr
         try systemQuietly([Git.tool, "-C", dir.asString, "config", "user.name", "Example Example"])
         try systemQuietly([Git.tool, "-C", dir.asString, "add", "."])
         try systemQuietly([Git.tool, "-C", dir.asString, "commit", "-m", "msg"])
-        if let tag = tag {
+        for tag in tags {
             try tagGitRepo(dir, tag: tag)
         }
     }
@@ -105,6 +109,18 @@ public func tagGitRepo(_ dir: AbsolutePath, tag: String) throws {
     try systemQuietly([Git.tool, "-C", dir.asString, "tag", tag])
 }
 
+public func removeTagGitRepo(_ dir: AbsolutePath, tag: String) throws {
+    try systemQuietly([Git.tool, "-C", dir.asString, "tag", "-d", tag])
+}
+
+public func addGitRepo(_ dir: AbsolutePath, file path: RelativePath) throws {
+    try systemQuietly([Git.tool, "-C", dir.asString, "add", path.asString])
+}
+
+public func commitGitRepo(_ dir: AbsolutePath, message: String = "Test commit") throws {
+    try systemQuietly([Git.tool, "-C", dir.asString, "commit", "-m", message])
+}
+
 public enum Configuration {
     case Debug
     case Release
@@ -154,3 +170,16 @@ public func systemQuietly(_ args: [String]) throws {
 public func systemQuietly(_ args: String...) throws {
     try systemQuietly(args)
 }
+
+public extension FileSystem {
+    /// Write to a file from a stream producer.
+    //
+    // FIXME: This is copy-paste from Commands/init.swift, maybe it is reasonable to lift it to Basic?
+    mutating func writeFileContents(_ path: AbsolutePath, body: (OutputByteStream) -> ()) throws {
+        let contents = BufferedOutputByteStream()
+        body(contents)
+        try createDirectory(path.parentDirectory, recursive: true)
+        try writeFileContents(path, bytes: contents.bytes)
+    }
+}
+

Sources/Utility/Git.swift

@@ -59,14 +59,32 @@ public class Git {
             let out = (try? Git.runPopen([Git.tool, "-C", repo.path.asString, "tag", "-l"])) ?? ""
             let tags = out.characters.split(separator: "\n").map{ String($0) }
 
-            // First try the plain init.
+            // First, check if we need to restrict the tag set to version-specific tags.
             var knownVersions: [Version: String] = [:]
+            for versionSpecificKey in Versioning.currentVersionSpecificKeys {
+                for tag in tags where tag.hasSuffix(versionSpecificKey) {
+                    let specifier = String(tag.characters.dropLast(versionSpecificKey.characters.count))
+                    if let version = Version(specifier) ?? Version.vprefix(specifier) {
+                        knownVersions[version] = tag
+                    }
+                }
+
+                // If we found tags at this version-specific key, we are done.
+                if !knownVersions.isEmpty {
+                    return knownVersions
+                }
+            }
+            
+            // Otherwise, look for normal tags.
             for tag in tags {
                 if let version = Version(tag) {
                     knownVersions[version] = tag
                 }
             }
+
             // If we didn't find any versions, look for 'v'-prefixed ones.
+            //
+            // FIXME: We should match both styles simultaneously.
             if knownVersions.isEmpty {
                 for tag in tags {
                     if let version = Version.vprefix(tag) {

Sources/Utility/Versioning.swift

@@ -27,9 +27,16 @@ public struct SwiftVersion {
     /// Build information, as an unstructured string.
     public var buildIdentifier: String?
 
+    /// The major component of the version number.
+    public var major: Int { return version.major }
+    /// The minor component of the version number.
+    public var minor: Int { return version.minor }
+    /// The patch component of the version number.
+    public var patch: Int { return version.patch }
+    
     /// The version as a readable string.
     public var displayString: String {
-        var result = "\(version.major).\(version.minor).\(version.patch)"
+        var result = "\(major).\(minor).\(patch)"
         if isDevelopment {
             result += "-dev"
         }
@@ -47,6 +54,18 @@ public struct SwiftVersion {
 #endif
         return vendorPrefix + "Swift Package Manager - Swift " + displayString
     }
+
+    /// The list of version specific identifiers to search when attempting to
+    /// load version specific package or version information, in order of
+    /// preference.
+    public var versionSpecificKeys: [String] {
+        return [
+            "@swift-\(major).\(minor).\(patch)",
+            "@swift-\(major).\(minor)",
+            "@swift-\(major)"
+        ]
+    }
+
 }
 
 private func getBuildIdentifier() -> String? {
@@ -64,4 +83,8 @@ public struct Versioning {
         version: (3, 0, 0),
         isDevelopment: true,
         buildIdentifier: getBuildIdentifier())
+
+    /// The list of version specific "keys" to search when attempting to load
+    /// version specific package or version information, in order of preference.
+    public static let currentVersionSpecificKeys = currentVersion.versionSpecificKeys
 }

Tests/FunctionalTests/DependencyResolutionTests.swift

@@ -9,11 +9,14 @@
 */
 
 import XCTest
-import TestSupport
+
 import Basic
+
 import func POSIX.popen
 
-class DependencyResolutionTestCase: XCTestCase {
+import TestSupport
+
+class DependencyResolutionTests: XCTestCase {
     func testInternalSimple() {
         fixture(name: "DependencyResolution/Internal/Simple") { prefix in
             XCTAssertBuilds(prefix)

Tests/FunctionalTests/ValidLayoutTests.swift

@@ -17,7 +17,7 @@ import Utility
 import func POSIX.rename
 import func POSIX.popen
 
-class ValidLayoutsTestCase: XCTestCase {
+class ValidLayoutsTests: XCTestCase {
 
     func testSingleModuleLibrary() {
         runLayoutFixture(name: "SingleModule/Library") { prefix in
@@ -113,7 +113,7 @@ class ValidLayoutsTestCase: XCTestCase {
 
 // MARK: Utility
 
-extension ValidLayoutsTestCase {
+extension ValidLayoutsTests {
     func runLayoutFixture(name: String, line: UInt = #line, body: (AbsolutePath) throws -> Void) {
         let name = "ValidLayouts/\(name)"