Allow unit tests to import and link any main modules of executables that are implemented in Swift. This uses a new Swift compiler flag to set the name of the entry point when emitting object code, and then uses linker flags to rename the main executable module's entry point back to _main again when actually linking the executable.

abertelrud · abertelrud · commit 05babe90c801 · 2021-03-06T09:43:03.000-08:00
This is guarded by a tools version check, since packages written this way won't be testable on older toolchains.

Also, this is currently only done on Darwin and Linux.  A supplemental PR will generate a small stub containing code that implements `main` to call the per-module `&lt;module&gt;_main` function, which will be linked into the executable.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,8 @@ Swift v.Next
    * Improvements
    
    Adding a dependency requirement can now be done with the convenience initializer `.package(url: String, branch: String)`.
+   
+   Test targets can now link against executable targets as if they were libraries, so that they can test any data strutures or algorithms in them.  All the code in the executable except for the main entry point itself is available to the unit test.  Separate executables are still linked, and can be tested as a subprocess in the same way as before.  This feature is available to tests defined in packages that have a tools version of `vNext` or newer. 
 
 
 
diff --git a/Fixtures/Miscellaneous/ExeTest/Package.swift b/Fixtures/Miscellaneous/ExeTest/Package.swift
@@ -1,10 +1,10 @@
-// swift-tools-version:5.3
+// swift-tools-version: 999.0
 import PackageDescription
 
 let package = Package(
     name: "ExeTest",
     targets: [
-        .target(
+        .executableTarget(
             name: "Exe",
             dependencies: []
         ),
diff --git a/Fixtures/Miscellaneous/TestableExe/Package.swift b/Fixtures/Miscellaneous/TestableExe/Package.swift
@@ -0,0 +1,25 @@
+// swift-tools-version: 999.0
+import PackageDescription
+
+let package = Package(
+    name: "TestableExe",
+    targets: [
+        .target(
+            name: "TestableExe1"
+        ),
+        .target(
+            name: "TestableExe2"
+        ),
+        .target(
+            name: "TestableExe3"
+        ),
+        .testTarget(
+            name: "TestableExeTests",
+            dependencies: [
+                "TestableExe1",
+                "TestableExe2",
+                "TestableExe3",
+            ]
+        ),
+    ]
+)
diff --git a/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe1/main.swift b/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe1/main.swift
@@ -0,0 +1,5 @@
+public func GetGreeting1() -> String {
+    return "Hello, world"
+}
+
+print("\(GetGreeting1())!")
diff --git a/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe2/main.swift b/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe2/main.swift
@@ -0,0 +1,5 @@
+public func GetGreeting2() -> String {
+    return "Hello, planet"
+}
+
+print("\(GetGreeting2())!")
diff --git a/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe3/include/TestableExe3.h b/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe3/include/TestableExe3.h
@@ -0,0 +1 @@
+const char * GetGreeting3();
diff --git a/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe3/main.c b/Fixtures/Miscellaneous/TestableExe/Sources/TestableExe3/main.c
@@ -0,0 +1,10 @@
+#include <stdio.h>
+#include "include/TestableExe3.h"
+
+const char * GetGreeting3() {
+    return "Hello, universe";
+}
+
+int main() {
+    printf("%s!\n", GetGreeting3());
+}
diff --git a/Fixtures/Miscellaneous/TestableExe/Tests/TestableExeTests/TestableExeTests.swift b/Fixtures/Miscellaneous/TestableExe/Tests/TestableExeTests/TestableExeTests.swift
@@ -0,0 +1,73 @@
+import XCTest
+import TestableExe1
+import TestableExe2
+// import TestableExe3
+import class Foundation.Bundle
+
+final class TestableExeTests: XCTestCase {
+    func testExample() throws {
+        // This is an example of a functional test case.
+        // Use XCTAssert and related functions to verify your tests produce the correct
+        // results.
+        
+        print(GetGreeting1())
+        XCTAssertEqual(GetGreeting1(), "Hello, world")
+        print(GetGreeting2())
+        XCTAssertEqual(GetGreeting2(), "Hello, planet")
+        // XCTAssertEqual(String(cString: GetGreeting3()), "Hello, universe")
+
+        // Some of the APIs that we use below are available in macOS 10.13 and above.
+        guard #available(macOS 10.13, *) else {
+            return
+        }
+
+        var execPath = productsDirectory.appendingPathComponent("TestableExe1")
+        var process = Process()
+        process.executableURL = execPath
+        var pipe = Pipe()
+        process.standardOutput = pipe
+        try process.run()
+        process.waitUntilExit()
+        var data = pipe.fileHandleForReading.readDataToEndOfFile()
+        var output = String(data: data, encoding: .utf8)
+        XCTAssertEqual(output, "Hello, world!\n")
+
+        execPath = productsDirectory.appendingPathComponent("TestableExe2")
+        process = Process()
+        process.executableURL = execPath
+        pipe = Pipe()
+        process.standardOutput = pipe
+        try process.run()
+        process.waitUntilExit()
+        data = pipe.fileHandleForReading.readDataToEndOfFile()
+        output = String(data: data, encoding: .utf8)
+        XCTAssertEqual(output, "Hello, planet!\n")
+
+        execPath = productsDirectory.appendingPathComponent("TestableExe3")
+        process = Process()
+        process.executableURL = execPath
+        pipe = Pipe()
+        process.standardOutput = pipe
+        try process.run()
+        process.waitUntilExit()
+        data = pipe.fileHandleForReading.readDataToEndOfFile()
+        output = String(data: data, encoding: .utf8)
+        XCTAssertEqual(output, "Hello, universe!\n")
+    }
+
+    /// Returns path to the built products directory.
+    var productsDirectory: URL {
+      #if os(macOS)
+        for bundle in Bundle.allBundles where bundle.bundlePath.hasSuffix(".xctest") {
+            return bundle.bundleURL.deletingLastPathComponent()
+        }
+        fatalError("couldn't find the products directory")
+      #else
+        return Bundle.main.bundleURL
+      #endif
+    }
+
+    static var allTests = [
+        ("testExample", testExample),
+    ]
+}
diff --git a/Sources/Build/BuildPlan.swift b/Sources/Build/BuildPlan.swift
@@ -121,6 +121,18 @@ extension BuildParameters {
         return args
     }
 
+    /// Computes the linker flags to use in order to rename a module-named main function to 'main' for the target platform, or nil if the linker doesn't support it for the platform.
+    fileprivate func linkerFlagsForRenamingMainFunction(of target: ResolvedTarget) -> [String]? {
+        var args: [String] = []
+        if self.triple.isDarwin() {
+            args = ["-alias", "_\(target.c99name)_main", "_main"]
+        }
+        else if self.triple.isLinux() {
+            args = ["--defsym", "main=\(target.c99name)_main"]
+        }
+        return args.flatMap { ["-Xlinker", $0] }
+    }
+
     /// Returns the scoped view of build settings for a given target.
     fileprivate func createScope(for target: ResolvedTarget) -> BuildSettings.Scope {
         return BuildSettings.Scope(target.underlyingTarget.buildSettings, environment: buildEnvironment)
@@ -515,7 +527,9 @@ public final class SwiftTargetBuildDescription {
 
     /// The path to the swiftmodule file after compilation.
     var moduleOutputPath: AbsolutePath {
-        let dirPath = (target.type == .executable) ? tempsPath : buildParameters.buildPath
+        // If we're an executable and we're not allowing test targets to link against us, we hide the module.
+        let allowLinkingAgainstExecutables = (buildParameters.triple.isDarwin() || buildParameters.triple.isLinux()) && toolsVersion >= .vNext
+        let dirPath = (target.type == .executable && !allowLinkingAgainstExecutables) ? tempsPath : buildParameters.buildPath
         return dirPath.appending(component: target.c99name + ".swiftmodule")
     }
 
@@ -690,6 +704,24 @@ public final class SwiftTargetBuildDescription {
         args += buildParameters.sanitizers.compileSwiftFlags()
         args += ["-parseable-output"]
 
+        // If we're compiling the main module of an executable other than the one that
+        // implements a test suite, and if the package tools version indicates that we
+        // should, we rename the `_main` entry point to `_<modulename>_main`.
+        //
+        // This will allow tests to link against the module without any conflicts. And
+        // when we link the executable, we will ask the linker to rename the entry point
+        // symbol to just `_main` again (or if the linker doesn't support it, we'll
+        // generate a source containing a redirect).
+        if target.type == .executable && !isTestTarget && toolsVersion >= .vNext {
+            // We only do this if the linker supports it, as indicated by whether we
+            // can construct the linker flags. In the future we will use a generated
+            // code stub for the cases in which the linker doesn't support it, so that
+            // we can rename the symbol unconditionally.
+            if buildParameters.linkerFlagsForRenamingMainFunction(of: target) != nil {
+                args += ["-Xfrontend", "-entry-point-function-name", "-Xfrontend", "\(target.c99name)_main"]
+            }
+        }
+
         // Only add the build path to the framework search path if there are binary frameworks to link against.
         if !libraryBinaryPaths.isEmpty {
             args += ["-F", buildParameters.buildPath.pathString]
@@ -1047,7 +1079,7 @@ public final class ProductBuildDescription {
         return buildParameters.binaryPath(for: product)
     }
 
-    /// The objects in this product.
+    /// All object files to link into this product.
     ///
     // Computed during build planning.
     public fileprivate(set) var objects = SortedArray<AbsolutePath>()
@@ -1167,6 +1199,20 @@ public final class ProductBuildDescription {
                 }
             }
             args += ["-emit-executable"]
+            
+            // If we're linking an executable whose main module is implemented in Swift,
+            // we rename the `_<modulename>_main` entry point symbol to `_main` again.
+            // This is because executable modules implemented in Swift are compiled with
+            // a main symbol named that way to allow tests to link against it without
+            // conflicts. If we're using a linker that doesn't support symbol renaming,
+            // we will instead have generated a source file containing the redirect.
+            // Support for linking tests againsts executables is conditional on the tools
+            // version of the package that defines the executable product.
+            if product.executableModule.underlyingTarget is SwiftTarget, toolsVersion >= .vNext {
+                if let flags = buildParameters.linkerFlagsForRenamingMainFunction(of: product.executableModule) {
+                    args += flags
+                }
+            }
         case .plugin:
             throw InternalError("unexpectedly asked to generate linker arguments for a plugin product")
         }
@@ -1669,9 +1715,21 @@ public class BuildPlan {
             switch dependency {
             case .target(let target, _):
                 switch target.type {
-                // Include executable and tests only if they're top level contents
-                // of the product. Otherwise they are just build time dependency.
-                case .executable, .test:
+                // Executable target have historically only been included if they are directly in the product's
+                // target list.  Otherwise they have always been just build-time dependencies.
+                // In tool version .vNext or greater, we also include executable modules implemented in Swift in
+                // any test products... this is to allow testing of executables.  Note that they are also still
+                // built as separate products that the test can invoke as subprocesses.
+                case .executable:
+                    if product.targets.contains(target) {
+                        staticTargets.append(target)
+                    } else if product.type == .test && target.underlyingTarget is SwiftTarget {
+                        if let toolsVersion = graph.package(for: product)?.manifest.toolsVersion, toolsVersion >= .vNext {
+                            staticTargets.append(target)
+                        }
+                    }
+                // Test targets should be included only if they are directly in the product's target list.
+                case .test:
                     if product.targets.contains(target) {
                         staticTargets.append(target)
                     }
diff --git a/Tests/FunctionalTests/MiscellaneousTests.swift b/Tests/FunctionalTests/MiscellaneousTests.swift
@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2014 - 2017 Apple Inc. and the Swift project authors
+ Copyright (c) 2014 - 2021 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
@@ -578,25 +578,20 @@ class MiscellaneousTestCase: XCTestCase {
         #endif
     }
     
-    func testErrorMessageWhenTestLinksExecutable() {
-        fixture(name: "Miscellaneous/ExeTest") { prefix in
+    func testTestsCanLinkAgainstExecutable() throws {
+        // Check if the host compiler supports the '-entry-point-function-name' flag.
+        try XCTSkipUnless(doesHostSwiftCompilerSupportRenamingMainSymbol(), "skipping because host compiler doesn't support '-entry-point-function-name'")
+        
+        fixture(name: "Miscellaneous/TestableExe") { prefix in
             do {
-                try executeSwiftTest(prefix)
-                XCTFail()
-            } catch SwiftPMProductError.executionFailure(let error, let output, let stderr) {
-                XCTAssertMatch(stderr + output, .contains("Compiling Exe main.swift"))
-                XCTAssertMatch(stderr + output, .contains("Compiling ExeTests ExeTests.swift"))
-                XCTAssertMatch(stderr + output, .regex("error: no such module 'Exe'"))
-                XCTAssertMatch(stderr + output, .regex("note: module 'Exe' is the main module of an executable, and cannot be imported by tests and other targets"))
-
-                if case ProcessResult.Error.nonZeroExit(let result) = error {
-                    // if our code crashes we'll get an exit code of 256
-                    XCTAssertEqual(result.exitStatus, .terminated(code: 1))
-                } else {
-                    XCTFail("\(stderr + output)")
-                }
+                let (stdout, _) = try executeSwiftTest(prefix)
+                XCTAssertMatch(stdout, .contains("Linking TestableExe1"))
+                XCTAssertMatch(stdout, .contains("Linking TestableExe2"))
+                XCTAssertMatch(stdout, .contains("Linking TestableExePackageTests"))
+                XCTAssertMatch(stdout, .contains("Hello, world"))
+                XCTAssertMatch(stdout, .contains("Hello, planet"))
             } catch {
-                XCTFail()
+                XCTFail("\(error)")
             }
         }
     }
@@ -613,3 +608,12 @@ class MiscellaneousTestCase: XCTestCase {
         }
     }
 }
+
+func doesHostSwiftCompilerSupportRenamingMainSymbol() throws -> Bool {
+    try withTemporaryDirectory { tmpDir in
+        let hostToolchain = try UserToolchain(destination: .hostDestination())
+        FileManager.default.createFile(atPath: "\(tmpDir)/foo.swift", contents: Data())
+        let result = try Process.popen(args: hostToolchain.swiftCompiler.pathString, "-c", "-Xfrontend", "-entry-point-function-name", "-Xfrontend", "foo", "\(tmpDir)/foo.swift", "-o", "\(tmpDir)/foo.o")
+        return try !result.utf8stderrOutput().contains("unknown argument: '-entry-point-function-name'")
+    }
+}
diff --git a/Tests/FunctionalTests/PluginTests.swift b/Tests/FunctionalTests/PluginTests.swift
@@ -14,7 +14,9 @@ import TSCBasic
 
 class PluginTests: XCTestCase {
     
-    func testUseOfBuildToolPluginTargetByExecutableInSamePackage() {
+    func testUseOfBuildToolPluginTargetByExecutableInSamePackage() throws {
+        // Check if the host compiler supports the '-entry-point-function-name' flag.  It's not needed for this test but is needed to build any executable from a package that uses tools version 999.0.
+        try XCTSkipUnless(doesHostSwiftCompilerSupportRenamingMainSymbol(), "skipping because host compiler doesn't support '-entry-point-function-name'")
         
         fixture(name: "Miscellaneous/Plugins") { path in
             do {
@@ -31,7 +33,10 @@ class PluginTests: XCTestCase {
         }
     }
 
-    func testUseOfBuildToolPluginProductByExecutableAcrossPackages() {
+    func testUseOfBuildToolPluginProductByExecutableAcrossPackages() throws {
+        // Check if the host compiler supports the '-entry-point-function-name' flag.  It's not needed for this test but is needed to build any executable from a package that uses tools version 999.0.
+        try XCTSkipUnless(doesHostSwiftCompilerSupportRenamingMainSymbol(), "skipping because host compiler doesn't support '-entry-point-function-name'")
+
         fixture(name: "Miscellaneous/Plugins") { path in
             do {
                 let (stdout, _) = try executeSwiftBuild(path.appending(component: "MySourceGenClient"), configuration: .Debug, extraArgs: ["--product", "MyTool"], env: ["SWIFTPM_ENABLE_PLUGINS": "1"])
@@ -47,7 +52,10 @@ class PluginTests: XCTestCase {
         }
     }
 
-    func testUseOfPrebuildPluginTargetByExecutableAcrossPackages() {
+    func testUseOfPrebuildPluginTargetByExecutableAcrossPackages() throws {
+        // Check if the host compiler supports the '-entry-point-function-name' flag.  It's not needed for this test but is needed to build any executable from a package that uses tools version 999.0.
+        try XCTSkipUnless(doesHostSwiftCompilerSupportRenamingMainSymbol(), "skipping because host compiler doesn't support '-entry-point-function-name'")
+
         fixture(name: "Miscellaneous/Plugins") { path in
             do {
                 let (stdout, _) = try executeSwiftBuild(path.appending(component: "MySourceGenPlugin"), configuration: .Debug, extraArgs: ["--product", "MyOtherLocalTool"], env: ["SWIFTPM_ENABLE_PLUGINS": "1"])
