Ramon Roche 9adda29da2
docs(sim): add Try PX4 quick-start and pre-built packages reference (#26957)
Adds documentation for the SITL containers and .deb packages introduced in #26495. The containers are now live on Docker Hub: [`px4io/px4-sitl:latest`](https://hub.docker.com/r/px4io/px4-sitl) and [`px4io/px4-sitl-gazebo:latest`](https://hub.docker.com/r/px4io/px4-sitl-gazebo).

The main addition is a [Try PX4 Simulation](https://docs.px4.io/main/en/dev_setup/try_px4) page that leads with a single `docker run` command and gets someone flying in under a minute. It lives in Getting Started, right after Recommended Hardware/Setup, so it's one of the first things new users see.

The existing `.deb` package reference has been moved from `packaging/px4_sitl_deb.md` to `simulation/px4_sitl.md` and expanded to cover both containers and `.deb` packages on one page. Sections are ordered by how people use them: what's available, install, configure, connect QGC/MAVSDK, connect ROS 2.

Other changes:
- README now has a "Try PX4" section with the docker one-liner above "Build from Source"
- Landing page (`index.md`) reworked to lead with "Try PX4" before "For Developers"
- Toolchain page (`dev_env.md`) gets a tip redirecting simulation-only users to pre-built packages
- `getting_started.md` and `SUMMARY.md` updated with links to the new pages
- Simulation index tip updated to mention containers alongside `.deb` packages

The SIH container image is published as `px4io/px4-sitl` (renamed from `px4io/px4-sitl-sih`) so the default lightweight option carries the simplest name. The Gazebo image remains `px4io/px4-sitl-gazebo`.

Also upgrades all GitHub Actions in the SITL workflow to Node.js 24 compatible versions (`actions/checkout@v6`, `actions/cache@v5`, `actions/upload-artifact@v7`, `actions/download-artifact@v8`, `docker/setup-buildx-action@v4`, `docker/build-push-action@v7`) to fix the Node.js 20 deprecation warning ahead of the June 2026 deadline.

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
2026-04-09 08:51:22 -07:00

116 lines
4.0 KiB
YAML

name: Build PX4 .deb Package
description: Build PX4 SITL, run cpack, validate the .deb, and upload artifact
inputs:
target:
description: 'Build target: default or sih'
required: true
artifact-name:
description: Name for the uploaded artifact
required: true
ccache-key-prefix:
description: Prefix for ccache cache keys
default: deb-ccache
ccache-max-size:
description: Maximum ccache size
default: 400M
runs:
using: composite
steps:
- name: Restore ccache
id: ccache-restore
uses: actions/cache/restore@v5
with:
path: ~/.ccache
key: ${{ inputs.ccache-key-prefix }}-${{ github.ref_name }}-${{ github.sha }}
restore-keys: |
${{ inputs.ccache-key-prefix }}-${{ github.ref_name }}-
${{ inputs.ccache-key-prefix }}-${{ github.base_ref || 'main' }}-
${{ inputs.ccache-key-prefix }}-
- name: Configure ccache
shell: bash
run: |
mkdir -p ~/.ccache
echo "base_dir = ${GITHUB_WORKSPACE}" > ~/.ccache/ccache.conf
echo "compression = true" >> ~/.ccache/ccache.conf
echo "compression_level = 6" >> ~/.ccache/ccache.conf
echo "max_size = ${{ inputs.ccache-max-size }}" >> ~/.ccache/ccache.conf
echo "hash_dir = false" >> ~/.ccache/ccache.conf
echo "compiler_check = content" >> ~/.ccache/ccache.conf
ccache -s
ccache -z
- name: Build PX4 SITL
shell: bash
run: make px4_sitl_${{ inputs.target }}
- name: ccache stats
if: always()
shell: bash
run: ccache -s
- name: Save ccache
uses: actions/cache/save@v5
if: always()
with:
path: ~/.ccache
key: ${{ inputs.ccache-key-prefix }}-${{ github.ref_name }}-${{ github.sha }}
- name: Build .deb package
shell: bash
run: |
cd build/px4_sitl_${{ inputs.target }}
cpack -G DEB
- name: Print package info and contents
shell: bash
run: |
cd build/px4_sitl_${{ inputs.target }}
echo "--- Package info ---"
dpkg-deb -I *.deb
echo "--- Package contents ---"
dpkg-deb -c *.deb
- name: Validate sih package
if: inputs.target == 'sih'
shell: bash
run: |
cd build/px4_sitl_sih
echo "--- Verify NO Gazebo resources ---"
! dpkg-deb -c px4_*.deb | grep share/gz > /dev/null && echo "PASS: no Gazebo" || { echo "FAIL: Gazebo found"; exit 1; }
echo "--- Install test ---"
dpkg -i px4_*.deb
test -x /opt/px4/bin/px4 || { echo "FAIL: px4 binary not found"; exit 1; }
test -L /usr/bin/px4 || { echo "FAIL: symlink not created"; exit 1; }
test ! -d /opt/px4/share/gz || { echo "FAIL: Gazebo dir should not exist"; exit 1; }
echo "--- Smoke test ---"
/opt/px4/bin/px4 -h
echo "PASS: sih package validation successful"
- name: Validate gazebo package
if: inputs.target == 'default'
shell: bash
run: |
cd build/px4_sitl_default
echo "--- Verify Gazebo resources in package ---"
dpkg-deb -c px4-gazebo_*.deb | grep share/gz/models > /dev/null || { echo "FAIL: models missing"; exit 1; }
dpkg-deb -c px4-gazebo_*.deb | grep share/gz/worlds > /dev/null || { echo "FAIL: worlds missing"; exit 1; }
echo "--- Install test ---"
dpkg -i px4-gazebo_*.deb
test -x /opt/px4-gazebo/bin/px4 || { echo "FAIL: px4 binary not found"; exit 1; }
test -x /opt/px4-gazebo/bin/px4-gazebo || { echo "FAIL: wrapper not found"; exit 1; }
test -L /usr/bin/px4-gazebo || { echo "FAIL: symlink not created"; exit 1; }
test -d /opt/px4-gazebo/share/gz/models || { echo "FAIL: Gazebo models not installed"; exit 1; }
echo "--- Smoke test ---"
/opt/px4-gazebo/bin/px4 -h
echo "PASS: gazebo package validation successful"
- name: Upload .deb artifacts
uses: actions/upload-artifact@v7
with:
name: ${{ inputs.artifact-name }}
path: build/px4_sitl_${{ inputs.target }}/*.deb
if-no-files-found: error