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

***********************************************
Setup Toolchain for Mac OS from Scratch
***********************************************

:link_to_translation:`zh_CN:[中文]`

Package Manager
===============

To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain<macos-setup>`, you will need to install either the MacPorts_ or Homebrew_ package manager.

MacPorts needs a full XCode installation, while Homebrew only needs XCode command line tools.

    .. _Homebrew: https://brew.sh/
    .. _MacPorts: https://www.macports.org/install.php

See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.

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

- install pip::

    sudo easy_install pip

- install pyserial::

    pip install --user pyserial

- 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

Compile the Toolchain from Source
=================================

- Install dependencies:

  - with MacPorts::

        sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make

  - with Homebrew::

        brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make

Create a case-sensitive filesystem image::

    hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"

Mount it::

    hdiutil mount ~/esp/crosstool.dmg

Create a symlink to your work directory::

    mkdir -p ~/esp
    ln -s /Volumes/ctng ~/esp/ctng-volume

Go into the newly created directory::

    cd ~/esp/ctng-volume

Download ``crosstool-NG`` and build it:

.. include-build-file:: inc/scratch-build-code.inc

Build the toolchain::

    ./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf
    ./ct-ng build
    chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf

Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` to ``PATH`` environment variable.

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`.
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			`***********************************************`
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			`Setup Toolchain for Mac OS from Scratch`
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			`***********************************************`

Included missing links between English and Chinese documentation, where translation into Chinese is available 2019-01-27 13:01:34 -05:00			:link_to_translation:`zh_CN:[中文]`
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			`Package Manager`
			`===============`

Doc/update CN translation for files on setting up toolchain from scratch in get started 2020-11-30 04:58:27 -05:00			To set up the toolchain from scratch, rather than :doc:`downloading a pre-compiled toolchain<macos-setup>`, you will need to install either the MacPorts_ or Homebrew_ package manager.
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/update CN translation for files on setting up toolchain from scratch in get started 2020-11-30 04:58:27 -05:00			`MacPorts needs a full XCode installation, while Homebrew only needs XCode command line tools.`
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/update CN translation for files on setting up toolchain from scratch in get started 2020-11-30 04:58:27 -05:00			`.. _Homebrew: https://brew.sh/`
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			`.. _MacPorts: https://www.macports.org/install.php`

			See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
docs: fix instructions for building toolchain on macOS Closes https://github.com/espressif/esp-idf/issues/503 Closes https://github.com/espressif/esp-idf/issues/2607 2018-10-22 01:45:09 -04:00
Getting started guides 2017-03-26 18:01:52 -04:00			`Install Prerequisites`
			`=====================`

			`- 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 pyserial::`
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			`pip install --user pyserial`

			`- install CMake & Ninja build:`

Doc/update CN translation for files on setting up toolchain from scratch in get started 2020-11-30 04:58:27 -05:00			`- If you have Homebrew, you can run::`
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
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`
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::`

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
			`Compile the Toolchain from Source`
			`=================================`

			`- Install dependencies:`

			`- with MacPorts::`

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			`sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make`
Getting started guides 2017-03-26 18:01:52 -04:00
Doc/update CN translation for files on setting up toolchain from scratch in get started 2020-11-30 04:58:27 -05:00			`- with Homebrew::`
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			`brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make`
Getting started guides 2017-03-26 18:01:52 -04:00
			`Create a case-sensitive filesystem image::`

			`hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"`

			`Mount it::`

			`hdiutil mount ~/esp/crosstool.dmg`

			`Create a symlink to your work directory::`

docs: fix instructions for building toolchain on macOS Closes https://github.com/espressif/esp-idf/issues/503 Closes https://github.com/espressif/esp-idf/issues/2607 2018-10-22 01:45:09 -04:00			`mkdir -p ~/esp`
			`ln -s /Volumes/ctng ~/esp/ctng-volume`

			`Go into the newly created directory::`

			`cd ~/esp/ctng-volume`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: generate toolchain download links 2018-08-29 09:30:03 -04:00			Download ``crosstool-NG`` and build it:
Getting started guides 2017-03-26 18:01:52 -04:00
docs: add new top-level docs builder that builds docs for a single chip 2019-11-12 22:46:16 -05:00			`.. include-build-file:: inc/scratch-build-code.inc`
Getting started guides 2017-03-26 18:01:52 -04:00
			`Build the toolchain::`

doc: Update English pages with generic target name 2019-12-08 22:01:09 -05:00			`./ct-ng xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`
Getting started guides 2017-03-26 18:01:52 -04:00			`./ct-ng build`
doc: Update English pages with generic target name 2019-12-08 22:01:09 -05:00			`chmod -R u+w builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf`
Getting started guides 2017-03-26 18:01:52 -04:00
doc: Update English pages with generic target name 2019-12-08 22:01:09 -05:00			Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf``. To use it, you need to add ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-{IDF_TARGET_TOOLCHAIN_NAME}-elf/bin`` to ``PATH`` environment variable.
Getting started guides 2017-03-26 18:01:52 -04:00
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.
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`.