deprecate name attribute on package dependencies (#3641)

motivation: follow-on work to the change in 5.5 that _allows_ users to not specify a name on the dependency, this soft-deprecates the ability to do so

changes:
* emit a deprecation warning when using the name attribute on a dependency (in the manifest)
* refactor the dependency::name attribute to "deprecatedName" to reflect the fact it was deprecated and prevent too much downstream logic
* cleanup the internal API
* cleanup and add tests
* cleanup havePD4Runtime

Author: tomerd

Diff for: Package.swift

@@ -15,7 +15,7 @@ import class Foundation.ProcessInfo
 
 
 /** SwiftPMDataModel is the subset of SwiftPM product that includes just its data model.
-This allowis some clients (such as IDEs) that use SwiftPM's data model but not its build system
+This allows some clients (such as IDEs) that use SwiftPM's data model but not its build system
 to not have to depend on SwiftDriver, SwiftLLBuild, etc. We should probably have better names here,
 though that could break some clients.
 */
@@ -33,7 +33,7 @@ let swiftPMDataModelProduct = (
     ]
 )
 
-/** The `libSwiftPM` set of interfaces to programatically work with Swift
+/** The `libSwiftPM` set of interfaces to programmatically work with Swift
  packages.  `libSwiftPM` includes all of the SwiftPM code except the
  command line tools, while `libSwiftPMDataModel` includes only the data model.
 

Diff for: Sources/Commands/Describe.swift

@@ -6,7 +6,7 @@
 
  See http://swift.org/LICENSE.txt for license information
  See http://swift.org/CONTRIBUTORS.txt for Swift project authors
-*/
+ */
 
 import TSCBasic
 import PackageModel
@@ -58,7 +58,7 @@ fileprivate struct DescribedPackage: Encodable {
         self.name = package.manifestName // TODO: rename property to manifestName?
         self.path = package.path.pathString
         self.toolsVersion = "\(package.manifest.toolsVersion.major).\(package.manifest.toolsVersion.minor)"
-            + (package.manifest.toolsVersion.patch == 0 ? "" : ".\(package.manifest.toolsVersion.patch)")
+        + (package.manifest.toolsVersion.patch == 0 ? "" : ".\(package.manifest.toolsVersion.patch)")
         self.dependencies = package.manifest.dependencies.map { DescribedPackageDependency(from: $0) }
         self.defaultLocalization = package.manifest.defaultLocalization
         self.platforms = package.manifest.platforms.map { DescribedPlatformRestriction(from: $0) }
@@ -100,24 +100,23 @@ fileprivate struct DescribedPackage: Encodable {
 
     /// Represents a package dependency for the sole purpose of generating a description.
     enum DescribedPackageDependency: Encodable {
-        case fileSystem(name: String?, path: AbsolutePath)
-        case sourceControl(name: String?, location: String, requirement: PackageDependency.SourceControl.Requirement)
+        case fileSystem(path: AbsolutePath)
+        case sourceControl(location: String, requirement: PackageDependency.SourceControl.Requirement)
         case registry(identity: PackageIdentity, requirement: PackageDependency.Registry.Requirement)
 
         init(from dependency: PackageDependency) {
             switch dependency {
             case .fileSystem(let settings):
-                self = .fileSystem(name: dependency.explicitNameForTargetDependencyResolutionOnly, path: settings.path)
+                self = .fileSystem(path: settings.path)
             case .sourceControl(let settings):
-                self = .sourceControl(name: dependency.explicitNameForTargetDependencyResolutionOnly, location: settings.location, requirement: settings.requirement)
+                self = .sourceControl(location: settings.location, requirement: settings.requirement)
             case .registry(let settings):
                 self = .registry(identity: settings.identity, requirement: settings.requirement)
             }
         }
 
         private enum CodingKeys: CodingKey {
             case type
-            case name
             case path
             case url
             case requirement
@@ -133,20 +132,17 @@ fileprivate struct DescribedPackage: Encodable {
         public func encode(to encoder: Encoder) throws {
             var container = encoder.container(keyedBy: CodingKeys.self)
             switch self {
-            case .fileSystem(let name, let path):
+            case .fileSystem(let path):
                 try container.encode(Kind.fileSystem, forKey: .type)
-                try container.encode(name, forKey: .name)
                 try container.encode(path, forKey: .path)
-            case .sourceControl(let name, let location, let requirement):
+            case .sourceControl(let location, let requirement):
                 try container.encode(Kind.sourceControl, forKey: .type)
-                try container.encode(name, forKey: .name)
                 try container.encode(location, forKey: .url)
                 try container.encode(requirement, forKey: .requirement)
             case .registry(let identity, let requirement):
                 try container.encode(Kind.registry, forKey: .type)
                 try container.encode(identity, forKey: .identity)
                 try container.encode(requirement, forKey: .requirement)
-
             }
         }
     }
@@ -287,7 +283,7 @@ public struct PlainTextEncoder {
 
         func unkeyedContainer() -> UnkeyedEncodingContainer {
             return PlainTextUnkeyedEncodingContainer(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath)
-       }
+        }
 
         func singleValueContainer() -> SingleValueEncodingContainer {
             return TextSingleValueEncodingContainer(outputStream: outputStream, formattingOptions: formattingOptions, userInfo: userInfo, codingPath: codingPath)

Diff for: Sources/PackageDescription/PackageDependency.swift

@@ -127,6 +127,8 @@ extension Package {
     }
 }
 
+// MARK: - file system
+
 extension Package.Dependency {
     /// Adds a package dependency to a local package on the filesystem.
     ///
@@ -136,11 +138,10 @@ extension Package.Dependency {
     /// on multiple tightly coupled packages.
     ///
     /// - Parameter path: The path of the package.
-    @available(_PackageDescription, obsoleted: 5.2)
     public static func package(
         path: String
     ) -> Package.Dependency {
-        return .package(name: nil, path: path)
+        return .init(name: nil, path: path)
     }
 
     /// Adds a package dependency to a local package on the filesystem.
@@ -153,9 +154,9 @@ extension Package.Dependency {
     /// - Parameters
     ///   - name: The name of the Swift package or `nil` to deduce the name from path.
     ///   - path: The local path to the package.
-    @available(_PackageDescription, introduced: 5.2)
+    @available(_PackageDescription, introduced: 5.2, deprecated: 5.6, message: "use package(path:) instead")
     public static func package(
-        name: String? = nil,
+        name: String,
         path: String
     ) -> Package.Dependency {
         return .init(name: name, path: path)
@@ -184,12 +185,11 @@ extension Package.Dependency {
     ///     - name: The name of the package, or nil to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - version: The minimum version requirement.
-    @available(_PackageDescription, obsoleted: 5.2)
     public static func package(
         url: String,
         from version: Version
     ) -> Package.Dependency {
-        return .package(name: nil, url: url, from: version)
+        return .package(url: url, .upToNextMajor(from: version))
     }
 
     /// Adds a package dependency that uses the version requirement, starting with the given minimum version,
@@ -211,26 +211,41 @@ extension Package.Dependency {
     ///     - name: The name of the package, or nil to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - version: The minimum version requirement.
-    @available(_PackageDescription, introduced: 5.2)
+    @available(_PackageDescription, introduced: 5.2, deprecated: 5.6, message: "use package(url:from:) instead")
     public static func package(
-        name: String? = nil,
+        name: String,
         url: String,
         from version: Version
     ) -> Package.Dependency {
         return .package(name: name, url: url, .upToNextMajor(from: version))
     }
-    
+
     /// Adds a remote package dependency given a branch requirement.
     ///
     ///    .package(url: "https://example.com/example-package.git", branch: "main"),
     ///
     /// - Parameters:
-    ///     - name: The name of the package, or nil to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - branch: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
     @available(_PackageDescription, introduced: 5.5)
     public static func package(
-        name: String? = nil,
+        url: String,
+        branch: String
+    ) -> Package.Dependency {
+        return .package(url: url, requirement: .branch(branch))
+    }
+
+    /// Adds a remote package dependency given a branch requirement.
+    ///
+    ///    .package(url: "https://example.com/example-package.git", branch: "main"),
+    ///
+    /// - Parameters:
+    ///     - name: The name of the package, or nil to deduce it from the URL.
+    ///     - url: The valid Git URL of the package.
+    ///     - branch: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
+    @available(_PackageDescription, introduced: 5.5, deprecated: 5.6, message: "use package(url:branch:) instead")
+    public static func package(
+        name: String,
         url: String,
         branch: String
     ) -> Package.Dependency {
@@ -242,12 +257,27 @@ extension Package.Dependency {
     ///    .package(url: "https://example.com/example-package.git", revision: "aa681bd6c61e22df0fd808044a886fc4a7ed3a65"),
     ///
     /// - Parameters:
-    ///     - name: The name of the package, or nil to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - revision: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
     @available(_PackageDescription, introduced: 5.5)
     public static func package(
-        name: String? = nil,
+        url: String,
+        revision: String
+    ) -> Package.Dependency {
+        return .package(url: url, requirement: .revision(revision))
+    }
+
+    /// Adds a remote package dependency given a revision requirement.
+    ///
+    ///    .package(url: "https://example.com/example-package.git", revision: "aa681bd6c61e22df0fd808044a886fc4a7ed3a65"),
+    ///
+    /// - Parameters:
+    ///     - name: The name of the package, or nil to deduce it from the URL.
+    ///     - url: The valid Git URL of the package.
+    ///     - revision: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
+    @available(_PackageDescription, introduced: 5.5, deprecated: 5.6, message: "use package(url:revision:) instead")
+    public static func package(
+        name: String,
         url: String,
         revision: String
     ) -> Package.Dependency {
@@ -266,12 +296,11 @@ extension Package.Dependency {
     ///     - name: The name of the package, or nil to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - range: The custom version range requirement.
-    @available(_PackageDescription, obsoleted: 5.2)
     public static func package(
         url: String,
         _ range: Range<Version>
     ) -> Package.Dependency {
-        return .package(name: nil, url: url, range)
+        return .package(name: nil, url: url, requirement: .range(range))
     }
 
     /// Adds a package dependency starting with a specific minimum version, up to
@@ -286,9 +315,9 @@ extension Package.Dependency {
     ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - range: The custom version range requirement.
-    @available(_PackageDescription, introduced: 5.2)
+    @available(_PackageDescription, introduced: 5.2, deprecated: 5.6, message: "use package(url:_:) instead")
     public static func package(
-        name: String? = nil,
+        name: String,
         url: String,
         _ range: Range<Version>
     ) -> Package.Dependency {
@@ -307,12 +336,11 @@ extension Package.Dependency {
     ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - range: The closed version range requirement.
-    @available(_PackageDescription, obsoleted: 5.2)
     public static func package(
         url: String,
         _ range: ClosedRange<Version>
     ) -> Package.Dependency {
-        return .package(name: nil, url: url, range)
+        return .package(name: nil, url: url, closedRange: range)
     }
 
     /// Adds a package dependency starting with a specific minimum version, going
@@ -327,19 +355,27 @@ extension Package.Dependency {
     ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - range: The closed version range requirement.
-    @available(_PackageDescription, introduced: 5.2)
+    @available(_PackageDescription, introduced: 5.2, deprecated: 5.6, message: "use package(url:_:) instead")
     public static func package(
-        name: String? = nil,
+        name: String,
         url: String,
         _ range: ClosedRange<Version>
+    ) -> Package.Dependency {
+        return .package(name: name, url: url, closedRange: range)
+    }
+
+    private static func package(
+        name: String?,
+        url: String,
+        closedRange: ClosedRange<Version>
     ) -> Package.Dependency {
         // Increase upperbound's patch version by one.
-        let upper = range.upperBound
+        let upper = closedRange.upperBound
         let upperBound = Version(
             upper.major, upper.minor, upper.patch + 1,
             prereleaseIdentifiers: upper.prereleaseIdentifiers,
             buildMetadataIdentifiers: upper.buildMetadataIdentifiers)
-        return .package(name: name, url: url, range.lowerBound ..< upperBound)
+        return .package(name: name, url: url, requirement: .range(closedRange.lowerBound ..< upperBound))
     }
 
     /// Adds a package dependency that uses the exact version requirement.
@@ -363,33 +399,7 @@ extension Package.Dependency {
         url: String,
         exact version: Version
     ) -> Package.Dependency {
-        return .package(name: nil, url: url, exact: version)
-    }
-
-    /// Adds a package dependency that uses the exact version requirement.
-    ///
-    /// This is the recommended way to specify a remote package dependency.
-    /// It allows you to specify the minimum version you require, allows updates that include bug fixes
-    /// and backward-compatible feature updates, but requires you to explicitly update to a new major version of the dependency.
-    /// This approach provides the maximum flexibility on which version to use,
-    /// while making sure you don't update to a version with breaking changes,
-    /// and helps to prevent conflicts in your dependency graph.
-    ///
-    /// The following example instruct the Swift Package Manager to use version `1.2.3`.
-    ///
-    ///    .package(url: "https://example.com/example-package.git", exact: "1.2.3"),
-    ///
-    /// - Parameters:
-    ///     - name: The name of the package, or `nil` to deduce it from the URL.
-    ///     - url: The valid Git URL of the package.
-    ///     - version: The minimum version requirement.
-    @available(_PackageDescription, introduced: 5.6)
-    public static func package(
-        name: String? = nil,
-        url: String,
-        exact version: Version
-    ) -> Package.Dependency {
-        return .init(name: name, location: url, requirement: .exact(version))
+        return .package(url: url, requirement: .exact(version))
     }
 
     /// Adds a remote package dependency given a version requirement.
@@ -398,13 +408,12 @@ extension Package.Dependency {
     ///     - name: The name of the package, or nil to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - requirement: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
-    @available(_PackageDescription, obsoleted: 5.2, deprecated: 5.6)
+    @available(_PackageDescription, deprecated: 5.6, message: "use specific requirement APIs instead")
     public static func package(
         url: String,
         _ requirement: Package.Dependency.Requirement
     ) -> Package.Dependency {
-        precondition(!requirement.isLocalPackage, "Use `.package(path:)` API to declare a local package dependency")
-        return .init(name: nil, url: url, requirement: requirement)
+        return .package(name: nil, url: url, requirement)
     }
 
     /// Adds a remote package dependency with a given version requirement.
@@ -413,9 +422,9 @@ extension Package.Dependency {
     ///     - name: The name of the package, or `nil` to deduce it from the URL.
     ///     - url: The valid Git URL of the package.
     ///     - requirement: A dependency requirement. See static methods on `Package.Dependency.Requirement` for available options.
-    @available(_PackageDescription, introduced: 5.2, deprecated: 5.6)
+    @available(_PackageDescription, introduced: 5.2, deprecated: 5.6, message: "use specific requirement APIs instead")
     public static func package(
-        name: String? = nil,
+        name: String?,
         url: String,
         _ requirement: Package.Dependency.Requirement
     ) -> Package.Dependency {
@@ -424,7 +433,6 @@ extension Package.Dependency {
     }
 
     // intentionally private to hide enum detail
-    @available(_PackageDescription, introduced: 5.6)
     private static func package(
         name: String? = nil,
         url: String,
@@ -541,16 +549,15 @@ extension Package.Dependency {
     }
 }
 
-
 // MARK: - common APIs used by mistake as unavailable to provide better error messages.
 
 extension Package.Dependency {
-    @available(*, unavailable, message: "use package(url:_:) with the .exact(Version) initializer instead")
+    @available(*, unavailable, message: "use package(url:exact:) instead")
     public static func package(url: String, version: Version) -> Package.Dependency {
         fatalError()
     }
 
-    @available(*, unavailable, message: "use package(url:_:) without the range label instead")
+    @available(*, unavailable, message: "use package(url:_:) instead")
     public static func package(url: String, range: Range<Version>) -> Package.Dependency {
         fatalError()
     }