从 Ignition 迁移

各位 Gazebo 社区成员：

2022 年 4 月，我们宣布停用“Ignition”名称，改用“Gazebo”。本指南将帮助你对自有包进行相应修改。好消息是，这次迁移不会像从 Gazebo Classic 迁移那么复杂！

概览

变更

具体发生了哪些变更？简要总结如下：

凡是使用名称 Ignition 或 ign 的地方，均替换为对应的 Gazebo 名称（Gazebo 或 gz），并保持大小写一致
ign-gazebo / Ignition Gazebo 变成了 gz-sim / Gazebo Sim
Ignition 标志已被 Gazebo 标志取代

这些变更涉及：

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

这意味着用户的迁移工作主要是对文件名、目录和源码进行查找替换。如需了解核心库为支持迁移所做的具体变更，可查看这个跟踪 Issue。

Tick-tocks 与 Hard-tocks

本节仅概述所做的各类变更。如需更详细的 tick-tock 列表，请参阅各核心库仓库中的迁移文件：

此外，本指南后续章节的迁移要点应能帮助你完成自有包的迁移，使其与 Gazebo 正常配合工作。

Tick-tocks

以下各项均已实现 tick-tock（渐进式过渡），但并非所有都会发出弃用警告。这些 tick-tock 通过别名或重定向机制（如符号链接、目录重定向、源码中的字符串替换）指向对应的 Gazebo 名称。

在源码中，大多数 tick-tock 都带有弃用注释或 GZ_DEPRECATED() 宏调用。

命名空间

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

源代码

公共头文件中的类名、成员、函数和变量
- 例如：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

CMake 与打包

CMake 宏 / 函数
- 例如：ign_find_package() → gz_find_package()
CMake 宏 / 函数参数
- 例如：NO_IGNITION_PREFIX → NO_PROJECT_PREFIX
CMake 变量*
- 例如：IgnOGRE2_FOUND → GzOGRE2_FOUND
- 并非每个 CMake 变量都有 tick-tock，但下游库中使用的大多数变量都有
由 gz_find_package() 查找的 CMake 包
- 例如：gz_find_package(IgnCURL) → gz_find_package(GzCURL)
Debian 包
- 例如：libignition-cmake3-dev → libgz-cmake3-dev

其他

环境变量（名称和值）
- 例如：IGN_GAZEBO_RESOURCE_PATH → GZ_SIM_RESOURCE_PATH
命令行
- 例如：ign → gz、ign gazebo → gz sim
GUI QML
- 例如：IgnSpinBox → GzSpinBox
话题*（通常在测试中）
- 例如：/ignition/XXX → /gz/XXX
- 注意： /gazebo 不会被迁移为 /sim
GitHub 组织和仓库
- 例如：ignitionrobotics → gazebosim、ign-cmake → gz-cmake
GitHub Actions 和工作流
- 例如：ignition-tooling → gazebo-tooling
网站
- 例如：ignitionrobotics.org → gazebosim.org
SDF 和 launch 标签
- 例如：<ignition-gui> → <gz-gui>
SDF 命名空间
- 例如：ignition:type

Hard-tocks

也有一些例外采用了 hard-tock（强制过渡），意味着你必须使用对应的 Gazebo 名称。继续使用 Ignition 名称极有可能导致编译或其他环节出错（除非仅涉及文档变更）。

命名空间

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

源代码

安装目录（install space）
- 例如：install/share/ignition → install/share/gz

CMake 与打包

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

其他

Gazebo launch 文件和标签
- 例如：sim.ign → sim.gzlaunch、<ign → <gz
配置和日志路径（待定）
- 例如：~/.ignition/gui/log → ~/.gz/gui/log
- 一些配置路径已有 tick-tock（例如 ~/.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 库内部且不在下游库中使用的内容（如头文件保护宏、私有头文件或源码、测试、文档）均已采用 hard-tock。

Untocks

只有极少数内容未被迁移，主要出于向后兼容考虑（例如支持 Fortress）。

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

迁移

概览

以下迁移指南提供了包迁移的指导和建议，应能覆盖大多数常见情况。

只需牢记总体目标：将每个 Ignition 写法（IGN、Ign、Ignition、ign、ignition）替换为对应的 Gazebo 写法（GZ、Gz、gz）。

建议

以下做法会有很大帮助：

充分利用正则表达式和 sed
- 迁移指南会提供正则表达式建议，但执行替换前务必先检查
注意大小写！
使用编辑器审查更改，并通过版本控制便于回滚
关注编译警告 / 错误，它们通常会（但并非总是）给出替换建议！
如有疑问，可在跟踪 Issue 中查找对应的变更

此外，如果你从源码构建 Gazebo 组件栈，应进行干净的全新编译和安装：删除 build 和 install 目录，并使用 --merge-install 运行构建。

注意事项

迁移的大部分工作是查找并替换 Ignition 相关术语为对应的 Gazebo 术语。然而，这里有不少边界情况容易导致脚本化处理出错，因此在给出迁移步骤之前，最好先了解其中一些情况。

大小写未正确匹配
- 例如：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
语法
- 例如：“an Ignition library” → “an Gazebo library”

此外，请注意以下情况：

已有的配置文件不会被覆盖。如果你想继续使用旧配置，或配置文件位于自定义位置，可能需要手动将其中的 Ignition 引用改为对应的 Gazebo 引用
- 例如，针对 gz-sim 的旧配置文件可能使用了 ignition::gazebo::systems::Physics 插件。由于该引用尚未迁移，你可能会遇到弃用警告。
安装目录已变更，如有涉及 ignition 的硬编码路径，可能需要改为 gz

迁移步骤

请按顺序执行每个小节中的步骤！这些步骤通常从具体到一般。

迁移文件与文件引用

在包根目录中，查找匹配（不区分大小写）模式 ign(ition)?[_|-]gazebo 的文件和目录，并将 ign / ignition 适当地迁移为 gz，将 gazebo 迁移为 sim
在包根目录中，查找包含（不区分大小写）ign / ignition 的文件和目录，并将它们迁移为 gz，保持大小写一致
更新包中所有对 (1) 和 (2) 中已迁移文件和目录的内部引用

迁移 CMake

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

变量与宏 / 函数调用

Find: IGN(ITION)?_GAZEBO
Replace: GZ_SIM

Find: ign(ition)?_gazebo
Replace: gz_sim

Find: IGN(ITION)?_
Replace: GZ_

Find: ign(ition)?_
Replace: gz_

Include

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-

项目名

Find: ignition-gazebo
Replace: gz-sim

Find: ignition-
Replace: gz-

注意： 有时 CMake 参数会传递到源文件中，请确保一并迁移。

迁移宏与环境变量

有用的环境变量迁移清单
有用的宏迁移清单（参见可折叠的展开块，有些被跳过了！）

迁移源代码宏和环境变量

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

迁移 SDF

在 .sdf 文件中：

Find: <ignition
Replace: <gz

Find: </ignition
Replace: </gz

Find: ignition:
Replace: gz:

一些示例：

<gz:odometer
<gz-gui

迁移插件与共享库

插件查找器（plugin finder）即使插件文件名去掉了 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::

迁移绑定

在 Python 文件（例如 .py）中：

Find: ignition.gazebo
Replace: gz.sim

Find: ignition.
Replace: gz.

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

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

迁移消息

在你的消息定义中：

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

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

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

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

迁移头文件与源文件

全面检查（请特别注意审查这些内容！）

头文件

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

命名空间

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::

其他一切

你可能需要手动检查：

Ign
ignition

同时注意，某些 gazebo 用法（通常是 API 的一部分）需要替换为 sim。

迁移你的 CLI 用法

过去使用的命令：

ign gazebo shapes.sdf

现在应该使用：

gz sim shapes.sdf

请注意，gazebo 动词已弃用。

有用的 CLI 重定向

为了支持 Jetty 和 Fortress 并排安装，Jetty 不会安装 ign CLI 可执行文件（以及 gazebo 动词）。这意味着除非同时安装了 Fortress，否则 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
}

双重检查

以下内容有助于你检查是否有遗漏或错误迁移的情况。

你应该不区分大小写地匹配这些内容。

错误

gz-gazebo
gzition
an gz

遗留的 Ign

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

其他包

本节详细介绍其他一些 Gazebo 相关包中所发生的变更。

ros_gz

ros_ign 已更名为 ros_gz。所有 Jetty 之前版本不再需要的 ign 或 ignition 内部引用均已完成迁移。

如果你想使用自定义 sim 版本或 sim 参数运行 ros_gz 演示，请使用 gz_version 和 gz_args launch 参数。使用 ign_version launch 参数时，还需要显式设置 ign_args launch 参数。