如何通过SPM将Metal工具着色器与本地可执行Metal库链接

核心思路 #

把Metal辅助函数的源文件放在Swift Package中，通过配置Package的编译路径，让依赖它的本地项目能直接在Metal代码中include这些文件，最终这些函数会被编译进本地项目的默认Metal库，无需额外加载bundle或动态库，完全满足直接链接访问+保留源文件可编辑的需求。

步骤1：构建Swift Package #

1.1 目录结构 #

创建一个名为MetalShaderUtils的Swift Package，结构如下：

MetalShaderUtils/
├── Package.swift
└── Sources/
    └── MetalShaderUtils/
        ├── Utilities.metal  # 实现辅助函数
        └── ShaderHeaders/   # 可选：存放头文件（也可直接用.metal作为头文件）
            └── Utilities.h

1.2 编写Metal辅助函数 #

在Utilities.metal中实现你的函数，用public修饰确保外部可访问，同时添加#pragma once防止重复包含：

#pragma once
#include <metal_stdlib>
using namespace metal;

public float3 rgb2hsv(float3 rgb) {
    float maxc = max(max(rgb.r, rgb.g), rgb.b);
    float minc = min(min(rgb.r, rgb.g), rgb.b);
    float v = maxc;
    
    if (minc == maxc) {
        return float3(0.0, 0.0, v);
    }
    
    float s = (maxc - minc) / maxc;
    float rc = (maxc - rgb.r) / (maxc - minc);
    float gc = (maxc - rgb.g) / (maxc - minc);
    float bc = (maxc - rgb.b) / (maxc - minc);
    float h;
    
    if (rgb.r == maxc) {
        h = bc - gc;
    } else if (rgb.g == maxc) {
        h = 2.0 + rc - bc;
    } else {
        h = 4.0 + gc - rc;
    }
    
    h = fract(h / 6.0);
    return float3(h, s, v);
}

1.3 配置Package.swift #

修改Package.swift，设置资源路径和编译头文件搜索路径，确保依赖项目能找到这些Metal文件：

// swift-tools-version: 5.9
import PackageDescription

let package = Package(
    name: "MetalShaderUtils",
    platforms: [
        .iOS(.v14),
        .macOS(.v11),
        .tvOS(.v14)
    ],
    products: [
        .library(name: "MetalShaderUtils", targets: ["MetalShaderUtils"]),
    ],
    targets: [
        .target(
            name: "MetalShaderUtils",
            resources: [
                .process("ShaderHeaders"),
                .process("Utilities.metal")
            ],
            cSettings: [
                .headerSearchPath("ShaderHeaders")
            ],
            swiftSettings: [
                // 传递头文件路径给依赖项目的编译器
                .unsafeFlags(["-Xcc", "-I" + "\(Package.current.path)/Sources/MetalShaderUtils"])
            ]
        ),
    ]
)

步骤2：本地项目集成与配置 #

2.1 添加Package依赖 #

在本地项目中添加MetalShaderUtils作为Swift Package依赖（Xcode中通过File > Add Packages...，或在项目的Package.swift中添加依赖声明）。

2.2 配置Metal编译路径（Xcode项目） #

如果是Xcode项目，进入项目的Build Settings，找到Metal Compiler - General下的Header Search Paths，添加路径：

$(SRCROOT)/../Packages/MetalShaderUtils/Sources/MetalShaderUtils

路径可根据你的Package实际位置调整，也可以用$(BUILD_DIR)/../MetalShaderUtils/Sources/MetalShaderUtils适配不同构建位置。

2.3 在本地Metal代码中调用辅助函数 #

现在你可以在本地项目的Metal文件中直接include并调用函数：

#include "Utilities.metal"

kernel void myLocalShader(texture2d<float, access::write> outputTexture [[texture(0)]],
                          uint2 gid [[thread_position_in_grid]]) {
    float3 rgbColor = float3(1.0, 0.5, 0.0);
    float3 hsvColor = rgb2hsv(rgbColor);
    
    // 后续处理逻辑
    outputTexture.write(float4(hsvColor, 1.0), gid);
}

关键说明 #

• 无需MTLDynamicLibrary：这个方案是把辅助函数直接编译进本地项目的默认Metal库，属于静态链接，完全兼容所有支持Metal的设备，避开了动态库的兼容性问题。
• 保留源文件可编辑：Package中存放的是.metal源文件，你可以随时修改并提交，依赖该Package的项目会自动获取最新版本的代码。
• 避免了bundle/字符串加载：不需要单独加载外部metallib或把着色器转成字符串编译，完全符合你的要求。

内容的提问来源于stack exchange，提问作者Affinity