esp-idf/docs/en/get-started/macos-setup.rst

**********************************************
Standard Setup of Toolchain for macOS
**********************************************

:link_to_translation:`zh_CN:[中文]`

Install Prerequisites
=====================

ESP-IDF will use the version of Python installed by default on macOS.

- install pip::

    sudo easy_install pip

- install CMake & Ninja build:

  - If you have HomeBrew_, you can run::

      brew install cmake ninja dfu-util

  - If you have MacPorts_, you can run::

      sudo port install cmake ninja dfu-util

  - Otherwise, consult the CMake_ and Ninja_ home pages for macOS installation downloads.

- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.

.. note::
   If an error like this is shown during any step::

     xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun

   Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.

Installing Python 3
-------------------

Basing on macOS `Catalina 10.15 release notes`_, use of Python 2.7 is not recommended and Python 2.7 will not be included by default in future versions of macOS. Check what Python you currently have::

  python --version

If the output is like ``Python 2.7.17``, your default interpreter is Python 2.7. If so, also check if Python 3 isn't already installed on your computer::

  python3 --version

If above command returns an error, it means Python 3 is not installed.

Below is an overview of steps to install Python 3.

  - Installing with HomeBrew_ can be done as follows::

      brew install python3

  - If you have MacPorts_, you can run::

      sudo port install python38

Python 2 deprecation
====================

Python 2 reached its `end of life <https://www.python.org/doc/sunset-python-2/>`_ and support for it in ESP-IDF will be removed soon. Please install Python 3.6 or higher. Instructions for macOS are listed above.


Next Steps
==========

To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.


.. _cmake: https://cmake.org/
.. _ninja: https://ninja-build.org/
.. _ccache: https://ccache.samba.org/
.. _homebrew: https://brew.sh/
.. _MacPorts: https://www.macports.org/install.php
.. _Catalina 10.15 release notes: https://developer.apple.com/documentation/macos-release-notes/macos-catalina-10_15-release-notes
docs: Make CMake build system default, mark GNU Make as legacy option All `-cmake` suffixes are removed Where a GNU Make option is renamed, the `-legacy` suffix is used 2019-06-24 21:26:53 -04:00			`**********************************************`
docs: update CN translation and keep line number consistent for all documents in get-started section 2021-09-22 07:12:32 -04:00			`Standard Setup of Toolchain for macOS`
docs: Make CMake build system default, mark GNU Make as legacy option All `-cmake` suffixes are removed Where a GNU Make option is renamed, the `-legacy` suffix is used 2019-06-24 21:26:53 -04:00			`**********************************************`
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00
doc(global): build cross-language links for translated documents 2018-04-27 02:46:13 -04:00			:link_to_translation:`zh_CN:[中文]`
Getting started guides 2017-03-26 18:01:52 -04:00
			`Install Prerequisites`
			`=====================`

docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			`ESP-IDF will use the version of Python installed by default on macOS.`

Getting started guides 2017-03-26 18:01:52 -04:00			`- install pip::`

			`sudo easy_install pip`

docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			`- install CMake & Ninja build:`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			`- If you have HomeBrew_, you can run::`
Getting started guides 2017-03-26 18:01:52 -04:00
Add build system support for programming ESP32-S2 using DFU utils 2020-04-06 10:41:44 -04:00			`brew install cmake ninja dfu-util`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			`- If you have MacPorts_, you can run::`
Getting started guides 2017-03-26 18:01:52 -04:00
Add build system support for programming ESP32-S2 using DFU utils 2020-04-06 10:41:44 -04:00			`sudo port install cmake ninja dfu-util`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			`- Otherwise, consult the CMake_ and Ninja_ home pages for macOS installation downloads.`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			`.. note::`
			`If an error like this is shown during any step::`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			`xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00			Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
Getting started guides 2017-03-26 18:01:52 -04:00
tools: Prefer python3 during install and export Install and export script should work on systems without "python" executable. Closes https://github.com/espressif/esp-idf/pull/6471 Closes https://github.com/espressif/esp-idf/issues/6532 Related to https://github.com/espressif/esp-idf/issues/6421 and https://github.com/espressif/arduino-esp32/issues/4717 2021-02-02 07:20:09 -05:00			`Installing Python 3`
			`-------------------`
doc: Getting Started Guide, remove shortcuts to 'build toolchain from scratch' instructions 2020-09-03 14:05:24 -04:00
add CN translation for adding python2 deprecation warning(MR 11115) 2020-11-30 07:11:36 -05:00			Basing on macOS `Catalina 10.15 release notes`_, use of Python 2.7 is not recommended and Python 2.7 will not be included by default in future versions of macOS. Check what Python you currently have::
doc: Getting Started Guide, remove shortcuts to 'build toolchain from scratch' instructions 2020-09-03 14:05:24 -04:00
			`python --version`

			If the output is like ``Python 2.7.17``, your default interpreter is Python 2.7. If so, also check if Python 3 isn't already installed on your computer::

			`python3 --version`

docs: update CN translation and keep line number consistent for all documents in get-started section 2021-09-22 07:12:32 -04:00			`If above command returns an error, it means Python 3 is not installed.`
doc: Getting Started Guide, remove shortcuts to 'build toolchain from scratch' instructions 2020-09-03 14:05:24 -04:00
tools: Prefer python3 during install and export Install and export script should work on systems without "python" executable. Closes https://github.com/espressif/esp-idf/pull/6471 Closes https://github.com/espressif/esp-idf/issues/6532 Related to https://github.com/espressif/esp-idf/issues/6421 and https://github.com/espressif/arduino-esp32/issues/4717 2021-02-02 07:20:09 -05:00			`Below is an overview of steps to install Python 3.`
doc: Getting Started Guide, remove shortcuts to 'build toolchain from scratch' instructions 2020-09-03 14:05:24 -04:00
			`- Installing with HomeBrew_ can be done as follows::`

			`brew install python3`

			`- If you have MacPorts_, you can run::`

			`sudo port install python38`

Tools: add Python 2 deprecation warning 2020-11-04 17:32:40 -05:00			`Python 2 deprecation`
			`====================`

			Python 2 reached its `end of life <https://www.python.org/doc/sunset-python-2/>`_ and support for it in ESP-IDF will be removed soon. Please install Python 3.6 or higher. Instructions for macOS are listed above.

add CN translation for adding python2 deprecation warning(MR 11115) 2020-11-30 07:11:36 -05:00
Getting started guides 2017-03-26 18:01:52 -04:00			`Next Steps`
			`==========`

docs: Make CMake build system default, mark GNU Make as legacy option All `-cmake` suffixes are removed Where a GNU Make option is renamed, the `-legacy` suffix is used 2019-06-24 21:26:53 -04:00			To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Functional renaming commit for CMake-as-default Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be) 2019-06-24 21:29:49 -04:00
			`.. _cmake: https://cmake.org/`
			`.. _ninja: https://ninja-build.org/`
			`.. _ccache: https://ccache.samba.org/`
			`.. _homebrew: https://brew.sh/`
			`.. _MacPorts: https://www.macports.org/install.php`
doc: Getting Started Guide, remove shortcuts to 'build toolchain from scratch' instructions 2020-09-03 14:05:24 -04:00			`.. _Catalina 10.15 release notes: https://developer.apple.com/documentation/macos-release-notes/macos-catalina-10_15-release-notes`