Ubuntu 上从源码编译 Tracy Profiler

Tracy 是游戏和实时应用常用的性能分析器，但官方只提供 Windows 预编译包，Linux 用户只能自己编译；官方那个 AppImage 又是 Wayland-only 构建，跑在 X11 会话下启动即崩。本文记录一次完整的编译过程，不需要修改任何 Tracy 源码，选对几个 CMake 开关就行。

为什么需要自己编译

Tracy 的官方 Release 只提供 Windows x64 预编译包（Tracy-<version>.7z），Linux 用户没有现成二进制。

官方另有一个 AppImage（tracy-profiler-x86_64.AppImage），但它是 Wayland-only 构建。如果运行在 X11 会话下，启动会直接崩溃：

1
2
3

Cannot establish wayland display connection!
terminate called without an active exception
[1]  40249 IOT instruction (core dumped)  ./tracy-profiler-x86_64.AppImage

从源码编译可以构建出与本机会话匹配的程序。

环境要求

项目	要求	说明
系统	Ubuntu 22.04 / 24.04	本文在 24.04.5 实测
CMake	≥ 3.25	GUI 的 `profiler/CMakeLists.txt` 要求 3.25；22.04 自带的 3.22 不满足
C++ 编译器	支持 C++20（GCC 10+）	本文用 g++ 13.3.0
构建工具	Ninja 或 Make	Ninja 更快，可选
磁盘	约 1 GB	依赖源码缓存约 470 MB + 构建目录约 210 MB
网络	能访问 GitHub	配置阶段会自动拉取依赖源码

实测环境：Ubuntu 24.04.5 LTS、g++ 13.3.0、CMake 3.28.3、Ninja 1.11.1、Tracy 提交 30997d5c。

第一步：确认显示会话类型

这一步决定后面用哪套开关，请先做：

1 2	echo "会话类型: $XDG_SESSION_TYPE" echo "DISPLAY=$DISPLAY WAYLAND_DISPLAY=$WAYLAND_DISPLAY"

输出 x11：跑在 Xorg 上，必须按下面的方案构建（禁用 Wayland 后端）。
输出 wayland：默认构建通常可用；但本文的方案在启用了 XWayland 的 Wayland 会话下同样能跑，且是实测过的路径，建议优先采用。

第二步：安装依赖

sudo apt update
sudo apt install -y \
  build-essential cmake git pkg-config \
  libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libxext-dev \
  libgl1-mesa-dev \
  libfreetype-dev libdbus-1-dev libcurl4-openssl-dev libpugixml-dev \
  ninja-build

各包作用：

包	作用
`build-essential` `cmake` `git` `pkg-config`	基础工具链
`libx11-dev` `libxrandr-dev` `libxinerama-dev` `libxcursor-dev` `libxi-dev` `libxext-dev`	X11 后端与 GLFW 编译所需
`libgl1-mesa-dev`	提供 `GL/gl.h` 与 `GL/glx.h`（经 `libgl-dev`、`libglx-dev` 传递依赖）
`libfreetype-dev`	字体渲染。不装则 Tracy 自行编译一份 freetype，更慢
`libdbus-1-dev`	文件选择器（xdg-desktop-portal 后端）所需
`libcurl4-openssl-dev` `libpugixml-dev`	在线功能与 XML 解析。不装则 Tracy 自行编译这两者
`ninja-build`	可选，加快构建

Ubuntu 22.04 的差异（未实测）

自带 CMake 3.22 低于要求的 3.25，需另装新版（Kitware APT 源，或 pip install cmake）。
freetype 开发包名为 libfreetype6-dev，不是 libfreetype-dev。
自带 libcurl4-openssl-dev 是 7.81，低于 Tracy 要求的 7.87，Tracy 会改为自行编译 libcurl（可以用，只是慢）。

第三步：配置

cd <你的 tracy 仓库路径>
export CPM_SOURCE_CACHE="$HOME/.cache/CPM"   # 依赖源码缓存，重建时可复用

cmake -B profiler/build -S profiler \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DLEGACY=ON \
  -DGLFW_BUILD_WAYLAND=OFF \
  -DNFD_WAYLAND=OFF

三个开关缺一不可：

开关	作用
`-DLEGACY=ON`	让 Tracy 使用 X11 后端（`BackendGlfw.cpp`），替代默认的 Wayland 后端（`BackendWayland.cpp`）。不加这个，程序在 X11 会话下起不来
`-DGLFW_BUILD_WAYLAND=OFF`	内置 GLFW 3.4 默认同时编译 X11 和 Wayland 两个后端，缺少 `wayland-scanner` 时会直接 `FATAL_ERROR` 中止
`-DNFD_WAYLAND=OFF`	文件选择器依赖 nfd 也默认编译 Wayland 支持，要求 `wayland-client.pc`，否则配置失败

配置成功的标志是结尾出现 -- Configuring done 与 -- Generating done。首次配置会从 GitHub 拉取 capstone、zstd、ImGui、nfd 等依赖源码，耗时取决于网速。

第四步：编译

1	cmake --build profiler/build --parallel "$(nproc)"

产物：profiler/build/tracy-profiler，Release 加 LTO 链接后约 52 MB。

出现下面这条警告可以忽略，实测生成的 ELF 中 GNU_STACK 段为 RW，栈不可执行属性正常：

1	lto-wrapper: warning: Extra option to '-Xassembler': --noexecstack, dropping all ...

第五步：验证

1 2	ldd profiler/build/tracy-profiler \| grep 'not found' \|\| echo "动态库全部解析" ./profiler/build/tracy-profiler

配套下载：已编译的 profiler 与插桩 demo

如果不想自己走一遍上面的流程，这里有一份已经编译好的成品压缩包，解开即可使用：

下载 tracyDemo.zip（10 MB）

压缩包内容：

路径	说明
`demo/bin/tracy-profiler`	已编译的 GUI 分析器，Release 构建，X11 后端（按本文方案编译，X11 与启用 XWayland 的 Wayland 会话均可运行）
`demo/bin/matmul_demo`	配套的多线程分块矩阵乘法示例程序，C++11，已带 Tracy 插桩
`demo/include/`	Tracy 头文件的完整拷贝（`public/` 整份，含 `TracyClient.cpp`）
`demo/src/`	示例程序源码：`main.cpp`、`matmul.cpp`、`matmul.hpp`
`demo/CMakeLists.txt`	示例的构建脚本，把 Tracy 客户端编成独立静态库并屏蔽其头文件警告
`demo/README.md`	参数说明、构建与运行步骤、分析要点

用法：

unzip tracyDemo.zip && cd demo
cmake -B build -S . -DCMAKE_BUILD_TYPE=RelWithDebInfo
cmake --build build --parallel "$(nproc)"

./bin/tracy-profiler &        # 先开分析器，监听 8086 端口
./bin/matmul_demo             # 再跑示例，循环执行不退出，直接在 GUI 里看

示例用多线程分块做矩阵乘法，每个线程的块和瓦片都有独立 zone，默认参数下会持续产生 4096 个 tile zone，适合观察 zone 密度对开销的影响。详细说明见压缩包内的 README.md。

常见问题

Failed to find wayland-scanner

内置 GLFW 试图编译 Wayland 后端但找不到 wayland-scanner，导致 FATAL_ERROR。加 -DGLFW_BUILD_WAYLAND=OFF。若确实需要 Wayland 后端，安装 libwayland-bin。

The following required packages were not found: wayland-client

nfd（文件选择器）需要 wayland-client.pc。加 -DNFD_WAYLAND=OFF；若需要 Wayland，安装 libwayland-dev。

找不到 GL/gl.h 或 X11/Xlib.h

缺少 libgl1-mesa-dev 或 libx11-dev。

apt 报依赖冲突：依赖 X (= 旧版本) 但是新版本正要被安装

这通常不是真的版本冲突，而是 apt 源缺少 noble-updates。已经从该源安装的包在新源里不可见，导致 -dev 包要求的精确版本无法满足。检查：

1	grep -E '^Suites:' /etc/apt/sources.list.d/ubuntu.sources

正常应同时包含 noble、noble-updates、noble-security。缺了就补上：

sudo cp /etc/apt/sources.list.d/ubuntu.sources{,.bak}
sudo sed -i 's/^Suites: noble$/Suites: noble noble-updates noble-backports/' \
        /etc/apt/sources.list.d/ubuntu.sources
sudo apt update

CMake 报版本过低

GUI 要求 CMake ≥ 3.25。

能否改用系统自带的 GLFW

Ubuntu 24.04 的 libglfw3-dev 是 3.3.10，而 Tracy 固定使用 GLFW 3.4，因此默认从源码编译 GLFW。不建议换成系统版本。

附：编译命令行工具（未实测）

tracy-profiler 能直接连接被分析的程序，通常不需要额外工具。若还需要 tracy-capture、tracy-csvexport、tracy-merge、tracy-import-chrome 等：

for t in update capture csvexport import merge; do
  cmake -B "$t/build" -S "$t" -G Ninja -DCMAKE_BUILD_TYPE=Release -DNO_ISA_EXTENSIONS=ON
  cmake --build "$t/build" --parallel "$(nproc)"
done

这些工具只要求 CMake ≥ 3.16，依赖比 GUI 少得多。

附：原生 Wayland 构建（未实测）

如果 Wayland 会话禁用了 XWayland，需要构建原生 Wayland 后端的版本：去掉 -DLEGACY=ON（cmake/config.cmake 会自动打开 USE_WAYLAND），并安装 Wayland 相关开发包。此时 Tracy 走 BackendWayland.cpp，不再使用 GLFW，GLFW_BUILD_WAYLAND 与 NFD_WAYLAND 两个开关也不起作用。

权威参考是 Tracy 自己的 CI 配置 .github/workflows/appimage.yml 与 profiler/appimage/build.sh：前者在 Ubuntu 24.04 上安装 libegl-dev libxkbcommon-dev libdbus-1-dev 等，后者会从源码构建一份固定版本的 Wayland 客户端库并打包进 AppImage。

附：增量重建与清理

cmake --build profiler/build --parallel "$(nproc)"   # 增量重建

rm -rf profiler/build          # 构建产物，约 210 MB
rm -rf "$HOME/.cache/CPM"      # 依赖源码缓存，约 470 MB，删掉后下次配置会重新下载

乱七八糟