mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-07-27 00:48:23 +08:00

Files

Ramon Roche a6d1822521 build(macos): inline homebrew deps in setup script, drop px4-dev meta-formula

Homebrew 4.5 (April 2026) stopped auto-tapping cross-tap
dependencies declared in formulae, as a security + performance
change. The px4-dev meta-formula pulled in packages from
osx-cross/arm, PX4/px4, and discoteq/discoteq, so 'brew install
px4-dev' now aborts before any real work unless every tap has been
added explicitly. On macos-latest CI runners the chain broke at the
first unreachable dep (discoteq/discoteq/flock) and subsequent make
steps failed with 'ccache: command not found'.

Since Tools/setup/macos.sh is the canonical install path and already
tapped osx-cross/arm and PX4/px4 before calling brew install, the
simplest fix is to inline the package list and call brew install
directly. The px4-dev meta-formula will be kept upstream as a
deprecated no-op so older copies of macos.sh on long-lived branches
and cached Docker images keep working.

The inlined package list is the same set px4-dev depended on, minus
the dead-weight flock dependency that hadn't been invoked in the PX4
build since the NuttX 9.1.x era. See the accompanying PX4/homebrew-px4
PR for formula changes.

Docs updated to match: docs/en/dev_setup/dev_env_mac.md no longer
names the px4-dev formula, describes the package list directly.

Verified locally on macOS ARM64:
- ./Tools/setup/macos.sh runs to completion with both taps and all 13
  packages resolving correctly
- make distclean && make px4_fmu-v6x_default builds successfully
  (1250/1250 ninja steps, 1930096 B FLASH used)

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

2026-04-18 13:04:26 -07:00

4.2 KiB

Raw Blame History

macOS Development Environment

The following instructions set up a PX4 development environment on macOS. This environment can be used to build PX4 for:

Pixhawk and other NuttX-based hardware
Gazebo Simulation (Gazebo Harmonic)

It works on both Intel and Apple Silicon Macs.

:::tip This setup is supported by the PX4 dev team. To build for other targets you will need to use a different OS or an unsupported development environment. :::

Development Environment Setup

Prerequisites

Install Xcode Command Line Tools — provides git, make, and the Apple clang compiler:
```
xcode-select --install
```
Install Homebrew by following the installation instructions.
Increase the open-file limit. The PX4 build opens many files simultaneously and the macOS default limit (256) is too low — you may see "LD: too many open files" errors without this.

Add the following line to your shell startup file so it applies to every new terminal session. macOS defaults to zsh since Catalina, so add it to ~/.zshrc (use ~/.bashrc if you use bash):
```
echo "ulimit -S -n 2048" >> ~/.zshrc
```
Then open a new terminal (or run source ~/.zshrc) for the change to take effect.
Ensure Python 3 is available. Some PX4 build scripts require python3 and pip3 to be in your PATH. The Xcode Command Line Tools include Python 3 by default.

:::tip If you need to install or manage a different Python version, we recommend pyenv, which lets you set global and per-directory Python versions. :::

Install Development Tools

Download PX4 Source Code:

git clone https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot
git submodule update --init --recursive --force

Install development environment libraries from the macos.sh helper script:
```
./Tools/setup/macos.sh --sim-tools
```
This installs:
- Toolchain packages from the osx-cross/arm and PX4/px4 Homebrew taps — ARM cross-compiler (arm-gcc-bin@13), cmake, ninja, ccache, fastdds, genromfs, kconfig-frontends, and other build tools
- Python packages from requirements.txt
- px4-sim (via --sim-tools) — Gazebo Harmonic simulation (gz-harmonic) and related tools
::: info Omit --sim-tools if you only need to build for NuttX hardware and don't need simulation.

Use --reinstall to force reinstallation of all Homebrew formulas (useful if something is broken). :::

Gazebo Simulation

The --sim-tools flag installs the px4-sim Homebrew formula, which pulls in Gazebo Harmonic.

If you skipped --sim-tools during initial setup and want to add simulation later:

brew tap PX4/px4
brew install px4-sim

::: info Gazebo requires XQuartz for display on macOS. If you don't already have it installed:

brew install --cask xquartz

You may need to log out and back in after installing XQuartz. :::

Verify Installation

After installation, verify the key tools are available:

# NuttX cross-compiler (from arm-gcc-bin@13)
arm-none-eabi-gcc --version

# Build tools
cmake --version
ninja --version

# Gazebo (if --sim-tools was used)
gz sim --versions

Quick smoke test — build and run a simulation target:

make px4_sitl gz_x500

If everything is set up correctly, this will build PX4 SITL and launch a Gazebo simulation with the x500 quadcopter.

Next Steps

Once you have finished setting up the command-line toolchain:

Install VSCode (if you prefer using an IDE to the command line).
Install the QGroundControl Daily Build

::: tip The daily build includes development tools that are hidden in release builds. It may also provide access to new PX4 features that are not yet supported in release builds. :::
Continue to the build instructions.

4.2 KiB Raw Blame History