夜雨聆风点击蓝字 关注我们
在AGIROS的日常开发与集成过程中，构建效率与依赖管理的复杂性一直是团队关注的重点。为此，这份《AGIROS Build 构建工具使用手册》，系统梳理了 AGIROS Build 核心命令、目录规范、补丁管理、常见标志解读以及加速构建的实用技巧，并额外提供与熟知的 Colcon Build 相结合的手段。无论你是刚接触AGIROS的新成员，还是正在优化构建流程的老朋友，希望本文能帮助你更高效地完成源码编译与打包工作。
一
环境准备
1. OS 环境
支持 Ubuntu / Docker / WSL 等操作系统环境。
已针对 WSL 做友好适配，部分打印输出中的文档链接已优化，可在cmd窗口中直接点击连接在 Windows 编辑器中打开 Linux 中的文件。
2. 在OS中创建Python环境
apt install -y python3.12-venv python3-full git-buildpackage \build-essential \python3-flake8 \python3-pytest-cov \python3-pip \python3-setuptools \pip git python3-yamlpython3 -m venv .venv && source .venv/bin/activatepip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
3. 确保正确配置软件源
使用 AGIROS 软件源，也可临时使用第三方源，常用源参考如下。
echo"deb https://mirrors.tuna.tsinghua.edu.cn/ros2/ubuntu/ noble main" | tee /etc/apt/sources.list.d/ros2.list && \apt-key adv --keyserver keyserver.ubuntu.com --recv-keys F42ED6FBAB17C654 && \apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys F42ED6FBAB17C654 && \apt install software-properties-common -y && add-apt-repository ppa:joseluisblancoc/mrpt-stable
4. 安装专用工具与集成
安装 AGIROS Build：
pip uninstall agirosbuild && rm ./agirosbuild-0.1.0-py3-none-any.whl && \wget https://gitee.com/frank152342/agirosbuild/raw/master/dist/agirosbuild-0.1.0-py3-none-any.whl && \pip install ./agirosbuild-0.1.0-py3-none-any.whl
与 Colcon Build 集成（可选）：
pip3 install colcon-common-extensionsagirosbuild integration --add-to-colcon
集成后可使用：
colcon build --packageonly [其他参数]二
agirosbuild packageonly 命令说明
1. 构建命令对比
2. AGIROS Build 源码目录结构
规范的目录结构为三级
work_dir / src / package-dir / 包内文件：
在包目录下执行agirosbuild packageonly等价于agirosbuild packageonly --packages-select 当前包。
3. Colcon Build 源码目录要求
colcon build 必须在 src 的上级目录下执行，不能在 src 内部执行（工具自身限制）。
执行后可能产生 build、install、log 等残留目录，这些目录对 agirosbuild 没有帮助，可安全删除。
src 目录中的 colcon build 残留文件应尽早清理。
4. 关键目录与文件说明
三
编译过程与技巧
1. 补丁应用：agirosbuild patch-apply
在 src 的上级目录下执行，或具体包代码中，会直接生效补丁。
补丁状态说明：
建议在应用补丁前先执行 agirosbuild patch-check 检查补丁状态。
2. 安装第三方私有包（示例）
apt install python3-vcstoolapt install python3-docutilsdpkg -i python3-catkin-pkg-modules_1.1.0-2_all.deb
如无法获取上述文件，可到 AGIROS 服务器或其他源获取。
3. 获取与解压源码
3.1 获取源码压缩包
根据实际情况从不同位置获取。
3.2 解压源码：agirosbuild tar-extract
将压缩包放入 src 目录，在 src 上级目录或 src 目录内执行解压。如果包源码集中放在其他目录（比如aaa）而非 src下，也可在该目录（比如aaa）下执行。
3.3 删除压缩包（可选）
解压后可删除原始压缩包以节省空间。后续如缺少依赖，可重新获取并解压。
4. 利用已有 deb 包加快构建
agirosbuild 和 colcon build 在构建前会检查源码对应的 deb 包是否存在。若存在，则视为已构建成功。
使用 --from-file 时，工具还会检查没有源码的 deb 包，按 order.txtdebs 顺序安装并归档到 debs 目录；若存在源码，则一并归档。
5. 启动 AGIROS 源码全量构建的一般流程
核心策略：先用 colcon build 构建基础包，再用 agirosbuild 构建剩余包。
5.1 优先构建三个基础包
export ROS_VERSION=2 && colcon build --packageonly --packages-select ament_package ament_cmake_core ros_workspace等价命令：
agirosbuild packageonly --packages-select ament_package ament_cmake_core ros_workspace
5.2 然后构建基础包（含依赖）
--packages-up-to 是 colcon build特有参数：
export ROS_VERSION=2 && colcon build --packageonly --packages-up-to ros_base
5.3 最后全量构建
在 src 上级目录执行：
agirosbuild packageonly
5.4 加速批量构建（可选）
agirosbuild packageonly --only-new可并行启动多个 bash 同时执行 agirosbuild。
工具会自动避开已编译的包，避免冲突。
未生成 .debuild 文件的源码会显示 [N] 标记。
5.5 人工值守场景（可选）
修改 bug 后重编已有包：
agirosbuild packageonly --skip-new# 或指定包agirosbuild packageonly --packages-select 包名
构建耗时较长的包（如 rclcpp、rviz-default-plugin），在源码目录下直接执行：
debuild -us -uc -b6. agirosbuild 提示信息详解
6.1 包名后的标志
6.2 tar 标志（一般无需关注）
构建时，如果需要压缩包存在，则工具会用tar命令自动压缩生成orig.tar.gz文件。
6.3 rules 标志
构建时，会检查rules文件，检查是否符合某些特定规则。
6.4 depends：解决AGIROS源码缺失的包
通过检查control文件，判断是否有三方包缺失，是否依赖其他agiros包，以及agiros包源码情况。
特征：如果出现报错depends=[x]，后面的agiros包名需要优先编译，[no_code]代表src目录下没有源码，需要补齐源码。
三方包缺失示例：
经查，发行Ubuntu版本升级后，要做三方包升级，如 libqt5core5a → libqt5core5t64，导致找不到，可更改control文件解决。
6.5 debuild 标志
6.6 build 文件与 kmsg 标志
build文件
点击 build 文件路径可直接打开（本机环境）。
带ctrl-c的不用关注，是用户临时终端的残留。
xx模块缺失
GitHub 访问失败处理示例（kmsg=[github]）：
debuild --> gz_fuel_tools_vendor > agiros-pixiu-gz-fuel-tools-vendor_0.0.6-1 tar=[skip] depends=[✓] debuild=[✗] /home/lifubing/ws/pixiu_arm/src/agiros-pixiu-gz-fuel-tools-vendor_0.0.6-1noble_arm64.build kmsg=[github ] (1.55 min)Failed <<< gz_fuel_tools_vendor [1min 33s, exited with code -2]Starting >>> gz_dartsim_vendordebuild --> gz_dartsim_vendor > agiros-pixiu-gz-dartsim-vendor_0.0.3-1 tar=[skip] depends=[✓] debuild=[✗] /home/lifubing/ws/pixiu_arm/src/agiros-pixiu-gz-dartsim-vendor_0.0.3-1noble_arm64.build kmsg=[github ] (2.77 min)
kmsg=[github] 标志代表Git 访问失败，可修改 CMakeLists.txt，优先检查本地已下载的 .tar.gz 包，解压后继续构建，无本地包时才走原有 Git 流程。也可配置proxy解决。
6.7 dpkg 扩展标志
dpkg=[x] 且无附加信息表示未知错误。
dpkg=[✓] [need depends: pydocstyle;] 代表安装时存在三方包缺失。而[ force-depends]代表忽略依赖强制安装上了，以便于不影响其他AGIROS包构建。
dpkg=[✓] 后面的信息，依赖的包未安装。
dpkg=[✓] 后面的信息，与其他包有目录冲突。
6.8 clearfile 标志
6.9 mvfile 标志
6.10 patchchk 标志
构建前会检查补丁状态。若构建失败，建议优先关注补丁状态。
四
其他常用命令
1. 补丁检查 agirosbuild patch-check
如果编译过程中检查出补丁文件，可先做补丁生效。
如下图：seriesBak，如果没有seriesBak，也没有seriesFile，则代表补丁已经生效过了。
2. 下载一级三方包 agirosbuild 3deb-incontrol
这里的一级三方包，是指 AGIROS 源码 control 文件 Depends 中的非 agiros 开头的 deb 包名。本工具扫描 src 源码，下载到本地或或安装三方包。
下载的 deb 会保存到 ./download/3-party目录。
3. 下载二级三方包 agirosbuild deb-in3deb-download
这里的二级三方包，是指已经下载的三方 deb 包，同时也依赖其他 deb 包，本工具将扫描 deb 提取其依赖信息，下载到本地。
扫描 ./download/3-party 中的deb包，下载这些 deb 依赖用到的其他 deb 到相同目录。
4. 压缩包解压 agirosbuild tar-extract
解压当前目录下的orig.tar.gz文件，通常在 src 或 debs 目录下执行。
5. 生成压缩包 agirosbuild tar-compress
当前目录下，压缩各个包子目录代码生成 origin.tar.gz 文件，通常在 src 或 debs 目录下执行。
6. 清理编译残留文件 agirosbuild clear-debuild-file
通常 debs 目录中不存在残留文件（工具已经自动处理了），src 会有残留，如下图。
当前目录下，清除各个包子目录代码 debuild 编译残留目录或文件，通常在 src 或 debs 目录下执行。
7. 安装deb包 agirosbuild install-debs
扫描 ./src 目录下的 deb 包，执行安装操作，并将安装成功的 deb 和代码移动到 ../debs 归档目录。
8. 显示依赖 agirosbuild show-depends
扫描 ./src 目录下未打包的源码，按不同维度显示依赖的 AGIROS 包，被依赖的 AGIROS 包，为调整打包顺序做支撑。
9. 显示重要文件链接 AGIROS Build show-files
当文件特别多时，可快速找到 build 文件和其他重要文件入口。
直接在包目录下执行，可减少输入包名等信息。
五
结语
构建工具是连接源码与可运行系统的重要桥梁。掌握 AGIROS Build 的设计思路与使用细节，在构建大量 AGIROS 包过程中，不仅能减少反复试错的时间成本，也能在面对依赖缺失、补丁冲突或网络异常时更从容地定位问题。随着AGIROS 生态的持续演进，我们也会不断优化工具链与文档，AGIROS build 对openEuler的支持预计将在今年下半年上线。如果你在实际使用中有任何疑问或改进建议，欢迎随时交流反馈。
联系邮箱：release@agiros.org.cn
