Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-05-29 19:57:12 +08:00
Code Issues Actions 14 Packages Projects Releases Wiki Activity

New Crowdin translations - zh-CN (#26488)

Browse Source 
Co-authored-by: Crowdin Bot <support+bot@crowdin.com>
This commit is contained in:
PX4 Build Bot
2026-02-18 16:44:34 +11:00
committed by GitHub
parent 7ef57f6262
commit 47d5971f42
314 changed files with 11960 additions and 1374 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/zh/test_and_ci/continous_integration.md
+192 -1
View File
@@ -1,3 +1,194 @@
# PX4 持续集成
PX4 构建和测试分布在多个持续集成服务上。
PX4 uses GitHub Actions for continuous integration, with different workflows handling code builds, testing, and documentation.
## Documentation CI
The documentation pipeline handles building, deploying, and translating the PX4 User Guide.
All documentation CI is consolidated into a single orchestrator workflow organized in tiers.
### Docs Orchestrator
**Workflow file:** [`docs-orchestrator.yml`](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/docs-orchestrator.yml)
This is the main documentation workflow. It runs on pull requests, pushes to `main` and `release/**` branches, and manual `workflow_dispatch` triggers, performing different jobs depending on the trigger event.
Jobs are organized in tiers, where each tier depends on the previous one completing successfully.
#### Tier Structure
| Tier | Job | PR | Push / Dispatch | 描述 |
| ---- | -------------- | ----------------------------------------------- | --------------------------------- | -------------------------------------------------------------------------------- |
| T1 | Detect Changes | Yes | — | Checks if source code files changed (triggers metadata regen) |
| T2 | PR Metadata | Yes (conditional) | — | Builds PX4 SITL and regenerates all auto-generated docs |
| T2 | Metadata Sync | — | Yes | Builds PX4 SITL, regenerates metadata, auto-commits |
| T2 | Link Check | Yes | — | Checks for broken links in changed files, posts PR comment |
| T3 | Build Site | Yes (if docs/source changed) | Yes (after T2) | Builds the VitePress documentation site |
| T4 | Deploy | — | Yes | Deploys to AWS S3 |
#### Pull Request Flow
When a PR modifies files in `docs/**` or the orchestrator workflow file itself, the workflow validates the changes:
```txt
PR Event
│
▼
┌─────────────────────────────────────┐
│ T1: Detect Changes │
│ • Checks if src/msg/ROMFS changed │
└─────────────────┬───────────────────┘
│
┌───────┴───────┐
▼ ▼
┌──────────────────┐ ┌─────────────────────────┐
│ T2: PR Metadata │ │ T2: Link Check (~30s) │
│ (conditional) │ │ • Detects changed .md │
│ • Builds SITL │ │ • Runs filtered check │
│ • Generates │ │ • Posts PR comment │
│ metadata │ │ • Runs full check │
│ • Builds │ └────────────┬────────────┘
│ failsafe web │ │
└────────┬─────────┘ │
└───────────┬────────────┘
▼
┌─────────────────────────────────────┐
│ T3: Build Site (~7-10 min) │
│ (skipped if only workflow YAML │
│ changed — no docs/source changes) │
│ • Builds VitePress site │
│ • Verifies no build errors │
└─────────────────┬───────────────────┘
│
▼
DONE
```
| Job | Duration | 描述 |
| -------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **T1: Detect Changes** | ~10s | Determines if metadata regeneration is needed |
| **T2: PR Metadata** | ~10-15m | Rebuilds PX4 SITL and regenerates all metadata (only if source files changed) |
| **T2: Link Check** | ~30s | Checks for broken links in changed markdown files and posts a sticky comment to the PR (skipped on fork PRs) |
| **T3: Build Site** | ~7-10m | Builds the VitePress site to verify there are no build errors. Skipped when only the workflow YAML changed (no docs or source changes). |
#### Push / Dispatch Flow (main/release branches)
When changes are pushed to `main` or `release/**` branches (or a `workflow_dispatch` is triggered), the workflow regenerates metadata, builds, and deploys.
Only `main` and `release/*` branches are accepted for deploy — other branches will fail with a clear error.
```txt
Push / Dispatch Event
│
▼
┌─────────────────────────────────────┐
│ T2: Metadata Sync (~10-15 min) │
│ • Builds px4_sitl_default │
│ • Generates parameter/airframe/ │
│ module documentation │
│ • Builds failsafe web simulator │
│ • Formats with Prettier │
│ • Auto-commits if changes detected │
│ (with [skip ci]) │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ T3: Build Site (~7-10 min) │
│ • Builds VitePress site │
│ • Uploads build artifact │
└─────────────────┬───────────────────┘
│
▼
┌─────────────────────────────────────┐
│ T4: Deploy (~3 min) │
│ • Syncs to AWS S3 │
│ • HTML: 60s cache │
│ • Assets: 24h immutable cache │
└─────────────────────────────────────┘
```
| Job | Duration | 描述 |
| ------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **T2: Metadata Sync** | ~10-15m | Rebuilds PX4 SITL, regenerates all metadata, formats with Prettier, auto-commits with `[skip ci]` |
| **T3: Build Site** | ~7-10m | Builds the VitePress documentation site |
| **T4: Deploy** | ~3m | Syncs built site to AWS S3 (HTML: 60s cache, assets: 24h cache) |
Crowdin upload is handled by a separate workflow (see below).
#### Generated Metadata
The metadata regeneration job creates the following auto-generated documentation:
| 类型 | 输出 | 描述 |
| ------------------ | ------------------------------------------------ | --------------------------------------------------------------- |
| 参数 | `docs/en/advanced_config/parameter_reference.md` | Complete parameter reference |
| 机型 | `docs/en/airframes/airframe_reference.md` | Airframe configurations |
| Modules | `docs/en/modules/*.md` | Module documentation |
| Messages | `docs/en/msg_docs/*.md` | uORB message documentation |
| uORB Graphs | `docs/public/middleware/*.json` | Topic dependency graphs |
| Failsafe Simulator | `docs/public/config/failsafe/*` | Interactive failsafe simulator (WebAssembly) |
:::warning
Do not manually edit the auto-generated files listed above. They are overwritten on every push to main.
:::
#### Path Triggers
The workflow triggers on different paths depending on the event:
**Push** (main/release branches):
| Path | Reason |
| ------------------------ | ------------------------------------- |
| `docs/**` | Documentation source files |
| `src/**` | Source code changes affect metadata |
| `msg/**` | Message definitions affect metadata |
| `ROMFS/**` | ROMFS files affect metadata |
| `Tools/module_config/**` | Module configuration affects metadata |
**Pull Request:**
| Path | Reason |
| ----------------------------------------- | ------------------------------ |
| `docs/**` | Documentation source files |
| `.github/workflows/docs-orchestrator.yml` | Changes to the workflow itself |
Source-only changes on PRs are detected at runtime by the T1: Detect Changes job using [dorny/paths-filter](https://github.com/dorny/paths-filter), which conditionally triggers the T2: PR Metadata job.
### Crowdin Download Workflow
**Workflow file:** [`docs_crowdin_download.yml`](https://github.com/PX4/PX4-Autopilot/blob/main/.github/workflows/docs_crowdin_download.yml)
This scheduled workflow downloads completed translations from Crowdin and creates pull requests.
| 设置 | 值 |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Schedule** | Every Sunday at 00:00 UTC |
| **Target Languages** | Korean (ko), Ukrainian (uk), Chinese Simplified (zh-CN) |
**Process:**
1. Downloads translations for each target language from Crowdin
2. Creates a separate PR for each language with new translations
3. PRs are labeled "Documentation" and assigned for review
### Caching Strategy
The workflows use caching to speed up builds:
| Cache | Size | Purpose |
| --------------------------------- | --------------------- | -------------------------------------------------- |
| ccache | 1GB | C++ compilation cache for SITL builds |
| node_modules | ~26MB | Node.js dependencies for VitePress |
### Infrastructure
Jobs run on [runs-on](https://runs-on.com/) self-hosted runners with S3 cache:
| Job | Runner |
| ---------------------------------- | ------------------------------------------------- |
| T1: Detect Changes | ubuntu-latest |
| T2: PR Metadata | 4 CPU (with px4-dev container) |
| T2: Metadata Sync | 4 CPU (with px4-dev container) |
| T2: Link Check | ubuntu-latest |
| T3: Build Site | 4 CPU |
| T4: Deploy | ubuntu-latest |
docs/zh/test_and_ci/docker.md
+29 -27
View File
@@ -1,12 +1,11 @@
# PX4 Docker 容器
Docker containers are provided for the complete [PX4 development toolchain](../dev_setup/dev_env.md#supported-targets) including NuttX and Linux based hardware, [Gazebo Classic](../sim_gazebo_classic/index.md) simulation, and [ROS](../simulation/ros_interface.md).
Docker containers are provided for the complete [PX4 development toolchain](../dev_setup/dev_env.md#supported-targets) including NuttX and Linux based hardware, [Gazebo](../sim_gazebo_gz/index.md) simulation, and [ROS 2](../ros2/user_guide.md).
This topic shows how to use the [available docker containers](#px4_containers) to access the build environment in a local Linux computer.
:::info
Dockerfiles and README can be found on [Github here](https://github.com/PX4/PX4-containers/tree/master?tab=readme-ov-file#container-hierarchy).
They are built automatically on [Docker Hub](https://hub.docker.com/u/px4io/).
The recommended `px4-dev` container is built from the [Dockerfile in the PX4-Autopilot source tree](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/Dockerfile) by the [Container build workflow](https://github.com/PX4/PX4-Autopilot/actions/workflows/dev_container.yml).
:::
## 系统必备组件
@@ -35,33 +34,36 @@ sudo usermod -aG docker $USER
# Log in/out again before using docker!
```
## Container Hierarchy {#px4_containers}
## px4-dev Container (Recommended) {#px4_containers}
The available containers are on [GitHub here](https://github.com/PX4/PX4-containers/tree/master?tab=readme-ov-file#container-hierarchy).
The **`px4-dev`** container is the recommended container for building PX4 firmware.
It is a single, multi-architecture container (linux/amd64 and linux/arm64) based on Ubuntu 24.04 that includes everything needed to build PX4 for NuttX hardware targets.
使用容器的最简单方法是通过 <a href="https://github.com/PX4/Firmware/blob/master/Tools/docker_run.sh">docker_run.sh</a> 帮助程序脚本。
The containers are hierarchical, such that containers have the functionality of their parents.
For example, the partial hierarchy below shows that the docker container with NuttX build tools (`px4-dev-nuttx-focal`) does not include ROS 2, while the simulation containers do:
It is published to both registries simultaneously:
```plain
- px4io/px4-dev-base-focal
- px4io/px4-dev-nuttx-focal
- px4io/px4-dev-simulation-focal
- px4io/px4-dev-ros-noetic
- px4io/px4-dev-ros2-foxy
- px4io/px4-dev-ros2-rolling
- px4io/px4-dev-base-jammy
- px4io/px4-dev-nuttx-jammy
```
- **GitHub Container Registry:** [ghcr.io/px4/px4-dev](https://github.com/PX4/PX4-Autopilot/pkgs/container/px4-dev)
- **Docker Hub:** [px4io/px4-dev](https://hub.docker.com/r/px4io/px4-dev)
The most recent version can be accessed using the `latest` tag: `px4io/px4-dev-nuttx-focal:latest`
(available tags are listed for each container on _hub.docker.com_.
For example, the `px4io/px4-dev-nuttx-focal` tags can be found on [hub.docker.com here](https://hub.docker.com/r/px4io/px4-dev-nuttx-focal/tags?page=1&ordering=last_updated)).
The container includes:
- Ubuntu 24.04 base
- ARM cross-compiler (`gcc-arm-none-eabi`) and Xtensa compiler (for ESP32 targets)
- Build tools: `cmake`, `ninja`, `ccache`, `make`
- Python 3 with PX4 build dependencies
- NuttX toolchain libraries (`libnewlib-arm-none-eabi`, etc.)
The container is built from the [Dockerfile](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/Dockerfile) in the PX4 source tree using the [Container build workflow](https://github.com/PX4/PX4-Autopilot/actions/workflows/dev_container.yml).
Images are tagged with the PX4 version (e.g. `px4io/px4-dev:v1.16.0`).
:::tip
Typically you should use a recent container, but not necessarily the `latest` (as this changes too often).
A `px4-sim` container with simulation tools (Gazebo Harmonic) is planned to complement `px4-dev` for simulation workflows.
:::
### Legacy Containers
The older per-distro containers from [PX4/PX4-containers](https://github.com/PX4/PX4-containers) (e.g. `px4-dev-nuttx-jammy`, `px4-dev-ros2-humble`, etc.) are no longer recommended.
They will be replaced by `px4-dev` (for builds) and the upcoming `px4-sim` (for simulation).
## 使用 Docker 容器
典型命令的语法如下所示。
@@ -121,7 +123,7 @@ Where,
- `<host_src>`: The host computer directory to be mapped to `<container_src>` in the container. This should normally be the **PX4-Autopilot** directory.
- `<container_src>`: The location of the shared (source) directory when inside the container.
- `<local_container_name>`: A name for the docker container being created. This can later be used if we need to reference the container again.
- `<container>:<tag>`: The container with version tag to start - e.g.: `px4io/px4-dev-ros:2017-10-23`.
- `<container>:<tag>`: The container with version tag to start - e.g.: `px4io/px4-dev:v1.16.0`.
- `<build_command>`: The command to invoke on the new container. E.g. `bash` is used to open a bash shell in the container.
The concrete example below shows how to open a bash shell and share the directory **~/src/PX4-Autopilot** on the host computer.
@@ -137,7 +139,7 @@ docker run -it --privileged \
-v /tmp/.X11-unix:/tmp/.X11-unix:ro \
-e DISPLAY=:0 \
--network host \
--name=px4-ros px4io/px4-dev-ros2-foxy:2022-07-31 bash
--name=px4-dev px4io/px4-dev:v1.16.0 bash
```
:::info
@@ -154,7 +156,7 @@ On other hosts you might iterate the value of `0` in `-e DISPLAY=:0` until the "
```sh
cd src/PX4-Autopilot #This is <container_src>
make px4_sitl_default gazebo-classic
make px4_sitl gz_x500
```
### 重新进入容器
@@ -218,7 +220,7 @@ This ensures that all files created within the container will be accessible on t
#### 图形驱动问题
It's possible that running Gazebo Classic will result in a similar error message like the following:
It's possible that running Gazebo will result in a similar error message like the following:
```sh
libGL error: failed to load driver: swrast
@@ -238,7 +240,7 @@ For Nvidia drivers the following command should be used (otherwise the installer
The following configuration is tested:
- OS X with VMWare Fusion and Ubuntu 14.04 (Docker container with GUI support on Parallels make the X-Server crash).
- OS X with VMWare Fusion and Ubuntu 22.04 (Docker container with GUI support on Parallels make the X-Server crash).
**Memory**