Extend @available to support PackageDescription

<rdar://problem/46548531> Extend @available to support PackageDescription

This introduces a new private availability kind "_PackageDescription" to
allow availability testing by an arbitary version that can be passed
using a new command-line flag "-swiftpm-manifest-version". The semantics
are exactly same as Swift version specific availability. In longer term,
it maybe possible to remove this enhancement once there is
a language-level availability support for 3rd party libraries.

Motivation:

Swift packages are configured using a Package.swift manifest file. The
manifest file uses a library called PackageDescription, which contains
various settings that can be configured for a package. The new additions
in the PackageDescription APIs are gated behind a "tools version" that
every manifest must declare. This means, packages don't automatically
get access to the new APIs. They need to update their declared tools
version in order to use the new API. This is basically similar to the
minimum deployment target version we have for our OSes.

This gating is important for allowing packages to maintain backwards
compatibility. SwiftPM currently checks for API usages at runtime in
order to implement this gating. This works reasonably well but can lead
to a poor experience with features like code-completion and module
interface generation in IDEs and editors (that use sourcekit-lsp) as
SwiftPM has no control over these features.

Author: aciidgh

include/swift/AST/Attr.h

@@ -616,6 +616,10 @@ enum class PlatformAgnosticAvailabilityKind {
   /// The declaration is available in some but not all versions
   /// of Swift, as specified by the VersionTuple members.
   SwiftVersionSpecific,
+  /// The declaration is available in some but not all versions
+  /// of SwiftPM's PackageDescription library, as specified by
+  /// the VersionTuple members.
+  PackageDescriptionVersionSpecific,
   /// The declaration is unavailable for other reasons.
   Unavailable,
 };
@@ -686,6 +690,9 @@ class AvailableAttr : public DeclAttribute {
   /// Whether this is a language-version-specific entity.
   bool isLanguageVersionSpecific() const;
 
+  /// Whether this is a PackageDescription version specific entity.
+  bool isPackageDescriptionVersionSpecific() const;
+
   /// Whether this is an unconditionally unavailable entity.
   bool isUnconditionallyUnavailable() const;
 
@@ -722,6 +729,12 @@ class AvailableAttr : public DeclAttribute {
   /// Returns true if this attribute is active given the current platform.
   bool isActivePlatform(const ASTContext &ctx) const;
 
+  /// Returns the active version from the AST context corresponding to
+  /// the available kind. For example, this will return the effective language
+  /// version for swift version-specific availability kind, PackageDescription
+  /// version for PackageDescription version-specific availability.
+  llvm::VersionTuple getActiveVersion(const ASTContext &ctx) const;
+
   /// Compare this attribute's version information against the platform or
   /// language version (assuming the this attribute pertains to the active
   /// platform).

include/swift/AST/AvailabilitySpec.h

@@ -37,6 +37,9 @@ enum class AvailabilitySpecKind {
 
     /// A language-version constraint of the form "swift X.Y.Z"
     LanguageVersionConstraint,
+
+    /// A PackageDescription version constraint of the form "_PackageDescription X.Y.Z"
+    PackageDescriptionVersionConstraint,
 };
 
 /// The root class for specifications of API availability in availability
@@ -101,38 +104,48 @@ class PlatformVersionConstraintAvailabilitySpec : public AvailabilitySpec {
 };
 
 /// An availability specification that guards execution based on the
-/// compile-time language version, e.g., swift >= 3.0.1.
-class LanguageVersionConstraintAvailabilitySpec : public AvailabilitySpec {
-  SourceLoc SwiftLoc;
+/// compile-time platform agnostic version, e.g., swift >= 3.0.1,
+/// package-description >= 4.0.
+class PlatformAgnosticVersionConstraintAvailabilitySpec : public AvailabilitySpec {
+  SourceLoc PlatformAgnosticNameLoc;
 
   llvm::VersionTuple Version;
   SourceRange VersionSrcRange;
 
 public:
-  LanguageVersionConstraintAvailabilitySpec(SourceLoc SwiftLoc,
-                                            llvm::VersionTuple Version,
-                                            SourceRange VersionSrcRange)
-    : AvailabilitySpec(AvailabilitySpecKind::LanguageVersionConstraint),
-      SwiftLoc(SwiftLoc), Version(Version),
-      VersionSrcRange(VersionSrcRange) {}
+  PlatformAgnosticVersionConstraintAvailabilitySpec(
+      AvailabilitySpecKind AvailabilitySpecKind,
+      SourceLoc PlatformAgnosticNameLoc, llvm::VersionTuple Version,
+      SourceRange VersionSrcRange)
+      : AvailabilitySpec(AvailabilitySpecKind),
+        PlatformAgnosticNameLoc(PlatformAgnosticNameLoc), Version(Version),
+        VersionSrcRange(VersionSrcRange) {
+    assert(AvailabilitySpecKind == AvailabilitySpecKind::LanguageVersionConstraint ||
+           AvailabilitySpecKind == AvailabilitySpecKind::PackageDescriptionVersionConstraint);
+  }
 
-  SourceLoc getSwiftLoc() const { return SwiftLoc; }
+  SourceLoc getPlatformAgnosticNameLoc() const { return PlatformAgnosticNameLoc; }
 
   // The platform version to compare against.
   llvm::VersionTuple getVersion() const { return Version; }
   SourceRange getVersionSrcRange() const { return VersionSrcRange; }
 
   SourceRange getSourceRange() const;
 
+  bool isLanguageVersionSpecific() const {
+      return getKind() == AvailabilitySpecKind::LanguageVersionConstraint;
+  }
+
   void print(raw_ostream &OS, unsigned Indent) const;
 
   static bool classof(const AvailabilitySpec *Spec) {
-    return Spec->getKind() == AvailabilitySpecKind::LanguageVersionConstraint;
+    return Spec->getKind() == AvailabilitySpecKind::LanguageVersionConstraint ||
+      Spec->getKind() == AvailabilitySpecKind::PackageDescriptionVersionConstraint;
   }
 
   void *
   operator new(size_t Bytes, ASTContext &C,
-               unsigned Alignment = alignof(LanguageVersionConstraintAvailabilitySpec)){
+               unsigned Alignment = alignof(PlatformAgnosticVersionConstraintAvailabilitySpec)){
     return AvailabilitySpec::operator new(Bytes, C, Alignment);
   }
 };

include/swift/AST/DiagnosticsParse.def

@@ -1367,15 +1367,15 @@ ERROR(attr_availability_expected_equal,none,
 ERROR(attr_availability_expected_version,none,
       "expected version number in '%0' attribute", (StringRef))
 
-WARNING(attr_availability_swift_expected_option,none,
+WARNING(attr_availability_platform_agnostic_expected_option,none,
       "expected 'introduced', 'deprecated', or 'obsoleted' in '%0' attribute "
-      "for platform 'swift'", (StringRef))
-WARNING(attr_availability_swift_expected_deprecated_version,none,
+      "for platform '%1'", (StringRef, StringRef))
+WARNING(attr_availability_platform_agnostic_expected_deprecated_version,none,
       "expected version number with 'deprecated' in '%0' attribute for "
-      "platform 'swift'", (StringRef))
-WARNING(attr_availability_swift_infeasible_option,none,
-      "'%0' cannot be used in '%1' attribute for platform 'swift'",
-      (StringRef, StringRef))
+      "platform '%1'", (StringRef, StringRef))
+WARNING(attr_availability_platform_agnostic_infeasible_option,none,
+      "'%0' cannot be used in '%1' attribute for platform '%2'",
+      (StringRef, StringRef, StringRef))
 
 WARNING(attr_availability_nonspecific_platform_unexpected_version,none,
       "unexpected version number in '%0' attribute for non-specific platform "
@@ -1610,12 +1610,15 @@ ERROR(avail_query_version_comparison_not_needed,
 ERROR(availability_query_wildcard_required, none,
       "must handle potential future platforms with '*'", ())
 
-ERROR(availability_swift_must_occur_alone, none,
-      "'swift' version-availability must be specified alone", ())
+ERROR(availability_must_occur_alone, none,
+      "'%0' version-availability must be specified alone", (StringRef))
 
 ERROR(pound_available_swift_not_allowed, none,
       "Swift language version checks not allowed in #available(...)", ())
 
+ERROR(pound_available_package_description_not_allowed, none,
+      "PackageDescription version checks not allowed in #available(...)", ())
+
 ERROR(availability_query_repeated_platform, none,
       "version for '%0' already specified", (StringRef))
 

include/swift/AST/DiagnosticsSema.def

@@ -3981,9 +3981,9 @@ NOTE(availability_marked_unavailable, none,
      "%select{getter for |setter for |}0%1 has been explicitly marked "
      "unavailable here", (unsigned, DeclName))
 
-NOTE(availability_introduced_in_swift, none,
-     "%select{getter for |setter for |}0%1 was introduced in Swift %2",
-     (unsigned, DeclName, llvm::VersionTuple))
+NOTE(availability_introduced_in_version, none,
+     "%select{getter for |setter for |}0%1 was introduced in %2 %3",
+     (unsigned, DeclName, StringRef, llvm::VersionTuple))
 
 NOTE(availability_obsoleted, none,
      "%select{getter for |setter for |}0%1 was obsoleted in %2 %3",

include/swift/Basic/LangOptions.h

@@ -82,6 +82,9 @@ namespace swift {
     /// User-overridable language version to compile for.
     version::Version EffectiveLanguageVersion = version::Version::getCurrentLanguageVersion();
 
+    /// PackageDescription version to compile for.
+    version::Version PackageDescriptionVersion;
+
     /// Disable API availability checking.
     bool DisableAvailabilityChecking = false;
 

include/swift/Option/Options.td

@@ -172,6 +172,11 @@ def swift_version : Separate<["-"], "swift-version">, Flags<[FrontendOption, Par
   HelpText<"Interpret input according to a specific Swift language version number">,
   MetaVarName<"<vers>">;
 
+def package_description_version: Separate<["-"], "package-description-version">,
+  Flags<[FrontendOption, HelpHidden, ParseableInterfaceOption]>,
+  HelpText<"The version number to be applied on the input for the PackageDescription availability kind">,
+  MetaVarName<"<vers>">;
+
 def tools_directory : Separate<["-"], "tools-directory">,
   Flags<[FrontendOption, NoInteractiveOption, DoesNotAffectIncrementalBuild,
          ArgumentIsPath]>,

include/swift/Parse/Parser.h

@@ -1414,8 +1414,8 @@ class Parser {
   ParserResult<AvailabilitySpec> parseAvailabilitySpec();
   ParserResult<PlatformVersionConstraintAvailabilitySpec>
   parsePlatformVersionConstraintSpec();
-  ParserResult<LanguageVersionConstraintAvailabilitySpec>
-  parseLanguageVersionConstraintSpec();
+  ParserResult<PlatformAgnosticVersionConstraintAvailabilitySpec>
+  parsePlatformAgnosticVersionConstraintSpec();
 
   bool canDelayMemberDeclParsing();
 };

include/swift/Serialization/ModuleFormat.h

@@ -52,7 +52,7 @@ const uint16_t SWIFTMODULE_VERSION_MAJOR = 0;
 /// describe what change you made. The content of this comment isn't important;
 /// it just ensures a conflict if two people change the module format.
 /// Don't worry about adhering to the 80-column limit for this line.
-const uint16_t SWIFTMODULE_VERSION_MINOR = 470; // Last change: Remove @trivial
+const uint16_t SWIFTMODULE_VERSION_MINOR = 471; // Last change: Add @available(_PackageDescription..)
 
 using DeclIDField = BCFixed<31>;
 
@@ -1547,6 +1547,7 @@ namespace decls_block {
     BCFixed<1>, // implicit flag
     BCFixed<1>, // is unconditionally unavailable?
     BCFixed<1>, // is unconditionally deprecated?
+    BCFixed<1>, // is this PackageDescription version-specific kind?
     BC_AVAIL_TUPLE, // Introduced
     BC_AVAIL_TUPLE, // Deprecated
     BC_AVAIL_TUPLE, // Obsoleted

lib/AST/ASTDumper.cpp

@@ -1437,7 +1437,8 @@ class PrintStmt : public StmtVisitor<PrintStmt> {
           cast<PlatformVersionConstraintAvailabilitySpec>(Query)->print(OS, Indent + 2);
           break;
         case AvailabilitySpecKind::LanguageVersionConstraint:
-          cast<LanguageVersionConstraintAvailabilitySpec>(Query)->print(OS, Indent + 2);
+        case AvailabilitySpecKind::PackageDescriptionVersionConstraint:
+          cast<PlatformVersionConstraintAvailabilitySpec>(Query)->print(OS, Indent + 2);
           break;
         case AvailabilitySpecKind::OtherPlatform:
           cast<OtherPlatformAvailabilitySpec>(Query)->print(OS, Indent + 2);

lib/AST/Attr.cpp

@@ -142,7 +142,8 @@ const AvailableAttr *DeclAttributes::getUnavailable(
 
       // If this attribute doesn't apply to the active platform, we're done.
       if (!AvAttr->isActivePlatform(ctx) &&
-          !AvAttr->isLanguageVersionSpecific())
+          !AvAttr->isLanguageVersionSpecific() &&
+          !AvAttr->isPackageDescriptionVersionSpecific())
         continue;
 
       // Unconditional unavailable.
@@ -172,7 +173,8 @@ DeclAttributes::getDeprecated(const ASTContext &ctx) const {
         continue;
 
       if (!AvAttr->isActivePlatform(ctx) &&
-          !AvAttr->isLanguageVersionSpecific())
+          !AvAttr->isLanguageVersionSpecific() &&
+          !AvAttr->isPackageDescriptionVersionSpecific())
         continue;
 
       // Unconditional deprecated.
@@ -183,10 +185,7 @@ DeclAttributes::getDeprecated(const ASTContext &ctx) const {
       if (!DeprecatedVersion.hasValue())
         continue;
 
-      llvm::VersionTuple MinVersion =
-        AvAttr->isLanguageVersionSpecific() ?
-        ctx.LangOpts.EffectiveLanguageVersion :
-        ctx.LangOpts.getMinPlatformVersion();
+      llvm::VersionTuple MinVersion = AvAttr->getActiveVersion(ctx);
 
       // We treat the declaration as deprecated if it is deprecated on
       // all deployment targets.
@@ -240,6 +239,7 @@ static bool isShortAvailable(const DeclAttribute *DA) {
     return false;
   case PlatformAgnosticAvailabilityKind::None:
   case PlatformAgnosticAvailabilityKind::SwiftVersionSpecific:
+  case PlatformAgnosticAvailabilityKind::PackageDescriptionVersionSpecific:
     return true;
   }
 
@@ -261,10 +261,16 @@ static void printShortFormAvailable(ArrayRef<const DeclAttribute *> Attrs,
   Printer << "@available(";
   auto FirstAvail = cast<AvailableAttr>(Attrs.front());
   if (Attrs.size() == 1 &&
-      FirstAvail->isLanguageVersionSpecific()) {
+      FirstAvail->getPlatformAgnosticAvailability() !=
+      PlatformAgnosticAvailabilityKind::None) {
     assert(FirstAvail->Introduced.hasValue());
-    Printer << "swift "
-            << FirstAvail->Introduced.getValue().getAsString()
+    if (FirstAvail->isLanguageVersionSpecific()) {
+      Printer << "swift ";
+    } else {
+      assert(FirstAvail->isPackageDescriptionVersionSpecific());
+      Printer << "_PackageDescription ";
+    }
+    Printer << FirstAvail->Introduced.getValue().getAsString()
             << ")";
   } else {
     for (auto *DA : Attrs) {
@@ -290,6 +296,7 @@ void DeclAttributes::print(ASTPrinter &Printer, const PrintOptions &Options,
   // Process attributes in passes.
   AttributeVector shortAvailableAttributes;
   const DeclAttribute *swiftVersionAvailableAttribute = nullptr;
+  const DeclAttribute *packageDescriptionVersionAvailableAttribute = nullptr;
   AttributeVector longAttributes;
   AttributeVector attributes;
   AttributeVector modifiers;
@@ -311,6 +318,11 @@ void DeclAttributes::print(ASTPrinter &Printer, const PrintOptions &Options,
         swiftVersionAvailableAttribute = availableAttr;
         continue;
       }
+      if (availableAttr->isPackageDescriptionVersionSpecific() &&
+          isShortAvailable(availableAttr)) {
+        packageDescriptionVersionAvailableAttribute = availableAttr;
+        continue;
+      }
     }
 
     AttributeVector &which = DA->isDeclModifier() ? modifiers :
@@ -322,6 +334,8 @@ void DeclAttributes::print(ASTPrinter &Printer, const PrintOptions &Options,
 
   if (swiftVersionAvailableAttribute)
     printShortFormAvailable(swiftVersionAvailableAttribute, Printer, Options);
+  if (packageDescriptionVersionAvailableAttribute)
+    printShortFormAvailable(packageDescriptionVersionAvailableAttribute, Printer, Options);
   if (!shortAvailableAttributes.empty())
     printShortFormAvailable(shortAvailableAttributes, Printer, Options);
 
@@ -424,6 +438,8 @@ bool DeclAttribute::printImpl(ASTPrinter &Printer, const PrintOptions &Options,
     auto Attr = cast<AvailableAttr>(this);
     if (Attr->isLanguageVersionSpecific())
       Printer << "swift";
+    else if (Attr->isPackageDescriptionVersionSpecific())
+      Printer << "_PackageDescription";
     else
       Printer << Attr->platformString();
 
@@ -890,11 +906,25 @@ bool AvailableAttr::isLanguageVersionSpecific() const {
   return false;
 }
 
+bool AvailableAttr::isPackageDescriptionVersionSpecific() const {
+  if (PlatformAgnostic ==
+      PlatformAgnosticAvailabilityKind::PackageDescriptionVersionSpecific)
+    {
+      assert(Platform == PlatformKind::none &&
+             (Introduced.hasValue() ||
+              Deprecated.hasValue() ||
+              Obsoleted.hasValue()));
+      return true;
+    }
+  return false;
+}
+
 bool AvailableAttr::isUnconditionallyUnavailable() const {
   switch (PlatformAgnostic) {
   case PlatformAgnosticAvailabilityKind::None:
   case PlatformAgnosticAvailabilityKind::Deprecated:
   case PlatformAgnosticAvailabilityKind::SwiftVersionSpecific:
+  case PlatformAgnosticAvailabilityKind::PackageDescriptionVersionSpecific:
     return false;
 
   case PlatformAgnosticAvailabilityKind::Unavailable:
@@ -911,6 +941,7 @@ bool AvailableAttr::isUnconditionallyDeprecated() const {
   case PlatformAgnosticAvailabilityKind::Unavailable:
   case PlatformAgnosticAvailabilityKind::UnavailableInSwift:
   case PlatformAgnosticAvailabilityKind::SwiftVersionSpecific:
+  case PlatformAgnosticAvailabilityKind::PackageDescriptionVersionSpecific:
     return false;
 
   case PlatformAgnosticAvailabilityKind::Deprecated:
@@ -920,17 +951,24 @@ bool AvailableAttr::isUnconditionallyDeprecated() const {
   llvm_unreachable("Unhandled PlatformAgnosticAvailabilityKind in switch.");
 }
 
+llvm::VersionTuple AvailableAttr::getActiveVersion(const ASTContext &ctx) const {
+  if (isLanguageVersionSpecific()) {
+    return ctx.LangOpts.EffectiveLanguageVersion;
+  } else if (isPackageDescriptionVersionSpecific()) {
+    return ctx.LangOpts.PackageDescriptionVersion;
+  } else {
+    return ctx.LangOpts.getMinPlatformVersion();
+  }
+}
+
 AvailableVersionComparison AvailableAttr::getVersionAvailability(
   const ASTContext &ctx) const {
 
   // Unconditional unavailability.
   if (isUnconditionallyUnavailable())
     return AvailableVersionComparison::Unavailable;
 
-  llvm::VersionTuple queryVersion =
-    isLanguageVersionSpecific() ?
-    ctx.LangOpts.EffectiveLanguageVersion :
-    ctx.LangOpts.getMinPlatformVersion();
+  llvm::VersionTuple queryVersion = getActiveVersion(ctx);
 
   // If this entity was obsoleted before or at the query platform version,
   // consider it obsolete.
@@ -943,7 +981,7 @@ AvailableVersionComparison AvailableAttr::getVersionAvailability(
   // static requirement, so we treat "introduced later" as just plain
   // unavailable.
   if (Introduced && *Introduced > queryVersion) {
-    if (isLanguageVersionSpecific())
+    if (isLanguageVersionSpecific() || isPackageDescriptionVersionSpecific())
       return AvailableVersionComparison::Unavailable;
     else
       return AvailableVersionComparison::PotentiallyUnavailable;