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

******************************************
Setup Linux Toolchain from Scratch
******************************************

:link_to_translation:`zh_CN:[中文]`

The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.

.. note:: The reason you might need to build your own toolchain is to solve the Y2K38 problem (time_t expand to 64 bits instead of 32 bits).

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

To compile with ESP-IDF you need to get the following packages:

- CentOS 7::

    sudo yum -y update && sudo yum install git wget ncurses-devel flex bison gperf python3 python3-pip cmake ninja-build ccache

CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience.

- Ubuntu and Debian::

    sudo apt-get install git wget libncurses-dev flex bison gperf python3 python3-pip python3-setuptools python3-serial python3-cryptography python3-future python3-pyparsing python3-pyelftools cmake ninja-build ccache libffi-dev libssl-dev dfu-util

- Arch::

    sudo pacman -Sy --needed gcc git make ncurses flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja ccache dfu-util

.. note::
    CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".

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

- Install dependencies:

  - CentOS 7::

        sudo yum install gawk gperf grep gettext ncurses-devel python3 python3-devel automake bison flex texinfo help2man libtool make

  - Ubuntu pre-16.04::

        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make

  - Ubuntu 16.04 or newer::

        sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make

  - Debian 9::

        sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make

  - Arch::

        sudo pacman -Sy --needed python-pip

Create the working directory and go into it::

  mkdir -p ~/esp
  cd ~/esp

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

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

.. note:: To create a toolchain with support for 64-bit time_t, you need to remove the ``--enable-newlib-long-time_t`` option from the ``crosstool-NG/samples/xtensa-esp32-elf/crosstool.config`` file in 33 and 43 lines.

Build the toolchain::

    ./ct-ng xtensa-esp32-elf
    ./ct-ng build
    chmod -R u+w builds/xtensa-esp32-elf

Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path-legacy>` to add the toolchain to your ``PATH``.

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 popular Linux distributions 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 Linux Toolchain 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			The following instructions are alternative to downloading binary toolchain from Espressif website. To quickly setup the binary toolchain, instead of compiling it yourself, backup and proceed to section :doc:`linux-setup`.
Getting started guides 2017-03-26 18:01:52 -04:00
idf: Support a custom toolchain with time_t wide 64-bits Allows resolving the Y2K38 problem. Closes: IDF-350 Closes: https://github.com/espressif/esp-idf/issues/584 2020-01-09 23:58:54 -05:00			`.. note:: The reason you might need to build your own toolchain is to solve the Y2K38 problem (time_t expand to 64 bits instead of 32 bits).`

Getting started guides 2017-03-26 18:01:52 -04:00			`Install Prerequisites`
			`=====================`

			`To compile with ESP-IDF you need to get the following packages:`

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			`- CentOS 7::`

Tools: add Python 2 deprecation warning 2020-11-04 17:32:40 -05:00			`sudo yum -y update && sudo yum install git wget ncurses-devel flex bison gperf python3 python3-pip cmake ninja-build ccache`

			`CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience.`
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
Getting started guides 2017-03-26 18:01:52 -04:00			`- Ubuntu and Debian::`

Tools: add Python 2 deprecation warning 2020-11-04 17:32:40 -05:00			`sudo apt-get install git wget libncurses-dev flex bison gperf python3 python3-pip python3-setuptools python3-serial python3-cryptography python3-future python3-pyparsing python3-pyelftools cmake ninja-build ccache libffi-dev libssl-dev dfu-util`
Getting started guides 2017-03-26 18:01:52 -04:00
			`- Arch::`

Tools: add Python 2 deprecation warning 2020-11-04 17:32:40 -05:00			`sudo pacman -Sy --needed gcc git make ncurses flex bison gperf python-pyserial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja ccache dfu-util`
Getting started guides 2017-03-26 18:01:52 -04:00
Add python-future by using python requirements file 2018-08-15 03:52:07 -04:00			`.. note::`
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 version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake".`
Getting started guides 2017-03-26 18:01:52 -04:00
			`Compile the Toolchain from Source`
			`=================================`

			`- Install dependencies:`

			`- CentOS 7::`

Tools: add Python 2 deprecation warning 2020-11-04 17:32:40 -05:00			`sudo yum install gawk gperf grep gettext ncurses-devel python3 python3-devel automake bison flex texinfo help2man libtool make`
Getting started guides 2017-03-26 18:01:52 -04:00
			`- Ubuntu pre-16.04::`

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 apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make`
Getting started guides 2017-03-26 18:01:52 -04:00
docs: Update package dependencies Closes https://github.com/espressif/esp-idf/issues/2384 2019-03-01 04:50:16 -05:00			`- Ubuntu 16.04 or newer::`
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			`sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make`
Getting started guides 2017-03-26 18:01:52 -04:00
Add build dependencies for toolchain for Debian Merges https://github.com/espressif/esp-idf/pull/1465 2018-01-05 04:48:35 -05:00			`- Debian 9::`
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			`sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make`
Getting started guides 2017-03-26 18:01:52 -04:00
			`- Arch::`

Tools: add Python 2 deprecation warning 2020-11-04 17:32:40 -05:00			`sudo pacman -Sy --needed python-pip`
Getting started guides 2017-03-26 18:01:52 -04:00
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			`Create the working directory and go into it::`

			`mkdir -p ~/esp`
			`cd ~/esp`

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: generate toolchain download links 2018-08-29 09:30:03 -04:00			`.. include:: /_build/inc/scratch-build-code.inc`
Getting started guides 2017-03-26 18:01:52 -04:00
idf: Support a custom toolchain with time_t wide 64-bits Allows resolving the Y2K38 problem. Closes: IDF-350 Closes: https://github.com/espressif/esp-idf/issues/584 2020-01-09 23:58:54 -05:00			.. note:: To create a toolchain with support for 64-bit time_t, you need to remove the ``--enable-newlib-long-time_t`` option from the ``crosstool-NG/samples/xtensa-esp32-elf/crosstool.config`` file in 33 and 43 lines.

Getting started guides 2017-03-26 18:01:52 -04:00			`Build the toolchain::`

			`./ct-ng xtensa-esp32-elf`
			`./ct-ng build`
			`chmod -R u+w builds/xtensa-esp32-elf`

Fix broken links in 'Getting Started' gudes 2019-08-02 05:09:33 -04:00			Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path-legacy>` to add the toolchain to your ``PATH``.
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 popular Linux distributions 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`.