Ubuntu 源码安装

以下说明适用于 Ubuntu Noble (24.04)。

安装工具

建议使用一些额外工具来辅助源码编译，当然也可以通过其他方式获取和构建源码。

获取所有库源码最简单的方法是使用 vcstool。

要以正确的顺序编译各个库和 gz-sim，推荐使用 colcon。colcon 工具可在所有平台上通过 pip（如果 pip 不可用则用 pip3）安装。

部分工具需要 Python 3.5 或更高版本，而某些平台（如 Ubuntu Focal）的默认 Python 版本可能不满足要求。在无法轻易更改默认版本时，Python virtualenv 是一个实用的解决方案。

通用工具

安装本教程所需工具：

sudo apt update && sudo apt install -y python3-pip python3-venv lsb-release gnupg curl git

通过 pip 安装 vcstool 和 colcon

pip 在所有平台上都可用。可用 pip 虚拟环境来安装这些工具：

python3 -m venv $HOME/vcs_colcon_installation
. $HOME/vcs_colcon_installation/bin/activate
pip3 install vcstool colcon-common-extensions

此时 vcs 和 colcon 已在当前终端的 pip 虚拟环境中可用。要在其他终端中使用，请像上面那样运行 activate 脚本。

通过 apt 安装 vcstool 和 colcon

另一种方法是使用 Debian 或 Ubuntu 上的 .deb 包：

sudo sh -c 'echo "deb http://packages.ros.org/ros2/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros2-latest.list'
curl -s https://raw.githubusercontent.com/ros/rosdistro/master/ros.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install python3-vcstool python3-colcon-common-extensions

获取源码

以下说明中使用了一些 UNIX 命令来管理目录，在 Windows 上使用等效命令也能达到同样效果。

首先创建一个开发者工作区，供 vcstool 和 colcon 使用：

mkdir -p ~/workspace/src
cd ~/workspace/

使用 vcstool 从各仓库自动拉取所有 Gazebo 库的源码：

vcs import --input https://raw.githubusercontent.com/gazebo-tooling/gazebodistro/master/collection-jetty.yaml src

此时 src 子目录中应该已包含所有可构建的源码。

安装依赖

编译之前，需要先安装 Jetty 系列中各个包的所有依赖。不同平台安装依赖的方法各不相同。

将 packages.osrfoundation.org 添加到 apt 源列表中：

sudo curl https://packages.osrfoundation.org/gazebo.gpg --output /usr/share/keyrings/pkgs-osrf-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/pkgs-osrf-archive-keyring.gpg] http://packages.osrfoundation.org/gazebo/ubuntu-stable $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/gazebo-stable.list > /dev/null
sudo apt-get update

以下命令必须在包含 Gazebo 源码的工作区中运行，它会在 Ubuntu 上安装所有依赖：

cd ~/workspace/src
sudo apt -y install \
  $(sort -u $(find . -iname 'packages-'`lsb_release -cs`'.apt' -o -iname 'packages.apt' | grep -v '/\.git/') | sed '/gz\|sdf/d' | tr '\n' ' ')

或者，如果想使用 rosdep 安装依赖，请确保 已安装 rosdep，然后运行以下命令：

cd ~/workspace/src
rosdep install -i --from-path . -y \
    --skip-keys "gz-cmake3 DART libogre-dev libogre-next-2.3-dev"

rosdep 命令会尝试安装 package.xml 文件中列出的依赖，但在某些情况下需要用到 --skip-keys 参数。上一行命令中使用它的原因如下：

• gz-cmake3：gz-tools2 可以从源码构建，兼容 gz-cmake3、gz-cmake4 和 gz-cmake (v5) 中的任意一个，而本工作区只包含 gz-cmake (v5)。gz-tools2 的 package.xml 文件 只依赖 gz-cmake3，由于该包不在工作区中，请使用 --skip-keys gz-cmake3。
• DART：gz-physics 可以基于 dartsim 构建，它在 gz-physics 的 package.xml 文件中被列为 DART。该包不在工作区中，因此将 DART 加入 --skip-keys。关于 DART 所用包名的更多背景，请参阅 gz-physics#608 中的讨论。
• libogre-dev 和 libogre-next-2.3-dev：gz-rendering 可以基于 ogre 1.9 和 ogre-next 2.3 构建。Debian 包名在 gz-rendering 的 package.xml 中被列为依赖，但并非在所有 Linux 版本上都可用，因此用 --skip-keys "libogre-dev libogre-next-2.3-dev" 来跳过。

构建 Gazebo 库

编译器和所有源码就位后，即可开始编译。首先进入工作区，查看 colcon 识别到的包：

cd ~/workspace/
colcon graph

colcon graph 应以 依赖关系图 的形式列出 Gazebo 库。确认无误后，即可构建整套库：

警告：编译过程最多可能占用 16 GB 内存。要禁用并行编译线程以降低内存占用，请事先运行 export CMAKE_BUILD_PARALLEL_LEVEL=1（参考），并在下面的 colcon build 命令中加上 --executor sequential（参考）。

colcon build --merge-install

为加快构建速度，也可以禁用测试：

colcon build --cmake-args ' -DBUILD_TESTING=OFF' --merge-install

若需使用调试器，请启用调试符号。Gazebo 运行会变慢，但可使用 GDB：

colcon build --cmake-args ' -DBUILD_TESTING=OFF' ' -DCMAKE_BUILD_TYPE=Debug' --merge-install

要构建某个包及其所有依赖包：

colcon build --merge-install --packages-up-to PACKAGE_NAME

要构建单个包：

colcon build --packages-select PACKAGE_NAME

更多 colcon 构建和测试选项，请参阅 colcon 文档。

如果没有错误，所有二进制文件就都可以使用了。构建出错时可查看 故障排除 一节。

使用工作区

每次打开新终端时都需要 source 工作区。

在 bash 中运行以下命令来 source 工作区：

. ~/workspace/install/setup.bash

或者在 zsh 中：

. ~/workspace/install/setup.zsh

源码安装说明到此结束；返回 入门 页面，开始使用 Gazebo！

卸载源码安装

源码安装可以通过多种方式“卸载”，取决于实际需求：

1. 如果按照上面的说明用 colcon 安装了工作区，所谓“卸载”可能只需要打开一个新终端、不 source 工作区的 setup.sh 即可。这样，环境就会表现得像系统上没有安装 Gazebo 一样。

2. 如果不仅不想使用这些库，还想释放空间，可以删除整个工作区目录：

   rm -rf ~/workspace

3. 如果想保留源代码，可以按需删除 install、build、log 目录，保留 src 目录。

故障排除

参见 故障排除

QML 调试

要进行 QML 调试，需要：

• 给 colcon 添加 --cmake-args -DDQT_QML_DEBUG 标志
• QtCreator

使用以下命令构建 Gazebo：

colcon build --cmake-args ' -DQT_QML_DEBUG' --merge-install

注意： 高级用户可能会注意到，只有 gz-sim 项目需要这个标志。

完成后，启动 gz sim -g 会显示如下信息：

QML debugging is enabled. Only use this in a safe environment.
QML Debugger: Waiting for connection on port 40000...

之后，进入 QtCreator -> Debug -> Start Debugging -> Attach to QML Port... 并输入 QML 端口号：

点击后，将端口号设置为 40000 并点击确定：

我们正在改进 QtCreator 集成，使其开箱即用。

目前 ruby gz 脚本还不能将必要的命令行参数传递给应用程序。

注意，由于所有实例都会尝试使用端口 40000，因此同一时间只能有一个实例使用该端口。如果关闭进程后立即重新启动，操作系统可能仍认为端口被占用，导致第二次启动无法响应 QML 调试器的 attach 请求。

避免启动时因等待调试器而卡住

在开发过程中，可能会发现 gz sim -g 在 QtCreator 连接到 QML 调试端口之前不会真正启动，这会比较麻烦。

如果存在此问题，可以编辑 C++ 文件 gz-sim/src/cmd/gz.cc，从中删除 block。例如：

// The following:
const_cast<char *>(
      "-qmljsdebugger=port:40000,block,services:DebugMessages,QmlDebugger,"
      "V8Debugger,QmlInspector,DebugTranslation")

// Must become the following
const_cast<char *>(
      "-qmljsdebugger=port:40000,services:DebugMessages,QmlDebugger,"
      "V8Debugger,QmlInspector,DebugTranslation")