From fc8bc668aecd87fd8c4776ec94a078484d5371ea Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Wed, 9 Mar 2022 11:47:08 +0000 Subject: [PATCH 1/3] [Docs] Added/Updated Lib builder docs --- docs/source/lib_builder.rst | 170 ++++++++++++++++++++++++++++++++---- 1 file changed, 153 insertions(+), 17 deletions(-) diff --git a/docs/source/lib_builder.rst b/docs/source/lib_builder.rst index e9a270362d2..cc609d13c4b 100644 --- a/docs/source/lib_builder.rst +++ b/docs/source/lib_builder.rst @@ -2,37 +2,173 @@ Library Builder ############### -How to Use Library Builder --------------------------- +About +----- -Espressif has provided a `tool `_ to simplify building your own compiled libraries for use in Arduino IDE (or your favorite IDE). -To generate custom libraries, follow these steps: +Espressif provides a `tool `_ to simplify building your own compiled libraries for use in Arduino IDE (or your favorite IDE). +This tool can be used to change the project or a specific configuration according to your needs. -- Step 1 - Clone the ESP32 Arduino lib builder:: +Installing +---------- + +To install the Library Builder into your environment, please, follow the instructions below. + +- Clone the ESP32 Arduino lib builder: + +.. code-block:: bash git clone https://github.com/espressif/esp32-arduino-lib-builder -- Step 2 - Go to the ``esp32-arduino-lib-builder`` folder:: +- Go to the ``esp32-arduino-lib-builder`` folder: + +.. code-block:: bash cd esp32-arduino-lib-builder -- Step 3 - Run the ``update-components`` script:: +- Build: + +.. code-block:: bash + + ./build.sh + +If everyting works, you may see the following message: ``Successfully created esp32 image.`` + +Dependencies +************ + +To build the libraries you will need to install some dependencies. Maybe you already have installed, but it is a good idea to check before building. + +- Install all dependencies (**Ubuntu**): + +.. code-block:: bash + + sudo apt-get install git wget curl libssl-dev libncurses-dev flex bison gperf cmake ninja-build ccache jq + +- Install Python and upgrade pip: + +.. code-block:: bash + + sudo apt-get install python3 + sudo pip install --upgrade pip + +- Install all required packages: + +.. code-block:: bash + + pip install --user setuptools pyserial click cryptography future pyparsing pyelftools + +Building +-------- + +If you have all the dependencies met, it is time to build the libraries. + +To build using the default configuration: + +.. code-block:: bash + + ./build.sh + +Custom Build +************ + +There are some options to help you creating the custom libraries. You can use the following options: + +Usage +^^^^^ + +.. code-block:: bash + + build.sh [-s] [-A arduino_branch] [-I idf_branch] [-i idf_commit] [-c path] [-t ] [-b ] [config ...] + +Skip Install/Update +^^^^^^^^^^^^^^^^^^^ + +Skip installing/updating of ESP-IDF and all components + +.. code-block:: bash + + ./build.sh -s + +This option can be used if you already have the ESP-IDF and all components already in your environment. + +Set Arduino-ESP32 Branch +^^^^^^^^^^^^^^^^^^^^^^^^ + +Set which branch of arduino-esp32 to be used for compilation + +.. code-block:: bash + + ./build.sh -A + +Set ESP-IDF Branch +^^^^^^^^^^^^^^^^^^ + +Set which branch of ESP-IDF to be used for compilation + +.. code-block:: bash + + ./build.sh -I + +Set the ESP-IDF Commit +^^^^^^^^^^^^^^^^^^^^^^ + +Set which commit of ESP-IDF to be used for compilation + +.. code-block:: bash + + ./build.sh -i + +Deploy +^^^^^^ + +Deploy the build to github arduino-esp32 + +.. code-block:: bash + + ./build.sh -d + +Set the Arduino-ESP32 Destination Folder +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Set the arduino-esp32 folder to copy the result to. ex. '$HOME/Arduino/hardware/espressif/esp32' + +.. code-block:: bash + + ./build.sh -c + +This function is used to copy the compiled libraries to the Arduino folder. + +Set the Target +^^^^^^^^^^^^^^ + +Set the build target(chip). ex. 'esp32s3' + +.. code-block:: bash + + ./build.sh -t + +This build command will build for the ESP32-S3 target. You can specify other targets. + +* esp32 +* esp32s2 +* esp32c3 +* esp32s3 - ./tools/update-components.sh` +Set Build Type +^^^^^^^^^^^^^^ -- Step 4 - Run ``install-esp-idf`` installation script (if you already have an ``$IDF_PATH`` defined, it will use your local copy of the repository):: +Set the build type. ex. 'build' to build the project and prepare for uploading to a board - ./tools/install-esp-idf.sh +.. code-block:: bash -- Step 5 - Copy the configuration (recommended) or directly edit sdkconfig using ``idf.py menuconfig``:: + ./build.sh -b - cp sdkconfig.esp32s2 sdkconfig +Additional Configuration +^^^^^^^^^^^^^^^^^^^^^^^^ -- Step 6 - Build:: +Specify additional configs to be applied. ex. 'qio 80m' to compile for QIO Flash@80MHz. Requires -b - idf.py build +.. code-block:: bash -The script automates the process of building `Arduino as an ESP-IDF component `_. -Once it is complete, you can cherry pick the needed libraries from ``out/tools/sdk/lib``, or run ``tools/copy-to-arduino.sh`` to copy the entire built system. -``tools/config.sh`` contains a number of variables that control the process, particularly the ``$IDF_BRANCH`` variable. You can adjust this to try building against newer versions, but there are absolutely no guarantees that any components will work or even successfully compile against a newer IDF. + ./build.sh -b From de3e91feee73c6d6a30426adde9cb874bd66cfe0 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Thu, 10 Mar 2022 17:27:25 +0000 Subject: [PATCH 2/3] [Docs] Fixes according to the PR review --- docs/source/lib_builder.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs/source/lib_builder.rst b/docs/source/lib_builder.rst index cc609d13c4b..7e7ab229c50 100644 --- a/docs/source/lib_builder.rst +++ b/docs/source/lib_builder.rst @@ -32,12 +32,12 @@ To install the Library Builder into your environment, please, follow the instruc ./build.sh -If everyting works, you may see the following message: ``Successfully created esp32 image.`` +If everything works, you may see the following message: ``Successfully created esp32 image.`` Dependencies ************ -To build the libraries you will need to install some dependencies. Maybe you already have installed, but it is a good idea to check before building. +To build the library you will need to install some dependencies. Maybe you already have installed it, but it is a good idea to check before building. - Install all dependencies (**Ubuntu**): @@ -72,7 +72,7 @@ To build using the default configuration: Custom Build ************ -There are some options to help you creating the custom libraries. You can use the following options: +There are some options to help you create custom libraries. You can use the following options: Usage ^^^^^ @@ -104,7 +104,7 @@ Set which branch of arduino-esp32 to be used for compilation Set ESP-IDF Branch ^^^^^^^^^^^^^^^^^^ -Set which branch of ESP-IDF to be used for compilation +Set which branch of ESP-IDF is to be used for compilation .. code-block:: bash @@ -158,7 +158,9 @@ This build command will build for the ESP32-S3 target. You can specify other tar Set Build Type ^^^^^^^^^^^^^^ -Set the build type. ex. 'build' to build the project and prepare for uploading to a board +Set the build type. ex. 'build' to build the project and prepare for uploading to a board. + +.. note:: This command depends on the ``-t`` argument. .. code-block:: bash @@ -169,6 +171,9 @@ Additional Configuration Specify additional configs to be applied. ex. 'qio 80m' to compile for QIO Flash@80MHz. Requires -b +.. note:: This command requires the ``-b`` to work properly. + + .. code-block:: bash - ./build.sh -b + ./build.sh -t esp32 -b idf_libs qio 80m From a3057da1685b30c9c340b7a6a3e659a6c2f748d0 Mon Sep 17 00:00:00 2001 From: "pedro.minatel" Date: Thu, 10 Mar 2022 17:28:42 +0000 Subject: [PATCH 3/3] [Docs] Fixes according to the PR review --- docs/source/lib_builder.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/lib_builder.rst b/docs/source/lib_builder.rst index 7e7ab229c50..5c62aafe55d 100644 --- a/docs/source/lib_builder.rst +++ b/docs/source/lib_builder.rst @@ -164,7 +164,7 @@ Set the build type. ex. 'build' to build the project and prepare for uploading t .. code-block:: bash - ./build.sh -b + ./build.sh -t esp32 -b Additional Configuration ^^^^^^^^^^^^^^^^^^^^^^^^