Merge branch 'main' into remove-scripts

.github/workflows/pull_request.yml

@@ -0,0 +1,79 @@
+name: Pull request
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+
+jobs:
+  tests:
+    name: Test
+    uses: swiftlang/github-workflows/.github/workflows/swift_package_test.yml@main
+    with:
+      linux_exclude_swift_versions: '[{"swift_version": "5.9"}, {"swift_version": "5.10"}]'
+      enable_windows_checks: false
+      enable_macos_checks: false
+  soundness:
+    name: Soundness
+    uses: swiftlang/github-workflows/.github/workflows/soundness.yml@main
+    with:
+      license_header_check_project_name: "Swift.org"
+      unacceptable_language_check_enabled: false
+      format_check_enabled: false
+  bench:
+    name: Benchmark
+    runs-on: ubuntu-latest
+    env:
+      BUILD_CMD: swift build -c release
+      BENCH_CMD: .build/release/RegexBenchmark
+      BASELINE_FILE: benchmark-baseline
+      COMPARE_FILE: benchmark-pr
+      COMPARE_OUT_FILE: benchmark-results.txt
+    steps:
+      - name: Check out baseline branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+          fetch-depth: 0
+      - name: Build baseline branch
+        working-directory: base
+        run: |
+          set -euo pipefail
+          eval "$BUILD_CMD"
+      - name: Run baseline benchmark
+        working-directory: base
+        run: |
+          set -euo pipefail
+          eval "$BENCH_CMD --save $RUNNER_TEMP/$BASELINE_FILE"
+          test -s "$RUNNER_TEMP/$BASELINE_FILE" || { echo "Baseline not created at $BASELINE_FILE"; exit 1; }
+      - name: Check out PR branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          path: pr
+          fetch-depth: 0
+      - name: Build PR branch
+        working-directory: pr
+        run: |
+          set -euo pipefail
+          eval "$BUILD_CMD"
+      - name: Run PR benchmark
+        working-directory: pr
+        run: |
+          set -euo pipefail
+          eval "$BENCH_CMD --save $RUNNER_TEMP/$COMPARE_FILE"
+          test -s "$RUNNER_TEMP/$COMPARE_FILE" || { echo "Comparison not created at $COMPARE_FILE"; exit 1; }
+          eval "$BENCH_CMD --compare $RUNNER_TEMP/$BASELINE_FILE" | tee "$RUNNER_TEMP/$COMPARE_OUT_FILE"
+      - name: 📊 Compare benchmarks
+        working-directory: pr
+        run: |
+          set -euo pipefail
+          eval "$BENCH_CMD --load $RUNNER_TEMP/$COMPARE_FILE --compare $RUNNER_TEMP/$BASELINE_FILE --compare-compile-time $RUNNER_TEMP/$BASELINE_FILE" | tee "$RUNNER_TEMP/$COMPARE_OUT_FILE"
+      - name: Upload benchmark artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: benchmark-results
+          path: |
+            ${{ runner.temp }}/${{ env.BASELINE_FILE }}
+            ${{ runner.temp }}/${{ env.COMPARE_FILE }}
+            ${{ runner.temp }}/${{ env.COMPARE_OUT_FILE }}

.gitignore

@@ -93,3 +93,6 @@ fastlane/test_output
 # https://github.com/johnno1962/injectionforxcode
 
 iOSInjectionProject/
+
+# DocC build folder
+*.docc-build

.license_header_template

@@ -0,0 +1,10 @@
+@@===----------------------------------------------------------------------===@@
+@@
+@@ This source file is part of the Swift.org open source project
+@@
+@@ Copyright (c) YEARS Apple Inc. and the Swift project authors
+@@ Licensed under Apache License v2.0 with Runtime Library Exception
+@@
+@@ See https://swift.org/LICENSE.txt for license information
+@@
+@@===----------------------------------------------------------------------===@@

.licenseignore

@@ -0,0 +1,25 @@
+.gitignore
+**/.gitignore
+.licenseignore
+.gitattributes
+.git-blame-ignore-revs
+.mailfilter
+.mailmap
+.spi.yml
+.swift-format
+.editorconfig
+.github/*
+.build
+*.py
+*.yml
+*.yaml
+*.cmake
+*.cmake.in
+Package.swift
+**/Package.swift
+Package@*.swift
+**/Package@*.swift
+Package.resolved
+**/Package.resolved
+.unacceptablelanguageignore
+ -a*/Snapshots/*

Documentation/ProgrammersManual.md

@@ -0,0 +1,30 @@
+# Programmer's Manual
+
+## Programming patterns
+
+### Engine quick checks and fast paths
+
+In the engine nomenclature, a quick-check results in a yes/no/maybe while a thorough check always results in a definite answer.
+
+The nature of quick checks and fast paths is that they bifurcate testing coverage. One easy way to prevent this in simple cases is to assert that a definite quick result matches the thorough result.
+
+One example of this pattern is matching against a builtin character class. The engine has a `_matchBuiltinCC`
+
+```swift
+  func _matchBuiltinCC(...) -> Input.Index? {
+    // Calls _quickMatchBuiltinCC, if that gives a definite result
+    // asserts that it is the same as the result of
+    // _thoroughMatchBuiltinCC and returns it. Otherwise returns the
+    // result of _thoroughMatchBuiltinCC
+  }
+
+  @inline(__always)
+  func _quickMatchBuiltinCC(...) -> QuickResult<Input.Index?>
+
+  @inline(never)
+  func _thoroughMatchBuiltinCC(...) -> Input.Index?
+```
+
+The thorough check is never inlined, as it is a lot of cold code. Note that quick and thorough functions should be pure, that is they shouldn't update processor state.
+
+

Package.swift

@@ -7,7 +7,23 @@ let availabilityDefinition = PackageDescription.SwiftSetting.unsafeFlags([
     "-Xfrontend",
     "-define-availability",
     "-Xfrontend",
-    "SwiftStdlib 5.7:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999",
+    "SwiftStdlib 5.7:macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 5.8:macOS 13.3, iOS 16.4, watchOS 9.4, tvOS 16.4",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 5.9:macOS 14.0, iOS 17.0, watchOS 10.0, tvOS 17.0",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 5.10:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999",
+    "-Xfrontend",
+    "-define-availability",
+    "-Xfrontend",
+    "SwiftStdlib 6.0:macOS 9999, iOS 9999, watchOS 9999, tvOS 9999",
 ])
 
 /// Swift settings for building a private stdlib-like module that is to be used
@@ -32,15 +48,20 @@ let package = Package(
         .library(
             name: "_StringProcessing",
             targets: ["_StringProcessing"]),
-        .library(
-            name: "Prototypes",
-            targets: ["Prototypes"]),
+        // FIXME: Disabled due to rdar://94763190.
+        // .library(
+        //     name: "Prototypes",
+        //     targets: ["Prototypes"]),
         .library(
             name: "_RegexParser",
             targets: ["_RegexParser"]),
         .executable(
             name: "VariadicsGenerator",
-            targets: ["VariadicsGenerator"])
+            targets: ["VariadicsGenerator"]),
+// Disable to work around rdar://126877024
+        .executable(
+          name: "RegexBenchmark",
+          targets: ["RegexBenchmark"])
     ],
     dependencies: [
         .package(url: "https://github.com/apple/swift-argument-parser", from: "1.0.0"),
@@ -67,24 +88,35 @@ let package = Package(
             name: "RegexBuilder",
             dependencies: ["_StringProcessing", "_RegexParser"],
             swiftSettings: publicStdlibSettings),
+        .target(name: "TestSupport",
+                swiftSettings: [availabilityDefinition]),
         .testTarget(
             name: "RegexTests",
-            dependencies: ["_StringProcessing"],
+            dependencies: ["_StringProcessing", "RegexBuilder", "TestSupport"],
             swiftSettings: [
-                .unsafeFlags(["-Xfrontend", "-disable-availability-checking"]),
+                availabilityDefinition
             ]),
         .testTarget(
             name: "RegexBuilderTests",
-            dependencies: ["_StringProcessing", "RegexBuilder"],
+            dependencies: ["_StringProcessing", "RegexBuilder", "TestSupport"],
             swiftSettings: [
-                .unsafeFlags(["-Xfrontend", "-disable-availability-checking"])
+                availabilityDefinition
             ]),
         .testTarget(
-            name: "Prototypes",
-            dependencies: ["_RegexParser", "_StringProcessing"],
+            name: "DocumentationTests",
+            dependencies: ["_StringProcessing", "RegexBuilder"],
             swiftSettings: [
-                .unsafeFlags(["-Xfrontend", "-disable-availability-checking"])
+                availabilityDefinition,
+                .unsafeFlags(["-enable-bare-slash-regex"]),
             ]),
+
+        // FIXME: Disabled due to rdar://94763190.
+        // .testTarget(
+        //     name: "Prototypes",
+        //     dependencies: ["_RegexParser", "_StringProcessing"],
+        //     swiftSettings: [
+        //         .unsafeFlags(["-Xfrontend", "-disable-availability-checking"])
+        //     ]),
 
         // MARK: Scripts
         .executableTarget(
@@ -105,6 +137,18 @@ let package = Package(
                 .product(name: "ArgumentParser", package: "swift-argument-parser"),
                 "_RegexParser",
                 "_StringProcessing"
+            ],
+            swiftSettings: [availabilityDefinition]),
+        .executableTarget(
+            name: "RegexBenchmark",
+            dependencies: [
+                .product(name: "ArgumentParser", package: "swift-argument-parser"),
+                "_RegexParser",
+                "_StringProcessing",
+                "RegexBuilder"
+            ],
+            swiftSettings: [
+                .unsafeFlags(["-Xfrontend", "-disable-availability-checking"]),
             ]),
 
         // MARK: Exercises