build(packaging): add SITL .deb packages and Docker runtime images

[mrpollo]

Adds .deb packaging and Docker runtime images for PX4 SITL, enabling zero-setup simulation on Linux, macOS, and Windows. Two .deb packages are produced: px4 (SIH physics only, no external dependencies) and px4-gazebo (full Gazebo Harmonic simulation resources). Both install to /opt with wrapper scripts and postinst/postrm maintainer scripts.

Two Docker runtime images consume these .deb packages:

• px4io/px4-sitl-sih (107MB): stripped PX4 binary on ubuntu:24.04 with just bc for rcS math. Runs the SIH physics engine headless with no simulator dependencies.
• px4io/px4-sitl-gazebo (2.2GB): ubuntu:24.04 with Gazebo Harmonic installed from OSRF repos. Includes PX4 models, worlds, and plugins.

A platform-adaptive entrypoint script detects Docker Desktop (macOS/Windows) via host.docker.internal and patches MAVLink targets (-t flag) and uXRCE-DDS agent address so UDP packets correctly reach the host through the Docker VM boundary. On Linux with --network host, the entrypoint is a no-op.

Verified on macOS Docker Desktop with port mapping: MAVSDK connected and flew a mission to 100m, mavsim-viewer rendered the vehicle, and the uXRCE-DDS agent received topics/publishers from the container.

A CI workflow (sitl_containers.yml) builds multi-arch images (amd64 + arm64) on git tags using native runners, publishes to Docker Hub and GHCR, and creates multi-arch manifests. It reuses the build-deb composite action and runs-on with S3 cache for ccache and apt packages.

[github-actions]

No broken links found in changed files.

[DronecodeBot]

This pull request has been mentioned on Discussion Forum for PX4, Pixhawk, QGroundControl, MAVSDK, MAVLink. There might be relevant details there:

https://discuss.px4.io/t/px4-dev-call-feb-18-2026-team-sync-and-community-q-a/48516/2

[hamishwillee]

Does this also work for SIH? I assume this must be done in separate command prompts?

Maybe something like:

Suggested change

	### Multi-Instance
	```bash
	PX4_SIM_MODEL=gz_x500 px4-sitl -i 0
	PX4_SIM_MODEL=gz_x500 px4-sitl -i 1
	```
	### Multi-Instance
	Multiple simulated vehicle instances can be started by passing the `-i` argument with an instance number.
	For example, to start an instance of a X500 Quad and a Cessna in Gazebo you could enter the following commands in separate command shells:
	```sh
	PX4_SIM_MODEL=gz_x500 px4-sitl -i 0
	```
	```sh
	PX4_SIM_MODEL=gz_rc_cessna px4-sitl -i 1
	```
	The instance number determines the UDP address for each vehicle in MAVLink.

What happens if I mix and match the different packages above?

[hamishwillee]

@mrpollo This feature is awesome, and this document is very succint. I am not however certain it is correctly positioned for audience.

In this section we're talking to people setting up their environment for the first time, they don't necessarily know what SITL, SIH, worlds, models, etc are.

The most important thing to present to them is "why this" - at the level of the reader. I suspect there are two reasons:

• To test ROS applications
• To just give simulation a go

Where it lives and how it is named depends on your answer to that question.

And depending on that answer it might be worth having two docs. I would be tempted to have a short intro doc that covers the minimum here:

This doc could then be linked and live in simulation.

Or even have an intro to this in the Ubuntu dev setup.

[mrpollo]

All great points, I am going to split the docs from this PR and will be pushing an augmented PR with tons of updates you are going to love ;)

[DronecodeBot]

This pull request has been mentioned on Discussion Forum for PX4, Pixhawk, QGroundControl, MAVSDK, MAVLink. There might be relevant details there:

https://discuss.px4.io/t/px4-dev-call-feb-25-2026-team-sync-and-community-q-a/48547/1

[Copilot]

Pull request overview

This PR adds support for creating Debian packages (.deb) for PX4 SITL simulation on Ubuntu, enabling users to run simulations without setting up a build environment.
The implementation provides two package variants: px4 (with SIH physics) and px4-gazebo (with Gazebo Harmonic), both installable via apt and supporting multi-instance launches, ROS 2 integration, and standard MAVLink/uXRCE-DDS interfaces.

Changes:

• CPack configuration for creating .deb packages with proper versioning, dependencies, and package metadata
• CMake install rules for SITL binaries, Gazebo resources, and ROMFS, with conditional logic to distinguish between .deb and legacy tarball workflows
• C++ code to auto-detect .deb installation and configure appropriate working directories using XDG standards
• Packaging scripts (wrapper, postinst/postrm) and GitHub Actions workflow for building and validating packages across Ubuntu 22.04/24.04 and amd64/arm64
• User documentation explaining installation, usage, and integration with external tools

Reviewed changes

Copilot reviewed 16 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
cmake/package.cmake	CPack configuration for generating .deb packages with version formatting, architecture detection, and package-specific metadata (px4 vs px4-gazebo)
platforms/posix/CMakeLists.txt	Conditional install rules: legacy tarball layout vs clean .deb layout, plus Gazebo resource installation
platforms/posix/src/px4/common/main.cpp	Auto-detection of .deb installation, XDG-based working directory setup, and mkdir_p helper for creating nested directories
src/modules/simulation/gz_plugins/optical_flow/CMakeLists.txt	RPATH configuration to enable plugin to find libOpticalFlow.so in same directory
Tools/packaging/px4-gazebo.sh	Wrapper script that sets Gazebo environment variables and creates missing dartsim symlink
Tools/packaging/postinst, postrm, sih/postinst, sih/postrm	Debian maintainer scripts for symlink creation/removal in /usr/bin
.github/workflows/build_deb_package.yml	CI workflow to build packages for Ubuntu 22.04/24.04, amd64/arm64, default/sih targets
.github/actions/build-deb/action.yml	Reusable action with ccache, build, validation steps for both package types
docs/en/packaging/px4_sitl_deb.md	User documentation covering installation, usage, multi-instance, ROS 2 integration, and build instructions
docs/en/simulation/index.md	Added tip pointing to .deb packages for users who don't want to build from source
docs/en/SUMMARY.md	Added link to new packaging documentation under Simulation section
boards/px4/sitl/sih.px4board	Board configuration disabling Gazebo modules for SIH-only package
.dockerignore	Excludes build/ directory from Docker context

Comments suppressed due to low confidence (1)

platforms/posix/src/px4/common/main.cpp:795

• The mkdir_p function does not handle paths with trailing slashes correctly. If path ends with '/', the final mkdir call at line 790 will attempt to create a directory with an empty final component. Consider stripping trailing slashes before processing: if (!path.empty() && path.back() == '/') { tmp = path.substr(0, path.size() - 1); }

static int mkdir_p(const std::string &path)
{
	std::string tmp = path;

	for (size_t i = 1; i < tmp.size(); ++i) {
		if (tmp[i] == '/') {
			tmp[i] = '\0';

			if (mkdir(tmp.c_str(), S_IRWXU | S_IRWXG | S_IRWXO) != 0 && errno != EEXIST) {
				return -1;
			}

			tmp[i] = '/';
		}
	}

	if (mkdir(tmp.c_str(), S_IRWXU | S_IRWXG | S_IRWXO) != 0 && errno != EEXIST) {
		return -1;
	}

	return 0;
}