构建系统

相关源文件

• .github/ISSUE_TEMPLATE/pc_bug_report.yml
• .github/workflows/auto-cache/action.yaml
• .github/workflows/badges.yaml
• .github/workflows/compile-openpilot/action.yaml
• .github/workflows/prebuilt.yaml
• .github/workflows/release.yaml
• .github/workflows/selfdrive_tests.yaml
• .github/workflows/setup-with-retry/action.yaml
• .github/workflows/setup/action.yaml
• .github/workflows/stale.yaml
• .gitignore
• Dockerfile.openpilot_base
• pyproject.toml
• selfdrive/debug/dump.py
• selfdrive/test/docker_build.sh
• selfdrive/test/docker_common.sh
• tools/install_python_dependencies.sh
• tools/install_ubuntu_dependencies.sh
• tools/mac_setup.sh
• tools/ubuntu_setup.sh

本页面介绍如何从源代码构建 openpilot，并提供有关构建系统架构的详细信息。有关测试信息，请参阅 测试框架。有关日志记录和数据分析工具，请参阅 数据日志记录与分析。

概述

openpilot 构建系统使用 SCons 作为其主要构建工具，并辅以一套支持脚本和 Docker 配置，以实现跨不同环境的一致构建。它提供了依赖管理、C/C++ 组件编译以及与持续集成管道集成的机制。

来源：pyproject.toml tools/ubuntu_setup.sh .github/workflows/selfdrive_tests.yaml selfdrive/test/docker_build.sh

设置和依赖

在构建 openpilot 之前，您需要设置包含所有必需依赖项的开发环境。

环境设置脚本

openpilot 为不同的操作系统提供了自动设置脚本

操作系统	设置脚本	描述
Ubuntu/Debian	tools/ubuntu_setup.sh	安装系统依赖项和 Python 包
macOS	tools/mac_setup.sh	使用 Homebrew 安装依赖项并设置 Python 环境

这两个设置脚本最终都调用 tools/install_python_dependencies.sh，它使用 uv（一个 Python 包管理器）来安装 pyproject.toml 中定义的依赖项。

来源：tools/ubuntu_setup.sh tools/mac_setup.sh tools/install_ubuntu_dependencies.sh tools/install_python_dependencies.sh

Ubuntu 依赖项

对于 Ubuntu（以及基于 Debian 的系统），设置脚本会安装必要的构建工具和库

来源：tools/install_ubuntu_dependencies.sh21-66

macOS 依赖项

对于 macOS，设置脚本使用 Homebrew 安装必需的软件包

来源：tools/mac_setup.sh35-53

Python依赖项

Python 依赖项通过 pyproject.toml 进行管理，并使用 uv 进行安装

主要的 Python 依赖项包括

类别	关键依赖项
核心	pycapnp, numpy, scons, Cython
测试	pytest, coverage, hypothesis
开发	matplotlib, pygame, av

来源：pyproject.toml tools/install_python_dependencies.sh22-24

使用 SCons 构建

openpilot 使用基于 Python 的构建系统 SCons 来编译其 C/C++ 组件。

基本构建

设置好环境后，您可以使用 SCons 构建 openpilot

SCons 缓存

SCons 使用缓存来加速增量构建。此缓存存储在不同的位置

• 在 CI 中：.ci_cache/scons_cache 或 /tmp/scons_cache
• 本地开发：通常在存储库根目录

清理并重新填充缓存（有助于故障排除）

来源：.github/workflows/compile-openpilot/action.yaml13-15 .github/workflows/selfdrive_tests.yaml28

基于 Docker 的构建

openpilot 提供 Docker 配置，用于在不同环境中进行可复现的构建。

来源：selfdrive/test/docker_build.sh selfdrive/test/docker_common.sh Dockerfile.openpilot_base

基础镜像

基础 Docker 镜像（openpilot-base）包含构建 openpilot 所需的所有依赖项

基础镜像定义在 Dockerfile.openpilot_base 中，包括

• Ubuntu 24.04 作为基础操作系统
• 构建 openpilot 的所有系统依赖项
• OpenCL 支持，用于硬件加速
• 预配置的 Python 环境

来源：Dockerfile.openpilot_base selfdrive/test/docker_common.sh1-10

使用 Docker 构建

使用 Docker 构建 openpilot

这种方法确保了不同开发环境之间的一致性。

来源：.github/workflows/selfdrive_tests.yaml28

持续集成

openpilot 使用 GitHub Actions 进行持续集成和测试。

来源：.github/workflows/selfdrive_tests.yaml .github/workflows/release.yaml

关键 CI 工作流

主要 CI 工作流包括

工作流	目的	关键操作
selfdrive_tests	主要测试工作流	构建代码、运行测试、检查代码质量
release	创建发布	构建生产就绪的工件，创建标签
prebuilt	构建 Docker 镜像	创建并发布预构建的 Docker 镜像

CI 系统使用多种优化策略

• 缓存 SCons 构建工件以加速构建
• 缓存下载的依赖项
• 将测试并行化到多个作业

来源： .github/workflows/selfdrive_tests.yaml32-359 .github/workflows/release.yaml1-55 .github/workflows/prebuilt.yaml1-40

构建工件

构建过程产生几种类型的构件

1. 二进制可执行文件和库:

   • 位于存储库中的各种目录中
   • 由SCons编译的C/C++组件

2. Python模块:

   • Python文件和编译的扩展

3. Docker 镜像:

   • openpilot-base：包含所有依赖项的基础镜像
   • openpilot-prebuilt：包含预编译openpilot二进制文件的镜像

构建问题故障排除

常见的构建问题及解决方案

1. 缺少依赖项:

   • 运行适合您操作系统的相应设置脚本
   • 对于Ubuntu：tools/ubuntu_setup.sh
   • 对于macOS：tools/mac_setup.sh

2. SCons缓存问题:

   • 清除缓存并重新构建

3. Docker构建问题:

   • 确保Docker已安装并正在运行
   • 尝试拉取最新的基础镜像

4. Python环境问题:

   • 重置您的Python环境

来源： .github/workflows/compile-openpilot/action.yaml tools/install_python_dependencies.sh

构建系统架构

以下图表显示了构建系统不同组件之间的交互方式

来源： .github/workflows/selfdrive_tests.yaml pyproject.toml Dockerfile.openpilot_base

结论

openpilot构建系统结合了SCons、Docker和GitHub Actions，为跨不同环境构建项目提供了一种健壮且灵活的方式。该系统旨在实现可复现性，确保开发、测试和部署的一致性构建。

开始构建openpilot

1. 使用适当的设置脚本设置开发环境
2. 安装依赖项
3. 运行SCons以构建项目
4. 或者，使用Docker来获得一致的构建环境

有关开发的高级主题，请参阅测试框架和开发工具页面。