Add --pkg-config-path to LocationOptions (#5949)

Resolves #5815.

Having a specific `--pkg-config-path` option for this means we have something that's less fragile and easier to report errors on than `PKG_CONFIG_PATH` environment variable.

Added `pkgConfigDirectory` to `LocationOptions`, which is propagated to `BuildPlan` as a function or initializer argument.

Author: MaxDesiatov

CHANGELOG.md

@@ -3,6 +3,13 @@ Note: This is in reverse chronological order, so newer entries are added to the
 Swift 5.8
 -----------
 
+* [#5949]
+  
+  New `--pkg-config-path` option on `build`, `test`, and `run` commands has been
+  introduced as an alternative to passing `PKG_CONFIG_PATH` environment variable.
+  It allows specifying alternative path to search for `.pc` files used by
+  `pkg-config`. Use the option multiple times to specify more than one path.
+
 * [#5874]
 
   In packages using tools version 5.8 or later, Foundation is no longer implicitly imported into package manifests. If Foundation APIs are used, the module needs to be imported explicitly.

Sources/Build/BuildOperation.swift

@@ -79,13 +79,13 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
     /// The output stream for the build delegate.
     private let outputStream: OutputByteStream
 
-    /// The verbosity level to print out at
+    /// The verbosity level to use for diagnostics.
     private let logLevel: Basics.Diagnostic.Severity
 
-    /// File system to operate on
+    /// File system to operate on.
     private let fileSystem: TSCBasic.FileSystem
 
-    /// ObservabilityScope with which to emit diagnostics
+    /// ObservabilityScope with which to emit diagnostics.
     private let observabilityScope: ObservabilityScope
 
     public var builtTestProducts: [BuiltTestProduct] {
@@ -95,6 +95,9 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
     /// File rules to determine resource handling behavior.
     private let additionalFileRules: [FileRuleDescription]
 
+    /// Alternative path to search for pkg-config `.pc` files.
+    private let pkgConfigDirectories: [AbsolutePath]
+
     public init(
         buildParameters: BuildParameters,
         cacheBuildManifest: Bool,
@@ -103,6 +106,7 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
         pluginScriptRunner: PluginScriptRunner,
         pluginWorkDirectory: AbsolutePath,
         disableSandboxForPluginCommands: Bool,
+        pkgConfigDirectories: [AbsolutePath],
         outputStream: OutputByteStream,
         logLevel: Basics.Diagnostic.Severity,
         fileSystem: TSCBasic.FileSystem,
@@ -118,6 +122,7 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
         self.additionalFileRules = additionalFileRules
         self.pluginScriptRunner = pluginScriptRunner
         self.pluginWorkDirectory = pluginWorkDirectory
+        self.pkgConfigDirectories = pkgConfigDirectories
         self.disableSandboxForPluginCommands = disableSandboxForPluginCommands
         self.outputStream = outputStream
         self.logLevel = logLevel
@@ -399,6 +404,7 @@ public final class BuildOperation: PackageStructureDelegate, SPMBuildCore.BuildS
             builtToolsDir: self.buildParameters.buildPath,
             buildEnvironment: self.buildParameters.buildEnvironment,
             toolSearchDirectories: [self.buildParameters.toolchain.swiftCompilerPath.parentDirectory],
+            pkgConfigDirectories: self.pkgConfigDirectories,
             pluginScriptRunner: self.pluginScriptRunner,
             observabilityScope: self.observabilityScope,
             fileSystem: self.fileSystem

Sources/Build/BuildPlan.swift

@@ -2416,7 +2416,12 @@ public class BuildPlan: SPMBuildCore.BuildPlan {
         else {
             pkgConfigCache[target] = ([], [])
         }
-        let results = try pkgConfigArgs(for: target, fileSystem: self.fileSystem, observabilityScope: self.observabilityScope)
+        let results = try pkgConfigArgs(
+            for: target,
+            pkgConfigDirectories: buildParameters.pkgConfigDirectories,
+            fileSystem: fileSystem,
+            observabilityScope: observabilityScope
+        )
         var ret: [(cFlags: [String], libs: [String])] = []
         for result in results {
             ret.append((result.cFlags, result.libs))

Sources/Commands/PackageTools/PluginCommand.swift

@@ -187,6 +187,7 @@ struct PluginCommand: SwiftCommand {
             accessibleTools: accessibleTools,
             writableDirectories: writableDirectories,
             readOnlyDirectories: readOnlyDirectories,
+            pkgConfigDirectories: swiftTool.options.locations.pkgConfigDirectories,
             fileSystem: swiftTool.fileSystem,
             observabilityScope: swiftTool.observabilityScope,
             callbackQueue: delegateQueue,

Sources/CoreCommands/BuildSystemSupport.swift

@@ -34,6 +34,7 @@ extension SwiftTool {
                         pluginScriptRunner: self.getPluginScriptRunner(),
                         pluginWorkDirectory: try self.getActiveWorkspace().location.pluginWorkingDirectory,
                         disableSandboxForPluginCommands: self.options.security.shouldDisableSandbox,
+                        pkgConfigDirectories: self.options.locations.pkgConfigDirectories,
                         outputStream: customOutputStream ?? self.outputStream,
                         logLevel: customLogLevel ?? self.logLevel,
                         fileSystem: self.fileSystem,

Sources/CoreCommands/Options.swift

@@ -86,6 +86,16 @@ public struct LocationOptions: ParsableArguments {
 
     @Option(name: .customLong("experimental-destinations-path"), help: .hidden, completion: .directory)
     public var crossCompilationDestinationsDirectory: AbsolutePath?
+
+    @Option(
+        name: .customLong("pkg-config-path"),
+        help:
+            """
+            Specify alternative path to search for pkg-config `.pc` files. Use the option multiple times to
+            specify more than one path.
+            """,
+        completion: .directory)
+    public var pkgConfigDirectories: [AbsolutePath] = []
 }
 
 public struct CachingOptions: ParsableArguments {

Sources/CoreCommands/SwiftTool.swift

@@ -297,11 +297,11 @@ public final class SwiftTool {
             (packageRoot ?? cwd).appending(component: ".build")
 
         // make sure common directories are created
-        self.sharedSecurityDirectory = try getSharedSecurityDirectory(options: self.options, fileSystem: fileSystem)
-        self.sharedConfigurationDirectory = try getSharedConfigurationDirectory(options: self.options, fileSystem: fileSystem)
-        self.sharedCacheDirectory = try getSharedCacheDirectory(options: self.options, fileSystem: fileSystem)
+        self.sharedSecurityDirectory = try getSharedSecurityDirectory(options: options, fileSystem: fileSystem)
+        self.sharedConfigurationDirectory = try getSharedConfigurationDirectory(options: options, fileSystem: fileSystem)
+        self.sharedCacheDirectory = try getSharedCacheDirectory(options: options, fileSystem: fileSystem)
         self.sharedCrossCompilationDestinationsDirectory = try fileSystem.getSharedCrossCompilationDestinationsDirectory(
-            explicitDirectory: self.options.locations.crossCompilationDestinationsDirectory
+            explicitDirectory: options.locations.crossCompilationDestinationsDirectory
         )
 
         // set global process logging handler
@@ -594,6 +594,7 @@ public final class SwiftTool {
                 archs: options.build.archs,
                 flags: options.build.buildFlags,
                 xcbuildFlags: options.build.xcbuildFlags,
+                pkgConfigDirectories: options.locations.pkgConfigDirectories,
                 jobs: options.build.jobs ?? UInt32(ProcessInfo.processInfo.activeProcessorCount),
                 shouldLinkStaticSwiftStdlib: options.linker.shouldLinkStaticSwiftStdlib,
                 canRenameEntrypointFunctionName: DriverSupport.checkSupportedFrontendFlags(

Sources/PackageLoading/Target+PkgConfig.swift

@@ -58,15 +58,28 @@ public struct PkgConfigResult {
 }
 
 /// Get pkgConfig result for a system library target.
-public func pkgConfigArgs(for target: SystemLibraryTarget, brewPrefix: AbsolutePath? = .none, fileSystem: FileSystem, observabilityScope: ObservabilityScope) throws -> [PkgConfigResult] {
+public func pkgConfigArgs(
+    for target: SystemLibraryTarget,
+    pkgConfigDirectories: [AbsolutePath],
+    brewPrefix: AbsolutePath? = .none,
+    fileSystem: FileSystem,
+    observabilityScope: ObservabilityScope
+) throws -> [PkgConfigResult] {
     // If there is no pkg config name defined, we're done.
     guard let pkgConfigNames = target.pkgConfig else { return [] }
 
     // Compute additional search paths for the provider, if any.
     let provider = target.providers?.first { $0.isAvailable }
-    let additionalSearchPaths = try provider?.pkgConfigSearchPath(brewPrefixOverride: brewPrefix) ?? []
 
-   var ret: [PkgConfigResult] = []
+    let additionalSearchPaths: [AbsolutePath]
+    // Give priority to `pkgConfigDirectories` passed as an argument to this function.
+    if let providerSearchPaths = try provider?.pkgConfigSearchPath(brewPrefixOverride: brewPrefix) {
+        additionalSearchPaths = pkgConfigDirectories + providerSearchPaths
+    } else {
+        additionalSearchPaths = pkgConfigDirectories
+    }
+
+    var ret: [PkgConfigResult] = []
     // Get the pkg config flags.
     for pkgConfigName in pkgConfigNames.components(separatedBy: " ") {
         let result: PkgConfigResult
@@ -92,19 +105,21 @@ public func pkgConfigArgs(for target: SystemLibraryTarget, brewPrefix: AbsoluteP
             }
 
             result = PkgConfigResult(
-                    pkgConfigName: pkgConfigName,
-                    cFlags: cFlags,
-                    libs: libs,
-                    error: error,
-                    provider: provider
+                pkgConfigName: pkgConfigName,
+                cFlags: cFlags,
+                libs: libs,
+                error: error,
+                provider: provider
             )
         } catch {
             result = PkgConfigResult(pkgConfigName: pkgConfigName, error: error, provider: provider)
         }
 
         // If there is no pc file on system and we have an available provider, emit a warning.
         if let provider = result.provider, result.couldNotFindConfigFile {
-            observabilityScope.emit(warning: "you may be able to install \(result.pkgConfigName) using your system-packager:\n\(provider.installText)")
+            observabilityScope.emit(
+                warning: "you may be able to install \(result.pkgConfigName) using your system-packager:\n\(provider.installText)"
+            )
         } else if let error = result.error {
             observabilityScope.emit(
                 warning: "\(error)",

Sources/PackageModel/BuildEnvironment.swift

@@ -10,7 +10,7 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A build environment with which to evaluation conditions.
+/// A build environment with which to evaluate conditions.
 public struct BuildEnvironment: Codable {
     public let platform: Platform
     public let configuration: BuildConfiguration?

Sources/SPMBuildCore/BuildParameters.swift

@@ -137,6 +137,9 @@ public struct BuildParameters: Encodable {
     /// Extra build flags.
     public var flags: BuildFlags
 
+    /// An array of paths to search for pkg-config `.pc` files.
+    public var pkgConfigDirectories: [AbsolutePath]
+
     /// How many jobs should llbuild and the Swift compiler spawn
     public var jobs: UInt32
 
@@ -155,7 +158,7 @@ public struct BuildParameters: Encodable {
     /// Whether to enable code coverage.
     public var enableCodeCoverage: Bool
 
-    /// Whether to enable generation of `.swiftinterface` files alongside
+    /// Whether to enable generation of `.swiftinterface` files alongside.
     /// `.swiftmodule`s.
     public var enableParseableModuleInterfaces: Bool
 
@@ -168,10 +171,10 @@ public struct BuildParameters: Encodable {
     /// to a separate process.
     public var useIntegratedSwiftDriver: Bool
 
-    /// Whether to use the explicit module build flow (with the integrated driver)
+    /// Whether to use the explicit module build flow (with the integrated driver).
     public var useExplicitModuleBuild: Bool
 
-    /// A flag that inidcates this build should check whether targets only import
+    /// A flag that inidcates this build should check whether targets only import.
     /// their explicitly-declared dependencies
     public var explicitTargetDependencyImportCheckingMode: TargetDependencyImportCheckingMode
 
@@ -231,6 +234,7 @@ public struct BuildParameters: Encodable {
         archs: [String] = [],
         flags: BuildFlags,
         xcbuildFlags: [String] = [],
+        pkgConfigDirectories: [AbsolutePath] = [],
         jobs: UInt32 = UInt32(ProcessInfo.processInfo.activeProcessorCount),
         shouldLinkStaticSwiftStdlib: Bool = false,
         shouldEnableManifestCaching: Bool = false,
@@ -261,6 +265,7 @@ public struct BuildParameters: Encodable {
         self.triple = triple
         self.archs = archs
         self.flags = flags
+        self.pkgConfigDirectories = pkgConfigDirectories
         self.xcbuildFlags = xcbuildFlags
         self.jobs = jobs
         self.shouldLinkStaticSwiftStdlib = shouldLinkStaticSwiftStdlib

Sources/SPMBuildCore/PluginContextSerializer.swift

@@ -24,6 +24,7 @@ typealias WireInput = HostToPluginMessage.InputContext
 internal struct PluginContextSerializer {
     let fileSystem: FileSystem
     let buildEnvironment: BuildEnvironment
+    let pkgConfigDirectories: [AbsolutePath]
     var paths: [WireInput.Path] = []
     var pathsToIds: [AbsolutePath: WireInput.Path.Id] = [:]
     var targets: [WireInput.Target] = []
@@ -105,7 +106,12 @@ internal struct PluginContextSerializer {
             var ldFlags: [String] = []
             // FIXME: What do we do with any diagnostics here?
             let observabilityScope = ObservabilitySystem({ _, _ in }).topScope
-            for result in try pkgConfigArgs(for: target, fileSystem: self.fileSystem, observabilityScope: observabilityScope) {
+            for result in try pkgConfigArgs(
+                for: target,
+                pkgConfigDirectories: pkgConfigDirectories,
+                fileSystem: fileSystem,
+                observabilityScope: observabilityScope
+            ) {
                 if let error = result.error {
                     observabilityScope.emit(
                         warning: "\(error)",

Sources/SPMBuildCore/PluginInvocation.swift

@@ -44,6 +44,7 @@ extension PluginTarget {
     ///   - workingDirectory: The initial working directory of the invoked plugin.
     ///   - outputDirectory: A directory under which the plugin can write anything it wants to.
     ///   - toolNamesToPaths: A mapping from name of tools available to the plugin to the corresponding absolute paths.
+    ///   - pkgConfigDirectory: A directory for searching `pkg-config` `.pc` files in it.
     ///   - fileSystem: The file system to which all of the paths refers.
     ///
     /// - Returns: A PluginInvocationResult that contains the results of invoking the plugin.
@@ -57,6 +58,7 @@ extension PluginTarget {
         accessibleTools: [String: (path: AbsolutePath, triples: [String]?)],
         writableDirectories: [AbsolutePath],
         readOnlyDirectories: [AbsolutePath],
+        pkgConfigDirectories: [AbsolutePath],
         fileSystem: FileSystem,
         observabilityScope: ObservabilityScope,
         callbackQueue: DispatchQueue,
@@ -74,7 +76,11 @@ extension PluginTarget {
         // Serialize the plugin action to send as the initial message.
         let initialMessage: Data
         do {
-            var serializer = PluginContextSerializer(fileSystem: fileSystem, buildEnvironment: buildEnvironment)
+            var serializer = PluginContextSerializer(
+                fileSystem: fileSystem,
+                buildEnvironment: buildEnvironment,
+                pkgConfigDirectories: pkgConfigDirectories
+            )
             let pluginWorkDirId = try serializer.serialize(path: outputDirectory)
             let toolSearchDirIds = try toolSearchDirectories.map{ try serializer.serialize(path: $0) }
             let accessibleTools = try accessibleTools.mapValues { (tool: (AbsolutePath, [String]?)) -> HostToPluginMessage.InputContext.Tool in
@@ -324,6 +330,7 @@ extension PackageGraph {
         builtToolsDir: AbsolutePath,
         buildEnvironment: BuildEnvironment,
         toolSearchDirectories: [AbsolutePath],
+        pkgConfigDirectories: [AbsolutePath],
         pluginScriptRunner: PluginScriptRunner,
         observabilityScope: ObservabilityScope,
         fileSystem: FileSystem
@@ -464,6 +471,7 @@ extension PackageGraph {
                     accessibleTools: accessibleTools,
                     writableDirectories: writableDirectories,
                     readOnlyDirectories: readOnlyDirectories,
+                    pkgConfigDirectories: pkgConfigDirectories,
                     fileSystem: fileSystem,
                     observabilityScope: observabilityScope,
                     callbackQueue: delegateQueue,

Sources/XCBuildSupport/PIFBuilder.swift

@@ -24,23 +24,16 @@ import SPMBuildCore
 struct PIFBuilderParameters {
 
     /// Whether or not build for testability is enabled.
-    public let enableTestability: Bool
+    let enableTestability: Bool
 
     /// Whether to create dylibs for dynamic library products.
-    public let shouldCreateDylibForDynamicProducts: Bool
+    let shouldCreateDylibForDynamicProducts: Bool
 
     /// The path to the library directory of the active toolchain.
-    public let toolchainLibDir: AbsolutePath
+    let toolchainLibDir: AbsolutePath
 
-    /// Creates a `PIFBuilderParameters` instance.
-    /// - Parameters:
-    ///   - enableTestability: Whether or not build for testability is enabled.
-    ///   - shouldCreateDylibForDynamicProducts: Whether to create dylibs for dynamic library products.
-    public init(enableTestability: Bool, shouldCreateDylibForDynamicProducts: Bool, toolchainLibDir: AbsolutePath) {
-        self.enableTestability = enableTestability
-        self.shouldCreateDylibForDynamicProducts = shouldCreateDylibForDynamicProducts
-        self.toolchainLibDir = toolchainLibDir
-    }
+    /// An array of paths to search for pkg-config `.pc` files.
+    let pkgConfigDirectories: [AbsolutePath]
 }
 
 /// PIF object builder for a package graph.
@@ -708,7 +701,12 @@ final class PackagePIFProjectBuilder: PIFProjectBuilder {
         var impartedSettings = PIF.BuildSettings()
 
         var cFlags: [String] = []
-        for result in try pkgConfigArgs(for: systemTarget, fileSystem: fileSystem, observabilityScope: self.observabilityScope) {
+        for result in try pkgConfigArgs(
+            for: systemTarget,
+            pkgConfigDirectories: parameters.pkgConfigDirectories,
+            fileSystem: fileSystem,
+            observabilityScope: observabilityScope
+        ) {
             if let error = result.error {
                 self.observabilityScope.emit(
                     warning: "\(error)",

Sources/XCBuildSupport/XcodeBuildSystem.swift

@@ -300,7 +300,8 @@ extension PIFBuilderParameters {
         self.init(
             enableTestability: buildParameters.enableTestability,
             shouldCreateDylibForDynamicProducts: buildParameters.shouldCreateDylibForDynamicProducts,
-            toolchainLibDir: (try? buildParameters.toolchain.toolchainLibDir) ?? .root
+            toolchainLibDir: (try? buildParameters.toolchain.toolchainLibDir) ?? .root,
+            pkgConfigDirectories: buildParameters.pkgConfigDirectories
         )
     }
 }

Tests/BuildTests/MockBuildTestHelper.swift

@@ -77,6 +77,7 @@ func mockBuildParameters(
         hostTriple: hostTriple,
         destinationTriple: destinationTriple,
         flags: flags,
+        pkgConfigDirectories: [],
         jobs: 3,
         shouldLinkStaticSwiftStdlib: shouldLinkStaticSwiftStdlib,
         canRenameEntrypointFunctionName: canRenameEntrypointFunctionName,