Go 中使用 PortMidi 的正确安装与编译指南

本文详解 go 项目中集成 portmidi 时常见的链接错误（如 `undefined reference to symbol 'pt_start'`）的根本原因及解决方案，强调必须从源码编译 portmidi 库而非依赖系统包管理器安装的二进制版本。

在 Go 中使用 rakyll/portmidi 这一 Cgo 封装库时，许多开发者会遇到如下典型链接错误：

/usr/bin/ld: $WORK/github.com/rakyll/portmidi/_obj/portmidi.cgo2.o: undefined reference to symbol 'Pt_Start'
/usr/lib/libporttime.so.0: error adding symbols: DSO missing from command line
collect2: error: ld returned 1 exit status

该错误并非 Go 代码或 go get 命令本身的问题，而是 C 链接阶段缺失关键动态共享对象（DSO） 所致——具体来说，Pt_Start 是 PortTime 子库中的函数，而 libporttime.so 未被正确链接进最终可执行文件。

⚠️ 关键误区：
许多用户尝试通过系统包管理器安装（如 apt install libportmidi0 或 libportmidi-dev），但这些预编译包往往存在以下问题：

• 缺少 libporttime.so 的导出符号（尤其在较新 Ubuntu/Debian 版本中）；
• 头文件路径不匹配或版本陈旧（PortMIDI v217 是当前最稳定兼容版本）；
• pkg-config 信息不完整，导致 cgo 无法自动推导 -lportmidi -lporttime 等链接标志。

✅ 正确做法：从官方源码手动编译安装 PortMIDI

1. 下载并解压源码
   访问 PortMIDI 官方 SourceForge 页面，下载 portmidi-src-217.zip 并解压：

   wget https://www./link/7b25edf03ff74e3bf57eaad1ea452f38 -O portmidi-src-217.zip
   unzip portmidi-src-217.zip
   cd portmidi/

2. 编译并安装（Linux 示例）
   进入 pm_linux/ 目录，按官方说明执行构建：

   cd pm_linux
   make clean
   make
   sudo make install

   默认会将头文件安装至 /usr/local/include/，库文件至 /usr/local/lib/，并注册 portmidi.pc 和 porttime.pc 到 /usr/local/lib/pkgconfig/。

3. 验证 pkg-config 是否就绪
   确保 pkg-config 能识别两个必需组件：

   pkg-config --modversion portmidi
   pkg-config --modversion porttime
   pkg-config --libs portmidi porttime  # 应输出类似：-L/usr/local/lib -lportmidi -lporttime

   若提示 Package not found，请设置环境变量：

   export PKG_CONFIG_PATH="/usr/local/lib/pkgconfig:$PKG_CONFIG_PATH"

4. 在 Go 项目中安全使用
   确保 CGO_ENABLED=1（默认开启），然后运行：

   go get github.com/rakyll/portmidi

   ✅ 此时 cgo 将通过 pkg-config 自动注入正确的 -I 和 -l 参数，链接成功。

? 补充说明：

• macOS 用户应使用 pm_macosx/ 目录下的 Makefile；Windows 用户建议使用 MSVC 或 MinGW 工具链配合 pm_win/ 目录构建。
• 若需静态链接，可在 make 后检查生成的 libportmidi.a 和 libporttime.a，并在 #cgo LDFLAGS 中显式指定。
• rakyll/portmidi 已归档（archive），生产项目建议 fork 维护或评估更活跃的替代方案（如 gitlab.com/gomidi/midi），但其纯 Go 实现不依赖 PortMIDI C 库。

遵循以上流程，即可彻底解决 DSO missing from command line 和 undefined reference to symbol 类链接错误，为 Go MIDI 应用打下可靠底层基础。