Skip to content

Replace outdated macOS build steps with the install script #7853

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ismetvahidzade986-sketch wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Replace outdated macOS build steps with the install script #7853

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 18 additions & 64 deletions dev/source/docs/building-setup-mac.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,80 +4,34 @@
Setting up the Build Environment (MacOSX)
=========================================

This article shows how to manually setup a minimal build environment on MacOS (ver 10.6 onwards).
This article shows how to set up the build environment on macOS.

.. youtube:: wLK2wLwEXm4
:width: 100%


There is a `pre-built script <https://github.com/ArduPilot/ardupilot/blob/master/Tools/environment_install/install-prereqs-mac.sh>`__ that will install these pre-requisites.

How to use it, cd to your ardupilot directory, and execute:
The recommended way to install the prerequisites is the environment install
script. It is kept up to date with the current toolchain and Python
requirements, so it is less likely to drift than a manual list of steps. From
your ``ardupilot`` directory, run:

::

sh ./Tools/environment_install/install-prereqs-mac.sh


Setup steps
-----------

#. MacOS will alert you when you enter a command in the terminal that requires Xcode Command Line Tools. You can also install Xcode Command Line Tools manually

::

xcode-select --install

#. Install `Homebrew <http://brew.sh>`__ for MacOS (Homebrew is a respected package manager for MacOS)

::

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

#. Install the following packages using brew

::

brew update
brew install gcc-arm-none-eabi genromfs python3

#. Install the latest version of awk using brew (make sure
**/usr/local/bin** takes precedence in your path):

::
./Tools/environment_install/install-prereqs-mac.sh -y

@ES-Alexander ES-Alexander Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps worth mentioning that leaving off the -y argument allows more intentionally approving or declining each step of the process? -y is a nice convenience, but not using it provides a trust level between blind trust and manually reading and copying lines from the script.

Personally I'd prefer to let uv manage my Python versions and library installs, so I imagine others with similar inclinations may wish to avoid installing pyenv and a separate Python version without necessarily being aware of it. The script implementation details seem out of scope here - just mentioning as an example of why -y may not always be desirable.


brew install gawk
The script installs the Xcode command line tools, Homebrew, the ARM toolchain,
and the Python packages ArduPilot needs. If you would rather set things up by
hand, read the script and run the steps it performs.

#. Install *empy* and *pyserial* using the following commands:
.. note::

::

python3 -m pip install empy pyserial

::

** Starting with MacOS Mojave (10.14.x) you might want to install the SDK headers

open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg


#. Follow the :ref:`MAVProxy documentation <mavproxy:mavproxy-downloadinstallmac>` if you plan to use the simulator.

Now you should be able to build with waf as described in `BUILD.md <https://github.com/ArduPilot/ardupilot/blob/master/BUILD.md>`__.

Additional Steps for macOS mojave
---------------------------------
Due to some changes binutils installed via brew have stopped working for macOS mojave leading to crashing builds. So if installed, remove via following command:

::

brew uninstall binutils

Also you will need to install the c++ include headers to /usr/include to do that. Run the following in commandline and follow the installation routine:

::
Do not run the script with ``sudo``, and avoid ``sudo`` for Python or pip
packages in general. Install Python packages into a virtual environment
(``python3 -m venv``) rather than system-wide. Homebrew will prompt for your
Comment on lines +29 to +30

@ES-Alexander ES-Alexander Jul 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find it unclear whether this is either

  1. suggesting the prereqs script will automatically install things into a virtual environment
    • This does not seem to currently be the case, from a quick read of the script
  2. recommending users should create and activate a virtual environment before running the prereqs script
    • If so, there should be clearer instructions on how to do so (e.g. python3 -m venv .venv followed by source .venv/bin/activate), and how to get out of it (i.e. deactivate)

password itself when it needs it.

open /Library/Developer/CommandLineTools/Packages/macOS_SDK_headers_for_macOS_10.14.pkg
Once the prerequisites are installed you should be able to build with waf as
described in `BUILD.md <https://github.com/ArduPilot/ardupilot/blob/master/BUILD.md>`__.

Cleaning
--------
Expand All @@ -88,7 +42,7 @@ If there have been updates to some git submodules you may need to do a full clea

./waf distclean

Commands `clean` and `distclean` can be used to clean the objects produced by the build.
`clean` keeps the configure information, cleaning only the objects for the current board. `distclean` cleans everything for every board, including the saved configure information.
Commands ``clean`` and ``distclean`` can be used to clean the objects produced by the build.
``clean`` keeps the configure information, cleaning only the objects for the current board. ``distclean`` cleans everything for every board, including the saved configure information.

Follow the instructions for `build <https://github.com/ArduPilot/ardupilot/blob/master/BUILD.md>`__ .
Loading