Metal运行时动态库与可执行库编译链接及管线创建报错问题

问题场景 #

需要完成以下操作：

• 运行时从源码创建Metal动态库
• 运行时从源码创建Metal可执行库并与此前创建的动态库链接
• 基于上述两个库创建计算管线

执行第三步时触发未定义符号错误：

Error Domain=AGXMetalG15X_M1 Code=2 "Undefined symbols:
  _Z5noisev, referenced from: OnTheFlyKernel
" UserInfo={NSLocalizedDescription=Undefined symbols:
  _Z5noisev, referenced from: OnTheFlyKernel
}

注：通过命令行创建并链接库时无此问题，相关代码如下：

import Foundation
import Metal

class MetalShaderCompiler {
    let device = MTLCreateSystemDefaultDevice()!
    var pipeline: MTLComputePipelineState!
    
    func compileDylib() -> MTLDynamicLibrary {
        let source = """
        #include <metal_stdlib>
        using namespace metal;
        
        half3 noise() {
            return half3(1, 0, 1);
        }
        """
        let option = MTLCompileOptions()
        option.libraryType = .dynamic
        option.installName = "@executable_path/libFoundation.metallib"
        let library = try! device.makeLibrary(source: source, options: option)
        let dylib = try! device.makeDynamicLibrary(library: library)
        return dylib
    }
    
    func compileExlib(dylib: MTLDynamicLibrary) -> MTLLibrary {
        let source = """
        #include <metal_stdlib>
        using namespace metal;
        extern half3 noise();
        kernel void OnTheFlyKernel(texture2d<half, access::read> src [[texture(0)]],
                               texture2d<half, access::write> dst [[texture(1)]],
                               ushort2 gid [[thread_position_in_grid]]) {
        
            half4 rgba = src.read(gid);
        
            rgba.rgb += noise();
        
            dst.write(rgba, gid);
        }
        """
        let option = MTLCompileOptions()
        option.libraryType = .executable
        option.libraries = [dylib]
        let library = try! self.device.makeLibrary(source: source, options: option)
        return library
    }
    
    func runtime() {
        let dylib = self.compileDylib()
        let exlib = self.compileExlib(dylib: dylib)
        
        let pipelineDescriptor = MTLComputePipelineDescriptor()
        pipelineDescriptor.computeFunction = exlib.makeFunction(name: "OnTheFlyKernel")
        pipelineDescriptor.preloadedLibraries = [dylib]
        
        pipeline = try! device.makeComputePipelineState(descriptor: pipelineDescriptor, options: .bindingInfo, reflection: nil)
    }
}

问题原因与修复方案 #

核心原因 #

1. 符号名字修饰不匹配：Metal默认使用C++名字修饰规则，动态库中的noise()被修饰为_Z5noisev，但可执行库中声明的extern half3 noise()未经过相同修饰，导致符号查找失败。
2. 冗余的installName配置：运行时在内存中创建的动态库无需设置installName，该属性仅针对磁盘上的库文件做路径解析，多余配置可能干扰链接逻辑。

修复步骤 #

1. 显式导出动态库符号：在动态库的noise()函数前添加extern "C"，强制使用C风格的符号命名规则，避免名字修饰；同时在可执行库的外部声明中也添加extern "C"，保证符号名称一致。
2. 移除installName配置：删除option.installName = "@executable_path/libFoundation.metallib"这一行。

修复后的完整代码 #

import Foundation
import Metal

class MetalShaderCompiler {
    let device = MTLCreateSystemDefaultDevice()!
    var pipeline: MTLComputePipelineState!
    
    func compileDylib() -> MTLDynamicLibrary {
        let source = """
        #include <metal_stdlib>
        using namespace metal;
        
        extern "C" half3 noise() {
            return half3(1, 0, 1);
        }
        """
        let option = MTLCompileOptions()
        option.libraryType = .dynamic
        let library = try! device.makeLibrary(source: source, options: option)
        let dylib = try! device.makeDynamicLibrary(library: library)
        return dylib
    }
    
    func compileExlib(dylib: MTLDynamicLibrary) -> MTLLibrary {
        let source = """
        #include <metal_stdlib>
        using namespace metal;
        extern "C" half3 noise();
        kernel void OnTheFlyKernel(texture2d<half, access::read> src [[texture(0)]],
                               texture2d<half, access::write> dst [[texture(1)]],
                               ushort2 gid [[thread_position_in_grid]]) {
        
            half4 rgba = src.read(gid);
        
            rgba.rgb += noise();
        
            dst.write(rgba, gid);
        }
        """
        let option = MTLCompileOptions()
        option.libraryType = .executable
        option.libraries = [dylib]
        let library = try! self.device.makeLibrary(source: source, options: option)
        return library
    }
    
    func runtime() {
        let dylib = self.compileDylib()
        let exlib = self.compileExlib(dylib: dylib)
        
        let pipelineDescriptor = MTLComputePipelineDescriptor()
        pipelineDescriptor.computeFunction = exlib.makeFunction(name: "OnTheFlyKernel")
        pipelineDescriptor.preloadedLibraries = [dylib]
        
        pipeline = try! device.makeComputePipelineState(descriptor: pipelineDescriptor, options: .bindingInfo, reflection: nil)
    }
}

补充说明 #

命令行编译时，Metal编译器可能默认处理了符号导出或名字修饰匹配，因此未触发错误。但运行时编译需要显式控制符号可见性和命名规则，确保跨库符号能被正确解析。

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