1****************
2IDF Docker Image
3****************
4
5.. highlight:: bash
6
7IDF Docker image (``espressif/idf``) is intended for building applications and libraries with specific versions of ESP-IDF, when doing automated builds.
8
9The image contains:
10
11- Common utilities such as git, wget, curl, zip.
12- Python 3.6 or newer.
13- A copy of a specific version of ESP-IDF (see below for information about versions). ``IDF_PATH`` environment variable is set, and points to ESP-IDF location in the container.
14- All the build tools required for the specific version of ESP-IDF: CMake, make, ninja, cross-compiler toolchains, etc.
15- All Python packages required by ESP-IDF are installed in a virtual environment.
16
17The image entrypoint sets up ``PATH`` environment variable to point to the correct version of tools, and activates the Python virtual environment. As a result, the environment is ready to use the ESP-IDF build system.
18
19The image can also be used as a base for custom images, if additional utilities are required.
20
21Tags
22====
23
24Multiple tags of this image are maintained:
25
26- ``latest``: tracks ``master`` branch of ESP-IDF
27- ``vX.Y``: corresponds to ESP-IDF release ``vX.Y``
28- ``release-vX.Y``: tracks ``release/vX.Y`` branch of ESP-IDF
29
30.. note::
31
32    Versions of ESP-IDF released before this feature was introduced do not have corresponding Docker image versions. You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags.
33
34Usage
35=====
36
37Setting up Docker
38~~~~~~~~~~~~~~~~~
39
40Before using the ``espressif/idf`` Docker image locally, make sure you have Docker installed. Follow the instructions at https://docs.docker.com/install/, if it is not installed yet.
41
42If using the image in CI environment, consult the documentation of your CI service on how to specify the image used for the build process.
43
44Building a project with CMake
45~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
46
47In the project directory, run::
48
49    docker run --rm -v $PWD:/project -w /project espressif/idf idf.py build
50
51
52The above command explained:
53
54- ``docker run``: runs a Docker image. It is a shorter form of the command ``docker container run``.
55- ``--rm``: removes the container when the build is finished
56- ``-v $PWD:/project``: mounts the current directory on the host (``$PWD``) as ``/project`` directory in the container
57- ``espressif/idf``: uses Docker image ``espressif/idf`` with tag ``latest`` (implicitly added by Docker when no tag is specified)
58- ``idf.py build``: runs this command inside the container
59
60To build with a specific docker image tag, specify it as ``espressif/idf:TAG``, for example::
61
62    docker run --rm -v $PWD:/project -w /project espressif/idf:release-v4.0 idf.py build
63
64You can check the up-to-date list of available tags at https://hub.docker.com/r/espressif/idf/tags.
65
66
67Building a project with GNU Make
68~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
69
70Same as for CMake, except that the build command is different::
71
72    docker run --rm -v $PWD:/project -w /project espressif/idf make defconfig all -j4
73
74
75.. note::
76
77    If the ``sdkconfig`` file does not exist, the default behavior of GNU Make build system is to open the menuconfig UI. This may be not desired in automated build environments. To ensure that the ``sdkconfig`` file exists, ``defconfig`` target is added before ``all``.
78
79If you intend to build the same project repeatedly, you may bind the ``tools/kconfig`` directory of ESP-IDF to a named volume. This will prevent Kconfig tools, located in ESP-IDF directory, from being rebuilt, causing a rebuild of the rest of the project::
80
81    docker run --rm -v $PWD:/project -v kconfig:/opt/esp/idf/tools/kconfig -w /project espressif/idf make defconfig all -j4
82
83If you need clean up the ``kconfig`` volume, run ``docker volume rm kconfig``.
84
85Binding the ``tools/kconfig`` directory to a volume is not necessary when using the CMake build system.
86
87Using the image interactively
88~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
89
90It is also possible to do builds interactively, to debug build issues or test the automated build scripts. Start the container with `-i -t` flags::
91
92    docker run --rm -v $PWD:/project -w /project -it espressif/idf
93
94
95Then inside the container, use ``idf.py`` as usual::
96
97    idf.py menuconfig
98    idf.py build
99
100.. note::
101
102    Commands which communicate with the development board, such as ``idf.py flash`` and ``idf.py monitor`` will not work in the container unless the serial port is passed through into the container. However currently this is not possible with Docker for Windows (https://github.com/docker/for-win/issues/1018) and Docker for Mac (https://github.com/docker/for-mac/issues/900).
103