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

*********************************************
Standard Setup of Toolchain for Linux
*********************************************

:link_to_translation:`zh_CN:[中文]`

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

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

- CentOS 7::

    sudo yum install git wget ncurses-devel flex bison gperf python cmake ninja-build ccache

- Ubuntu and Debian::

    sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools cmake ninja-build ccache libffi-dev libssl-dev

- Arch::

    sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pip cmake ninja ccache

.. 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".

Additional Tips
===============

Permission issues /dev/ttyUSB0
------------------------------

With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.

Arch Linux Users
----------------

To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.

Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:

- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/

Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.

Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.

Setting up Python 3 as default for Ubuntu and Debian
----------------------------------------------------

Ubuntu and Debian are still providing Python 2.7 as the default interpreter. Python 3 can be installed as follows::

    sudo apt-get install python3 python3-pip python3-setuptools

Making Python 3 the default interpreter is possible by running::

    sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10

.. note::
    This is system-wide change which may affect all of the applications.

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

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


Related Documents
=================

.. toctree::
    :maxdepth: 1

    linux-setup-scratch


.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
-												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
+								*********************************************
 								Standard Setup of Toolchain for Linux
 								*********************************************
-												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
 								=====================
 								To compile with ESP-IDF you need to get the following packages:
 								- CentOS 7::
-												Docs: Encourage to used Python 3

											
										
										
											2020-02-20 10:00:53 -05:00
+								    sudo yum install git wget ncurses-devel flex bison gperf python cmake ninja-build ccache
-												Getting started guides

											
										
										
											2017-03-26 18:01:52 -04:00
 								- Ubuntu and Debian::
-												Docs: Encourage to used Python 3

											
										
										
											2020-02-20 10:00:53 -05:00
+								    sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools cmake ninja-build ccache libffi-dev libssl-dev
-												Getting started guides

											
										
										
											2017-03-26 18:01:52 -04:00
 								- Arch::
-												Docs: Encourage to used Python 3

											
										
										
											2020-02-20 10:00:53 -05:00
+								    sudo pacman -S --needed gcc git make ncurses flex bison gperf python-pip cmake ninja ccache
-												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".
-												Add python-future by using python requirements file

											
										
										
											2018-08-15 03:52:07 -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
+								Additional Tips
-												Getting started guides

											
										
										
											2017-03-26 18:01:52 -04:00
+								===============
-												docs: Improved documentation for /dev/ttyUSB0 issues

Improved documentation for /dev/ttyUSB0 issues.  This occurred in Ubuntu, but I'm sure is applies to most distributions.

Merges https://github.com/espressif/esp-idf/pull/1158

											
										
										
											2017-10-25 00:44:08 -04:00
+								Permission issues /dev/ttyUSB0
 								------------------------------
-												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
+								With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
-												docs: Improved documentation for /dev/ttyUSB0 issues

Improved documentation for /dev/ttyUSB0 issues.  This occurred in Ubuntu, but I'm sure is applies to most distributions.

Merges https://github.com/espressif/esp-idf/pull/1158

											
										
										
											2017-10-25 00:44:08 -04:00
-												Getting started guides

											
										
										
											2017-03-26 18:01:52 -04:00
+								Arch Linux Users
 								----------------
-												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
+								To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
-												Getting started guides

											
										
										
											2017-03-26 18:01:52 -04:00
 								Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
 								- https://aur.archlinux.org/packages/ncurses5-compat-libs/
 								- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
-												linux docs: (Arch) Add key to keyring

for me it was necessary to add the key manually to the key ring. Otherwise I could not have installed the packages

Merges https://github.com/espressif/esp-idf/pull/1029

(Amended to remove reference to exact key, references AUR links instead.)

											
										
										
											2017-09-22 17:38:08 -04:00
+								Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
-												Getting started guides

											
										
										
											2017-03-26 18:01:52 -04:00
+								Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
-												Docs: Encourage to used Python 3

											
										
										
											2020-02-20 10:00:53 -05:00
+								Setting up Python 3 as default for Ubuntu and Debian
 								----------------------------------------------------
 								Ubuntu and Debian are still providing Python 2.7 as the default interpreter. Python 3 can be installed as follows::
 								    sudo apt-get install python3 python3-pip python3-setuptools
 								Making Python 3 the default interpreter is possible by running::
 								    sudo update-alternatives --install /usr/bin/python python /usr/bin/python3 10
 								.. note::
 								    This is system-wide change which may affect all of the applications.
-												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
 								Related Documents
 								=================
 								.. toctree::
 								    :maxdepth: 1
 								    linux-setup-scratch
 								.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository