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 -y update && sudo yum install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache dfu-util

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 flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util

- Arch::

    sudo pacman -S --needed gcc git make flex bison gperf python-pip 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".

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 {IDF_TARGET_NAME}. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.

Fixing broken pip on Ubuntu 16.04
=================================

Package ``python3-pip`` could be broken without possibility to upgrade it. Package has to be removed and installed manually using script `get-pip.py <https://bootstrap.pypa.io/get-pip.py>`_.::

    apt remove python3-pip python3-virtualenv; rm -r ~/.local
    rm -r ~/.espressif/python_env && python get-pip.py

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

.. _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-25 11:26:53 +10: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-25 11:29:49 +10:00
-												doc(global): build cross-language links for translated documents

											
										
										
											2018-04-27 14:46:13 +08:00
+								:link_to_translation:`zh_CN:[中文]`
-												Getting started guides

											
										
										
											2017-03-27 00:01:52 +02:00
 								Install Prerequisites
 								=====================
 								To compile with ESP-IDF you need to get the following packages:
 								- CentOS 7::
-												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 13:20:09 +01:00
+								    sudo yum -y update && sudo yum install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache dfu-util
-												Tools: add Python 2 deprecation warning

											
										
										
											2020-11-04 23:32:40 +01:00
 								CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience.
-												Getting started guides

											
										
										
											2017-03-27 00:01:52 +02:00
 								- Ubuntu and Debian::
-												Tools: add Python 2 deprecation warning

											
										
										
											2020-11-04 23:32:40 +01:00
+								    sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util
-												Getting started guides

											
										
										
											2017-03-27 00:01:52 +02:00
 								- Arch::
-												Add build system support for programming ESP32-S2 using DFU utils

											
										
										
											2020-04-06 16:41:44 +02:00
+								    sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja ccache dfu-util
-												Getting started guides

											
										
										
											2017-03-27 00:01:52 +02:00
-												Add python-future by using python requirements file

											
										
										
											2018-08-15 09:52:07 +02: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-25 11:29:49 +10: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 09:52:07 +02: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-25 11:29:49 +10:00
+								Additional Tips
-												Getting started guides

											
										
										
											2017-03-27 00:01:52 +02: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 17:44:08 +13:00
+								Permission issues /dev/ttyUSB0
 								------------------------------
-												doc: Update English pages with generic target name

											
										
										
											2019-12-09 11:01:09 +08:00
+								With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the {IDF_TARGET_NAME}. :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 17:44:08 +13:00
-												Tools: add Python 2 deprecation warning

											
										
										
											2020-11-04 23:32:40 +01:00
+								Fixing broken pip on Ubuntu 16.04
 								=================================
-												docs: update CN translation and keep line number consistent for all documents in get-started section

											
										
										
											2021-09-22 17:44:03 +08:00
+								Package ``python3-pip`` could be broken without possibility to upgrade it. Package has to be removed and installed manually using script `get-pip.py <https://bootstrap.pypa.io/get-pip.py>`_.::
-												Tools: add Python 2 deprecation warning

											
										
										
											2020-11-04 23:32:40 +01:00
 								    apt remove python3-pip python3-virtualenv; rm -r ~/.local
 								    rm -r ~/.espressif/python_env && python get-pip.py
 								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-27 00:01:52 +02: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-25 11:26:53 +10:00
+								To carry on with development environment setup, proceed to :ref:`get-started-get-esp-idf`.
-												Getting started guides

											
										
										
											2017-03-27 00:01:52 +02:00
 								.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository