Nix 包管理器的 ROS overlay

轻松在任何 Linux 发行版上安装 Robot Operating System (ROS)

想使用 ROS，但不想运行 Ubuntu？本项目利用 Nix 的强大功能，使其能够在任何 Linux 机器上以相同的方式开发和运行 ROS 包。

Nix 是一个与发行版无关的包管理器，它使用纯函数式编程语言来可靠且可复现地构建软件。这些特性使其有潜力成为在任何机器上运行 ROS 的最简单方式之一，无论操作系统是什么。

[!IMPORTANT] master 分支在大多数包都能正常工作时进行测试和更新。开发在 develop 分支上进行，预计该分支有时会有许多包构建失败。请勿针对仅在 develop 分支中出现的 bug 提交问题。

当前状态

发行版	master	develop	develop + nixos-unstable
Humble
Jazzy
Kilted
Lyrical
Rolling

有效的方法：

大多数软件包构建成功（见上表）
使用 nix-shell 构建的全功能 ROS 开发环境
使用标准 ROS 工具自动化生成 Nix 软件包定义（superflore)

仍需完成的工作：

更新 ROS 软件包以适配最新的 nixpkgs 并将其提交至上游
macOS 支持

设置

Install Nix: https://nixos.org/nix/download.html
(Optional) configure Nix to use ROS Cachix binary cache
Try one of the examples

示例

ROS 2 Jazzy 桌面环境：

nix-shell \
  -I nix-ros-overlay=https://github.com/lopsided98/nix-ros-overlay/archive/master.tar.gz \
  --option extra-substituters 'https://ros.cachix.org' \
  --option extra-trusted-public-keys 'ros.cachix.org-1:dSyZxI8geDCJrwgvCOHDoAfOm5sV1wCPjBkKL+38Rvo=' \
  '<nix-ros-overlay/examples/ros2-desktop.nix>' --argstr rosDistro jazzy
# Run command-line talker/listener demo
ros2 launch demo_nodes_cpp talker_listener_launch.xml

如果你想在非 NixOS 发行版上运行 rviz2 等图形应用程序，我们建议使用 nix-system-graphics 或 nixGL。后者不太方便，但无需更改系统范围的配置。

Flakes

启用 Flakes 后，上述内容的等效形式为：

nix develop github:lopsided98/nix-ros-overlay/master#example-ros2-desktop-jazzy
# Run command-line talker/listener demo
ros2 launch demo_nodes_cpp talker_listener_launch.xml

在基于 flake.nix 的项目中使用该 overlay 可能如下所示：

{
  inputs = {
    nix-ros-overlay.url = "github:lopsided98/nix-ros-overlay/master";
    nixpkgs.follows = "nix-ros-overlay/nixpkgs";  # IMPORTANT!!!
  };
  outputs = { self, nix-ros-overlay, nixpkgs }:
    nix-ros-overlay.inputs.flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ nix-ros-overlay.overlays.default ];
        };
      in {
        devShells.default = pkgs.mkShell {
          name = "Example project";
          packages = [
            pkgs.colcon
            # ... other non-ROS packages
            (with pkgs.rosPackages.humble; buildEnv {
              underlay = true;
              paths = [
                ros-core
                # ... other ROS packages
              ];
            })
          ];
        };
      });
  nixConfig = {
    extra-substituters = [ "https://ros.cachix.org" ];
    extra-trusted-public-keys = [ "ros.cachix.org-1:dSyZxI8geDCJrwgvCOHDoAfOm5sV1wCPjBkKL+38Rvo=" ];
  };
}

你可以使用以下命令轻松使用上述模板：

nix flake init --template github:lopsided98/nix-ros-overlay

配置二进制缓存

预构建的 ROS 软件包（针对 x86_64-linux 和 aarch64-linux）托管在 Cachix 上，并使用公共基础设施上的 GitHub Actions 构建。

要使用此二进制缓存，请运行 cachix use ros 或在 nix.conf 中手动设置以下选项：

substituters = https://cache.nixos.org https://ros.cachix.org
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= ros.cachix.org-1:dSyZxI8geDCJrwgvCOHDoAfOm5sV1wCPjBkKL+38Rvo=

[!WARNING] 不幸的是，免费 Cachix 缓存的容量已不再足够，软件包可能在短时间内被驱逐或根本不存在。我们正在努力解决这一情况。在解决之前（目前尚无预计时间），你可以使用由 @wentasah 维护并由其 [Hydra][Hydra 实例] 填充的 实验性二进制缓存。请注意，不保证 100% 可用性，带宽可能会受到限制，尤其是在欧洲以外地区。

要使用实验性二进制缓存，请将以下内容添加到你的 nix.conf 中：
extra-substituters = https://attic.iid.ciirc.cvut.cz/ros
extra-trusted-public-keys = ros:JR95vUYsShSqfA1VTYoFt1Nz6uXasm5QrcOsGry9f6Q=

常见问题

问：为什么某些软件包因 _unresolved_<dependency> 参数而评估失败？

A: 如果包在评估时出现如下错误：

error: evaluation aborted with the following error message:
'lib.customisation.callPackageWith: Function called without required
argument "_unresolved_<dependency>" at /.../nix-ros-overlay/distros/<distro>/<package>/default.nix:5'

这意味着包 <dependency> 在 rosdep YAML 文件中缺少 nixos 键。在某些情况下，只需在 nixpkgs 中找到对应的包并提交一个添加 rosdep 条目的 PR 即可。如果该包没有 Nix 表达式，你应该尝试将其打包并提交到 nixpkgs 上游。在某些情况下，可能适合将该包添加到本 overlay 中，但应尽量避免这样做。

Q: 为什么有些包构建失败？

ROS 包有成千上万个，因此确保每个包都能构建是不可行的。我通常的目标是保持发行版中至少 80-90% 的包能够成功构建，但随着发行版变旧并与较新的软件产生不兼容性，这一比例往往会下降。如果你需要的包无法构建，请提交一个 issue 或尝试自行修复。在许多情况下，构建失败是由于包本身的 bug 引起的，应在上游修复。在其他情况下，可能需要在本 overlay 中添加覆盖以修复自动生成的表达式。

Q: 我可以更新 overlay 以匹配最新的 ROS 吗？

该 overlay 大约每几周通过半自动方式更新一次。如果你想尝试更新版本的 ROS，你可以从仓库根目录运行以下命令，在本地更新整个 overlay：

nix flake update rosdistro
nix run .#update-overlay

它需要从所有发行版下载所有 ROS 包的源码 tarball，这可能需要很长时间。如果你只对某个特定发行版感兴趣，可以在命令行中指定 superflore 参数。例如，以下命令仅更新 jazzy 发行版：

nix run .#update-overlay -- --dry-run --output-repository-path . --tar-archive-dir .tar --no-branch --ros-distro jazzy

您也可以从 rosdistro 仓库的自定义版本重新生成 overlay：

nix run .#update-overlay --override-input rosdistro /path/to/local/rosdistro

Q: 你们是否提供 ROS 1 或 Gazebo Classic 的软件包？

在 Gazebo Classic 和 ROS 1 分别于 2025 年 1 月和 5 月到达生命周期终点（End-of-Life）后，我们已将它们从 master 和 develop 分支中移除。不过，你仍然可以在 ros1-25.05 分支中访问它们，该分支是基于 nixpkgs 的 nixos-25.05 分支构建的。我们至少会接受针对该分支的 PR 直到 2025 年底。如果你需要某个编译失败的 ROS 1 软件包，或许值得查看一下 ROS-O GitHub 组织是否为其提供了一些补丁。