diff --git a/Tools/setup/macos.sh b/Tools/setup/macos.sh index a3457129ee..8218b4e9ab 100755 --- a/Tools/setup/macos.sh +++ b/Tools/setup/macos.sh @@ -74,7 +74,7 @@ python3 -m pip install --user -r ${DIR}/requirements.txt # Optional, but recommended additional simulation tools: 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 elif [[ $REINSTALL_FORMULAS == "--reinstall" ]]; then brew reinstall px4-sim diff --git a/docs/en/dev_setup/dev_env_mac.md b/docs/en/dev_setup/dev_env_mac.md index 25757f8657..8110a58173 100644 --- a/docs/en/dev_setup/dev_env_mac.md +++ b/docs/en/dev_setup/dev_env_mac.md @@ -1,111 +1,119 @@ # 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: - 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 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 - +### Prerequisites -## Base Setup - -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): +1. **Install Xcode Command Line Tools** — provides `git`, `make`, and the Apple `clang` compiler: ```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 - 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 - # Point pip3 to macOS system python 3 pip - alias pip3=/usr/bin/pip3 - ``` +The `--sim-tools` flag installs the `px4-sim` Homebrew formula, which pulls in Gazebo Harmonic. -### 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). -1. Run these commands in your shell to install the common tools: +::: info +Gazebo requires **XQuartz** for display on macOS. +If you don't already have it installed: - ```sh - brew tap PX4/px4 - brew install px4-dev - ``` +```sh +brew install --cask xquartz +``` -1. Install the required Python packages: +You may need to log out and back in after installing XQuartz. +::: - ```sh - # 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 - ``` +### Verify Installation -## 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 - brew unlink tbb - 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 - ``` +# Gazebo (if --sim-tools was used) +gz sim --versions +``` - ::: info - 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). - ::: +Quick smoke test — build and run a simulation target: -1. To install SITL simulation with Gazebo Classic: +```sh +make px4_sitl gz_x500 +``` - ```sh - 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 - ``` +If everything is set up correctly, this will build PX4 SITL and launch a Gazebo simulation with the x500 quadcopter. ## 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 the [QGroundControl Daily Build](../dev_setup/qgc_daily_build.md) - :::tip + ::: 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. :::