Gazebo 从 Ignition 迁移指南

系列文章目录

---

---

前言

您好，Gazebo 社区

2022 年 4 月，我们宣布退出 “Ignition”，改用 “Gazebo”。本迁移指南将帮助您在自己的软件包中执行必要的更改，幸运的是，它不会像从 Gazebo Classic 迁移那样麻烦！

---

一、概览

1.1 变化

那么，实际情况如何呢？总而言之：

• 无论何时使用 Ignition 或 ign 名称，都会使用 Gazebo 的对应名称（Gazebo 或 gz），并保留以下情况
• ign-gazebo / Ignition Gazebo 变成了 gz-sim / Gazebo Sim
• Ignition 徽标已被 Gazebo 徽标取代。

这些更改是在

• 网站
• GitHub 组织和资源库
• 文档
• UI 用户界面
• 命名空间、命令行工具、共享库、目录、API、文件

这意味着用户迁移的大部分工作将涉及文件名、目录和源代码的智能查找和替换。如果您需要跟踪为支持核心库迁移而做出的任何更改，也可以查看 GitHub 上的跟踪问题。

1.2 Tick-tocks and Hard-tocks

本节仅概述了所做的不同改动，如需更详细的 tick-tocks 列表，请参阅各个核心库软件仓库中的迁移文件：

• gz-cmake
• gz-common
• gz-fuel-tools
• gz-gui
• gz-launch
• gz-math
• gz-msgs
• gz-physics
• gz-plugin
• gz-rendering
• gz-sensors
• gz-sim
• gz-tools
• gz-transport
• gz-utils
• sdformat

此外，本迁移指南后续章节中的迁移指针也能帮助您准备好软件包并使用 Gazebo。

一般来说，如果您使用的是 Harmonic，由于堆栈中编写了明确的滴答计时逻辑，您仍然可以使用 Ignition 对应程序或 Gazebo 对应程序来处理大多数事情。需要注意的是，使用 Ignition 对应程序通常会引发报废警告。

1.3 Tick-tocks

以下的 Tick-tocks 均已实现，但并非所有 Tick-tocks 都会发出弃用警告。这些 tick-tocks 要么以别名的形式实现，要么以某种重定向机制（如符号链接、目录重定向、源代码中的字符串替换）来替代 Gazebo 对应的目标。

此外，在源代码中，大多数 tick-tocks 都会有相关注释，说明它们已被弃用，或者有一个 GZ_DEPRECATED() 宏调用。

1.3.1 Namespaces（命名空间）

• Python 命名空间
  • 例如 ignition.math.XXX → gz.math.XXX
• C++ 命名空间
  • 例如 ignition::gazebo::XXX → gz::sim::XXX
• 消息命名空间和包
  • 例如 ignition.msgs.XXX → gz.msgs.XXX, ignition/msgs/header.proto → gz/msgs/header.proto

1.3.2 Source（源文件）

• 公共头文件中的类名、成员、函数和变量
  • 例如：IgnitionFormatter → GzFormatter
• 公共头文件
  • 例如：include/ignition → include/gz
• 插件
  • 例如 ignition::gazebo::systems::LiftDrag → gz::sim::systems::LiftDrag
• 共享库
  • 例如 libignition-gazebo-buoyancy-engine-system.so → libgz-sim-buoyancy-engine-system.so
  • 您可以删除 lib 和 .so 前缀和后缀！
    • 例如 libignition-gazebo-buoyancy-engine-system.so → gz-sim-buoyancy-engine-system
• 公共头文件中的 C++ 宏
  • 例如 IGN_PARTITION → GZ_PARTITION

1.3.3 CMake and Packaging（CMake 和打包）

• CMake 宏/函数
  • 例如 ign_find_package() → gz_find_package()
• CMake 宏/函数参数
  • 例如 NO_IGNITION_PREFIX → NO_PROJECT_PREFIX
• CMake 变量*
  • 例如 IgnOGRE2_FOUND → GzOGRE2_FOUND
  • 并非每个 CMake 变量都是 tick-tocked 的，但下游库中使用的大多数 CMake 变量都是
• 通过 gz_find_package() 找到的 CMake 软件包
  • 例如 gz_find_package(IgnCURL) → gz_find_package(GzCURL)
• Debian 软件包
  • 例如 libignition-cmake3-dev → libgz-cmake3-dev

1.3.4 Misc.（其他杂项）

• 环境变量（名称和值）
  • 例如 IGN_GAZEBO_RESOURCE_PATH → GZ_SIM_RESOURCE_PATH
• 命令行
  • 例如 ign → gz， ign gazebo → gz sim
• 图形用户界面 QML
  • 例如，IgnSpinBox → GzSpinBox
• 话题*（通常在测试中）
  • 例如：/ignition/XXX → /gz/XXX
  • 注意：/gazebo 不会迁移到 /sim
• GitHub 组织和资源库
  • 例如： ignitionrobotics → gazebosim , ign-cmake → gz-cmake
• GitHub 操作和工作流程
  • 例如 ignition-tooling → gazebo-tooling
• 网站
  • 例如 ignitionrobotics.org → gazebosim.org
• SDF 和 Launch 标签
  • 例如： →
• SDF 命名空间
  • 例如 ignition:type

1.4 Hard-tocks

有一些例外情况是硬性规定的，这意味着您必须使用 Gazebo 对应程序。使用 Ignition 对应程序很可能会导致编译或其他方面的中断（除非只是文档上的改动）。

1.4.1 命名空间

• Ruby 命名空间
  • 例如 ignition/math → gz/math

1.4.2 源代码

• 安装空间
  • 例如 install/share/ignition → install/share/gz

1.4.3 CMake 和打包

• 大多数可包含的 CMake 文件在 gz-cmake 中
  • 例如：IgnUtils.cmake → GzUtils.cmake
• Gazebo 库 CMake 项目名称
  • 例如 ignition-utils2 → gz-utils2
• 内部使用的 CMake 变量
  • 例如 IGN_TRANSPORT_VER → GZ_TRANSPORT_VER

1.4.4 杂项

• Gazebo 启动文件和标签
  • 例如：sim.ign → sim.gzlaunch,
• 配置和日志路径（待定）
  • 例如 ~/.ignition/gui/log → ~/.gz/gui/log
  • 某些配置路径已被勾选（例如 ~/.ignition/gazebo/plugins）
• Fuel URL（待定）
  • 例如 https://fuel.ignitionrobotics.org
• Fuel 缓存路径（也在待定中）
  • 例如 ~/.ignition/fuel → ~/.gz/fuel
• 文档和注释中的库名
  • 例如，Ignition Gazebo → Gazebo Sim
• gz-launch Websocket 服务器
  • 例如 ign.js → gz.js

此外，任何属于 Gazebo 核心库内部且未在下游库中使用的内容（如头文件保护、私有头文件或源代码、测试、文档）都会被硬锁定。

1.5 Untocks

有一小部分内容没有迁移，主要是出于向后兼容的原因（如支持 Fortress）。

• 针对 Harmonic 之前版本的 Gazebo 库的分支名称
  • 例如 ign-cmake2
• 一些链接
  • 例如 https://osrf-migration.github.io/ignition-gh-pages
• 与 Fuel 用户代理相关
  • 例如：X-Ign-Resource-Version、IgnitionFuelTools

二、迁移

2.1 概览

以下迁移指南仅是如何迁移软件包的指南和建议，应涵盖大多数一般情况。

请牢记将所有 Ignition 对应程序（IGN、Ign、Ignition、 ign、ignition）替换为 Gazebo 对应程序（GZ、Gz、gz）的总体目标。

2.2 建议

以下做法可能会有很大帮助

• 充分利用 regex 和 sed
  • 迁移指南会建议使用哪些 regex 表达式，但在执行替换之前一定要进行复查
• 注意大小写
• 使用编辑器审核更改，并使用源码控制以方便回滚
• 注意编译警告/错误，它们通常（但不总是）会给出替换建议！
• 如有疑问，可追溯到跟踪问题中列出的更改

此外，如果您是从源代码构建 Gazebo 协议栈，则应进行干净、全新的重建和安装。删除 build 和 install 目录，然后使用 --merge-install 运行联编。

2.3 常见问题

大部分迁移工作主要是查找与 Ignition 相关的术语，并将其替换为与 Gazebo 相关的术语。

不过，有很多边缘情况会导致难以创建脚本来处理迁移（导致错误或 bug），因此在建议迁移步骤之前，最好先了解其中的一些情况。

• 不区分大小写

  • 例如 IGNITION_ADD_PLUGIN → gz_ADD_PLUGIN

• 贪心匹配

  • 例如：Align → Algz，unsigned → unsgzed，signal → sgzal

• 不将 "gazebo "迁移到 “sim”

  • 例如：ign-gazebo → gz-gazebo（应为 gz-sim）

• 在 ignition 前匹配 ign

  • 例如 ignition-cmake3 → gzition-cmake3

• 迁移不应迁移的库

  • 例如 ignition-cmake2 → gz-cmake2

• 语法

  • 例如：“一个 Ignition 库” → “一个 Gazebo 库”
    此外，请注意以下行为：

• 已存在的配置文件不会被覆盖，因此如果你想使用旧的配置文件或在自定义位置有一个配置文件，你可能需要手动迁移配置文件中的 Ignition 对应引用，让它们指向相应的对应文件。

  • 例如，以前的配置文件中的 gz-sim 文件可能使用了 ignition::gazebo::systems::Physics 插件。你可能会遇到弃用警告，因为该引用尚未迁移。

• 由于安装空间发生了变化，如果你有涉及 ignition 的硬编码位置，可能需要将它们迁移到 gz

2.4 迁移步骤

按顺序执行各个部分的步骤非常重要！这些步骤通常从具体到一般。

迁移文件和文件引用

1. 在软件包根目录中，查找与 ign(ition)?[_|-]gazebo 模式（不区分大小写）相匹配的文件和目录，并将 ign / ignition 适当迁移到 gz，将 gazebo 迁移到 sim。
2. 在软件包根目录中，查找带有 ign / ignition 的文件和目录（不区分大小写），并将它们移至 gz，同时匹配大小写
3. 更新软件包中所有对（1）和（2）中已迁移文件和目录的内部引用

2.5 迁移 CMake

CMakeLists.txt 文件（以及它们在源文件中的引用！）中：

2.5.1 变量和宏/函数调用

Find: IGN(ITION)?_GAZEBO
Replace: GZ_SIM

Find: ign(ition)?_gazebo
Replace: gz_sim

Find: IGN(ITION)?_
Replace: GZ_

Find: ign(ition)?_
Replace: gz_

2.5.2 Includes 文件

Find: include\(Ign
Replace: include(Gz

Find: include\(ign
Replace: include(gz

Find: gz_find_package\(ign-
Replace: gz_find_package(gz-

Find: gz_find_package\(Ign(ition)?
Replace: gz_find_package(Gz-

2.5.3 项目名称

Find: ignition-gazebo
Replace: gz-sim

Find: ignition-
Replace: gz-

注意：CMake 参数有时会渗透到源文件中，因此请确保也对它们进行了适当的迁移。

2.6 迁移宏和环境变量

• 环境变量迁移帮助列表
• 宏迁移的有用列表（请参阅可切换的下拉块，有些会被跳过）

2.7 迁移源代码宏和环境变量

Find: IGN(ITION)?_GAZEBO
Replace: GZ_SIM

Find: ign(ition)?_gazebo
Replace: gz_sim

Find: IGN(ITION)?_
Replace: GZ_

Find: ign(ition)?_
Replace: gz_

对于环境变量，可以使用与宏相同的方法，但要注意环境变量中存储的值！(例如路径）。

此外，日志宏也已迁移！迁移任何用途！

• ignerr -> gzerr
• ignwarn -> gzwarn
• ignmsg -> gzmsg
• igndbg -> gzdbg
• ignlog -> gzlog
• ignLogInit -> gzLogInit
• ignLogClose -> gzLogClose
• ignLogDirectory -> gzLogDirectory

2.8 迁移 SDF

在 .sdf 文件中：

Find: <ignition
Replace: <gz

Find: </ignition
Replace: </gz

Find: ignition:
Replace: gz:

举几个例子：

2.9 迁移插件和共享库

即使插件的文件名去除了 lib 和 .so，插件查找器也能找到它们。

在 .sdf 文件和源文件（如 .cc）中：

Find: (lib)?ign(ition)?-gazebo([^. ]*)\.so
Replace: gz-sim\3

Find: (lib)?ign(ition)?([^. ]*)\.so
Replace: gz\3

Find: ignition::gazebo
Replace: gz::sim

Find: ignition::
Replace: gz::

2.10 迁移绑定

在 Python 文件中（如 .py）

Find: ignition.gazebo
Replace: gz.sim

Find: ignition.
Replace: gz.

在 Ruby 文件（如 .i、.rb）中

Find: ign(ition)?/
Replace: gz/

2.11 迁移消息

在您的信息定义中在您的消息定义中

Find: ign(ition)?\.gazebo
Replace: gz.sim

Find: ign(ition)?/gazebo
Replace: gz/sim

Find: ign(ition)?\.
Replace: gz.

Find: ign(ition)?/
Replace: gz/

2.12 迁移头文件和源文件

到处扫查（特别注意审查这些内容！）。

2.12.1 头文件

Find: #include\s*([<"])ign(ition)?/gazebo
Replace: #include \1gz/sim

Find: #include\s*([<"])ign(ition)?/
Replace: #include \1gz/

// Note: You should be wary of the IGNITION GAZEBO case for the following
// and adjust accordingly
Find: #([^\s]*)\s+(.*)IGN(?:ITION)?_(.*)_(H+)_(.*)$
Replace: #$1 $2GZ_$3_$4_$5

Find: #endif\s*// GZ(.*)_H
Replace: #endif  // GZ$1_H

2.12.2 命名空间

Find: namespace\s*ignition
Replace: namespace gz

Find: namespace\s*gazebo
Replace: namespace sim

Find: ignition::gazebo
Replace: gz::sim

Find: Ignition::Gazebo
Replace: Gz::Sim

Find: ignition::
Replace: gz::

Find: Ignition::
Replace: Gz::

2.12.3 其他

您可能需要手动检查：

• ign
• ignition

还要注意，某些 gazebo 实例（通常作为 API 的一部分）需要使用 sim 来代替。

2.13 迁移 CLI 命令行使用

您曾经使用过的地方：

ign gazebo shapes.sdf

现在您应该使用

gz sim shapes.sdf

注意，"gazebo "动词已被弃用。

2.13.1 有用的 CLI 命令行重定向

为了支持同时安装 Harmonic 和 Fortress，Harmonic 将不安装 ign CLI 可执行文件（和 gazebo verb）。这意味着除非同时安装 Fortress 和 Harmonic，否则 CLI 的使用必须进行迁移。使用 gz 代替 ign，使用 sim 代替 gazebo。

你可以在 ~/.bashrc 文件中添加以下脚本，将任何 ign 调用重定向到 gz，这样就不必迁移所有脚本（仍在使用 ign），不过还是建议进行迁移。

ign() {
  if which ign &> /dev/null; then
    $(which ign) "$@"
  else
    if which gz &> /dev/null; then
      echo "[DEPRECATED] ign is deprecated! Please use gz instead!"
      if [ "$1" = "gazebo" ]; then
        echo "[DEPRECATED] The gazebo verb is deprecated! Please use sim instead!"
        shift
        $(which gz) sim "$@"
      else
        $(which gz) "$@"
      fi
    else
      echo "[ERROR] It seems like you don't have Gazebo installed!"
      return 1
    fi
  fi
}

2.14 双重检查

如果您有任何遗留问题或错误迁移的实例，这些内容可能有助于进行双重检查

应根据具体情况进行匹配。

2.14.1 错误

• gz-gazebo
• gzition
• gz

2.14.2 剩余点火

• \.ign(ition)?
• ign(ition)?[-_]

---

三、附加软件包

本节将详细介绍其他一些与 Gazebo 相关的软件包所发生的变化。

3.1 ros_gz

ros_ign 已更名为 ros_gz。所有对 ign 或 ignition 的内部引用（Gazebo 的预览 Harmonic 版本不依赖这些引用）都已迁移。

如果想使用自定义模拟版本或模拟参数运行 ros_gz 演示，请使用 gz_version 和 gz_args 启动参数。使用 ign_version 启动参数还需要明确设置 ign_args 启动参数。