Mirrors_Framework/PX4-Autopilot
1
0
Fork 0
mirror of https://github.com/PX4/PX4-Autopilot.git synced 2026-06-01 11:06:04 +08:00
Code Issues Actions 18 Packages Projects Releases Wiki Activity

[Docs] macOS Dev environment installation (#25204)

Browse Source 
* Initial changes

* index fix

* gz index fix2

* gz index fix 3

* updates

* Run prettier

* zsh env
removed gz classic

* Corrections 2

* Cleanups

* Update docs/en/dev_setup/dev_env_mac.md

* Apply suggestions from code review

* Minor subedit and prettier

* small correction

* cleanups gz harmonic brew formula

* fix(macos.sh): invert px4-sim install condition for --sim-tools

The condition checked if px4-sim WAS installed before running
brew install, meaning it would never install on a fresh system.
Add the missing negation so it installs when NOT already present.

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

* docs: rewrite macOS dev environment setup guide

- Add Xcode Command Line Tools as prerequisite
- Default to ~/.zshrc (macOS default since Catalina)
- Explain why ulimit change is needed and why in startup file
- Add reminder to open new terminal after shell config changes
- Remove broken pip3 alias workaround
- Split git clone into clone + submodule update (canonical form)
- Recommend --sim-tools flag since first build uses gz_x500
- Document what macos.sh installs and its --reinstall flag
- Clarify Gazebo comes from --sim-tools / px4-sim formula
- Add XQuartz requirement for Gazebo display
- Add verification section with key tool checks and smoke test
- Remove outdated video guide comment block

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

* conventions

---------

Signed-off-by: Ramon Roche <mrpollo@gmail.com>
Co-authored-by: Hamish Willee <hamishwillee@gmail.com>
Co-authored-by: Ramon Roche <mrpollo@gmail.com>
This commit is contained in:
Farhang
2026-02-18 18:40:53 -05:00
committed by GitHub
parent 2ebfd40bba
commit eafb6c396b
2 changed files with 85 additions and 77 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Tools/setup/macos.sh
+1 -1
View File
@@ -74,7 +74,7 @@ python3 -m pip install --user -r ${DIR}/requirements.txt
# Optional, but recommended additional simulation tools: # Optional, but recommended additional simulation tools:
if [[ $INSTALL_SIM == "--sim-tools" ]]; then if [[ $INSTALL_SIM == "--sim-tools" ]]; then
if brew ls --versions px4-sim > /dev/null; then if ! brew ls --versions px4-sim > /dev/null; then
brew install px4-sim brew install px4-sim
elif [[ $REINSTALL_FORMULAS == "--reinstall" ]]; then elif [[ $REINSTALL_FORMULAS == "--reinstall" ]]; then
brew reinstall px4-sim brew reinstall px4-sim
docs/en/dev_setup/dev_env_mac.md
+84 -76
View File
@@ -1,111 +1,119 @@
# macOS Development Environment # macOS Development Environment
The following instructions set up a PX4 development environment for macOS. The following instructions set up a PX4 development environment on macOS.
This environment can be used to build PX4 for: This environment can be used to build PX4 for:
- Pixhawk and other NuttX-based hardware - Pixhawk and other NuttX-based hardware
- [Gazebo Classic Simulation](../sim_gazebo_classic/index.md) - [Gazebo Simulation](../sim_gazebo_gz/index.md) (Gazebo Harmonic)
It works on both Intel and Apple Silicon Macs.
:::tip :::tip
This setup is supported by the PX4 dev team. This setup is supported by the PX4 dev team.
To build other targets you will need to use a [different OS](../dev_setup/dev_env.md#supported-targets) (or an [unsupported development environment](../advanced/community_supported_dev_env.md)). To build for [other targets](../dev_setup/dev_env.md#supported-targets) you will need to use a [different OS](../dev_setup/dev_env.md#supported-targets) or an [unsupported development environment](../advanced/community_supported_dev_env.md).
::: :::
## Video Guide ## Development Environment Setup
<lite-youtube videoid="tMbMGiMs1cQ" title="Setting up your PX4 development environment on macOS"/> ### Prerequisites
## Base Setup 1. **Install Xcode Command Line Tools** — provides `git`, `make`, and the Apple `clang` compiler:
The "base" macOS setup installs the tools needed for building firmware, and includes the common tools that will be needed for installing/using the simulators.
### Environment Setup
:::details Apple Silicon MacBook users!
If you have an Apple M1, M2 etc. MacBook, make sure to run the terminal as x86 by setting up an x86 terminal:
1. Locate the Terminal application within the Utilities folder (**Finder > Go menu > Utilities**)
2. Select _Terminal.app_ and right-click on it, then choose **Duplicate**.
3. Rename the duplicated Terminal app, e.g. to _x86 Terminal_
4. Now select the renamed _x86 Terminal_ app and right-click and choose \*_Get Info_
5. Check the box for **Open using Rosetta**, then close the window
6. Run the _x86 Terminal_ as usual, which will fully support the current PX4 toolchain
:::
First set up the environment
1. Enable more open files by appending the following line to the `~/.zshenv` file (creating it if necessary):
```sh ```sh
echo ulimit -S -n 2048 >> ~/.zshenv xcode-select --install
``` ```
2. **Install Homebrew** by following the [installation instructions](https://brew.sh).
3. **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):
```sh
echo "ulimit -S -n 2048" >> ~/.zshrc
```
Then **open a new terminal** (or run `source ~/.zshrc`) for the change to take effect.
4. **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](https://github.com/pyenv/pyenv), which lets you set global and per-directory Python versions.
:::
### Install Development Tools
1. **Download PX4 Source Code:**
```sh
git clone https://github.com/PX4/PX4-Autopilot.git
cd PX4-Autopilot
git submodule update --init --recursive --force
```
2. **Install development environment libraries** from the [macos.sh](https://github.com/PX4/PX4-Autopilot/blob/main/Tools/setup/macos.sh) helper script:
```sh
./Tools/setup/macos.sh --sim-tools
```
This installs:
- **`px4-dev`** — ARM cross-compiler (`arm-gcc-bin@13`), `cmake`, `ninja`, `ccache`, and other build tools
- **Python packages** from `requirements.txt`
- **`px4-sim`** (via `--sim-tools`) — Gazebo Harmonic simulation (`gz-harmonic`) and related tools
::: info ::: info
If you don't do this, the build toolchain may report the error: `"LD: too many open files"` 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).
::: :::
1. Enforce Python 3 by appending the following lines to `~/.zshenv` ### Gazebo Simulation
```sh The `--sim-tools` flag installs the `px4-sim` Homebrew formula, which pulls in Gazebo Harmonic.
# Point pip3 to macOS system python 3 pip
alias pip3=/usr/bin/pip3
```
### Common Tools If you skipped `--sim-tools` during initial setup and want to add simulation later:
To setup the environment to be able to build for Pixhawk/NuttX hardware (and install the common tools for using simulators): ```sh
brew tap PX4/px4
brew install px4-sim
```
1. Install Homebrew by following these [installation instructions](https://brew.sh). ::: info
1. Run these commands in your shell to install the common tools: Gazebo requires **XQuartz** for display on macOS.
If you don't already have it installed:
```sh ```sh
brew tap PX4/px4 brew install --cask xquartz
brew install px4-dev ```
```
1. Install the required Python packages: You may need to log out and back in after installing XQuartz.
:::
```sh ### Verify Installation
# install required packages using pip3
python3 -m pip install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging kconfiglib future jsonschema
# if this fails with a permissions error, your Python install is in a system path - use this command instead:
sudo -H python3 -m pip install --user pyserial empty toml numpy pandas jinja2 pyyaml pyros-genmsg packaging kconfiglib future jsonschema
```
## Gazebo Classic Simulation After installation, verify the key tools are available:
To setup the environment for [Gazebo Classic](../sim_gazebo_classic/index.md) simulation: ```sh
# NuttX cross-compiler (from arm-gcc-bin@13)
arm-none-eabi-gcc --version
1. Run the following commands in your shell: # Build tools
cmake --version
ninja --version
```sh # Gazebo (if --sim-tools was used)
brew unlink tbb gz sim --versions
sed -i.bak '/disable! date:/s/^/ /; /disable! date:/s/./#/3' $(brew --prefix)/Library/Taps/homebrew/homebrew-core/Formula/tbb@2020.rb ```
brew install tbb@2020
brew link tbb@2020
```
::: info Quick smoke test — build and run a simulation target:
September 2021: The commands above are a workaround to this bug: [PX4-Autopilot#17644](https://github.com/PX4/PX4-Autopilot/issues/17644).
They can be removed once it is fixed (along with this note).
:::
1. To install SITL simulation with Gazebo Classic: ```sh
make px4_sitl gz_x500
```
```sh If everything is set up correctly, this will build PX4 SITL and launch a Gazebo simulation with the x500 quadcopter.
brew install --cask temurin
brew install --cask xquartz
brew install px4-sim-gazebo
```
1. Run the macOS setup script: `PX4-Autopilot/Tools/setup/macos.sh`
The easiest way to do this is to clone the PX4 source, and then run the script from the directory, as shown:
```sh
git clone https://github.com/PX4/PX4-Autopilot.git --recursive
cd PX4-Autopilot/Tools/setup
sh macos.sh
```
## Next Steps ## Next Steps
@@ -114,7 +122,7 @@ Once you have finished setting up the command-line toolchain:
- Install [VSCode](../dev_setup/vscode.md) (if you prefer using an IDE to the command line). - Install [VSCode](../dev_setup/vscode.md) (if you prefer using an IDE to the command line).
- Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md) - Install the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md)
:::tip ::: tip
The _daily build_ includes development tools that are hidden in release builds. 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. It may also provide access to new PX4 features that are not yet supported in release builds.
::: :::