|
1 | | -# ESP32 Arduino Lib Builder [](https://github.com/espressif/esp32-arduino-lib-builder/actions/workflows/push.yml) |
| 1 | +# ESP32 Arduino Lib Builder |
2 | 2 |
|
3 | | -This repository contains the scripts that produce the libraries included with esp32-arduino. |
| 3 | +This repository contains the scripts that produce the SDK included with esp32-arduino. It not only supports local compilation but also provides an automated compilation and SDK download process through GitHub Actions. |
4 | 4 |
|
5 | | -Tested on Ubuntu (32 and 64 bit), Raspberry Pi and MacOS. |
| 5 | +If you want to directly use the precompiled SDK based on the branches below, please check the [arduino-esp32-SDK](https://github.com/esp-arduino-libs/arduino-esp32-sdk) repository. |
6 | 6 |
|
7 | | -### Build on Ubuntu and Raspberry Pi |
8 | | -```bash |
9 | | -sudo apt-get install git wget curl libssl-dev libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache jq |
10 | | -sudo pip install --upgrade pip |
11 | | -git clone https://github.com/espressif/esp32-arduino-lib-builder |
12 | | -cd esp32-arduino-lib-builder |
13 | | -./build.sh |
14 | | -``` |
| 7 | +## Contents |
15 | 8 |
|
16 | | -### Using the User Interface |
| 9 | +- [ESP32 Arduino Lib Builder](#esp32-arduino-lib-builder) |
| 10 | + - [Contents](#contents) |
| 11 | + - [Feature](#feature) |
| 12 | + - [Branches](#branches) |
| 13 | + - [Release Versions](#release-versions) |
| 14 | + - [Debug Versions](#debug-versions) |
| 15 | + - [High Performance Versions](#high-performance-versions) |
| 16 | + - [How to Use](#how-to-use) |
| 17 | + - [Compilation in Github](#compilation-in-github) |
| 18 | + - [Compilation in Local](#compilation-in-local) |
17 | 19 |
|
18 | | -You can more easily build the libraries using the user interface found in the `tools/config_editor/` folder. |
19 | | -It is a Python script that allows you to select and edit the options for the libraries you want to build. |
20 | | -The script has mouse support and can also be pre-configured using the same command line arguments as the `build.sh` script. |
21 | | -For more information and troubleshooting, please refer to the [UI README](tools/config_editor/README.md). |
| 20 | +## Feature |
22 | 21 |
|
23 | | -To use it, follow these steps: |
| 22 | +In comparison to the original [esp32-arduino-lib-builder](https://github.com/espressif/esp32-arduino-lib-builder), this repository is used for recompiling specific versions of the SDK in `arduino-esp32` and has the following branches: |
24 | 23 |
|
25 | | -1. Make sure you have the required dependencies installed: |
26 | | - - Python 3.9 or later |
27 | | - - The [Textual](https://github.com/textualize/textual/) library |
28 | | - - All the dependencies listed in the previous section |
| 24 | +* `release/*` is used to recompile the original SDK for a specified version. |
| 25 | +* `debug/*` is used to recompile debug versions based on a specified SDK version. |
| 26 | +* `high_perf/*` is used to recompile high performance versions based on a specified SDK version. It changes some configurations (as below) and can achieve higher performance in some cases, especially for avoiding [screen drifting](https://docs.espressif.com/projects/esp-faq/en/latest/software-framework/peripherals/lcd.html#why-do-i-get-drift-overall-drift-of-the-display-when-esp32-s3-is-driving-an-rgb-lcd-screen) when using RGB LCDs. (Only available for v3.x and above versions) |
29 | 27 |
|
30 | | -2. Execute the script `tools/config_editor/app.py` from any folder. It will automatically detect the path to the root of the repository. |
| 28 | + * For ESP32-S3 SoCs: |
| 29 | + * It changes the optimization level from `-Os` to `-O2` by enabling `CONFIG_COMPILER_OPTIMIZATION_PERF=y`. |
| 30 | + * It increases the size of the data cache line from `32` to `64` by enabling `CONFIG_ESP32S3_DATA_CACHE_LINE_64B=y`. |
| 31 | + * For ESP32-S3R8 SoC: |
| 32 | + * It enables the function **XIP on PSRAM** by enabling `CONFIG_SPIRAM_FETCH_INSTRUCTIONS=y` and `CONFIG_SPIRAM_RODATA=y`. |
31 | 33 |
|
32 | | -3. Configure the compilation and ESP-IDF options as desired. |
| 34 | +## Branches |
33 | 35 |
|
34 | | -4. Click on the "Compile Static Libraries" button to start the compilation process. |
| 36 | +### Release Versions |
35 | 37 |
|
36 | | -5. The script will show the compilation output in a new screen. Note that the compilation process can take many hours, depending on the number of libraries selected and the options chosen. |
| 38 | +* [release/v2.0.13](https://github.com/esp-arduino-libs/esp32-arduino-lib-builder/tree/release/v2.0.13) |
| 39 | +* [release/v3.0.0-alpha3](https://github.com/esp-arduino-libs/esp32-arduino-lib-builder/tree/release/v3.0.0-alpha3) |
37 | 40 |
|
38 | | -6. If the compilation is successful and the option to copy the libraries to the Arduino Core folder is enabled, it will already be available for use in the Arduino IDE. Otherwise, you can find the compiled libraries in the `esp32-arduino-libs` folder alongside this repository. |
39 | | - - Note that the copy operation doesn't currently support the core downloaded from the Arduino IDE Boards Manager, only the manual installation from the [`arduino-esp32`](https://github.com/espressif/arduino-esp32) repository. |
| 41 | +### Debug Versions |
40 | 42 |
|
41 | | -### Documentation |
| 43 | +Due to the support of specifying the LOG level when compiling v3.x and above versions in esp32-arduino-lib-builder, the branches here are only used to compile debug versions of v2.x. |
42 | 44 |
|
43 | | -For more information about how to use the Library builder, please refer to this [Documentation page](https://docs.espressif.com/projects/arduino-esp32/en/latest/lib_builder.html?highlight=lib%20builder) |
| 45 | +* [debug/v2.0.13](https://github.com/esp-arduino-libs/esp32-arduino-lib-builder/tree/release/v2.0.13) |
| 46 | + |
| 47 | +### High Performance Versions |
| 48 | + |
| 49 | +As only v3.x and above versions support the required high-performance configurations, the branches here are only used for compiling the high_perf version of v3.x. |
| 50 | + |
| 51 | +* [high_perf/v3.0.0-alpha3](https://github.com/esp-arduino-libs/esp32-arduino-lib-builder/tree/high_perf/v3.0.0-alpha3) |
| 52 | + |
| 53 | +## How to Use |
| 54 | + |
| 55 | +### Compilation in Github |
| 56 | + |
| 57 | +1. Click `Fork` to fork this repository into your account. |
| 58 | + |
| 59 | + <img src="docs/_static/auto_step_0-1.png"> |
| 60 | + |
| 61 | +2. Uncheck the `Copy the master branch only` option and click `Create fork`. |
| 62 | + |
| 63 | + <img src="docs/_static/auto_step_0-2.png"> |
| 64 | + |
| 65 | +3. If you want to change the default configurations, follow the below steps: |
| 66 | + |
| 67 | + * Choose a branch based on the version you want to recompile. Here take `release/v3.0.0-alpha3` as an example. |
| 68 | + |
| 69 | + <img src="docs/_static/auto_step_1.png"> |
| 70 | + |
| 71 | + * To change the default configurations, mofify the files in the `configs` folder based on your application requirements. |
| 72 | + |
| 73 | + <img src="docs/_static/auto_step_2.png"> |
| 74 | + |
| 75 | + * Commit the changes. |
| 76 | + |
| 77 | + <img src="docs/_static/auto_step_3.png"> |
| 78 | + |
| 79 | + * Select `Create a new branch for this commit and start a pull request`, change the branch name if needed and click `Propose changes`. |
| 80 | + |
| 81 | + <img src="docs/_static/auto_step_4.png"> |
| 82 | + |
| 83 | + * Do not create a pull request, just click `Action`. Here you can see the compilation process. (Default to compile all targets) |
| 84 | + |
| 85 | + <img src="docs/_static/auto_step_5.png"> |
| 86 | + |
| 87 | + <img src="docs/_static/auto_step_6.png"> |
| 88 | + |
| 89 | +4. If you don't need to change the default configurations or just want to compile a specific target, follow the below steps: |
| 90 | + |
| 91 | + * Click `Actions`, here are two workflows, `Manual Build SDK For (v2) the Specific Target` is used to compile the v2.x version, and `Manual Build SDK For (v3) the Specific Target` is used to compile the v3.x version. |
| 92 | + |
| 93 | + <img src="docs/_static/manual_step_0_0.png"> |
| 94 | + |
| 95 | + * If you want to compile the **v2.x version**, click `Manual Build SDK For (v2) the Specific Target`, then click `Run workflow`. Here you can select the branch (only available for the `xx/v2.x.x` branches) and the target. |
| 96 | + |
| 97 | + <img src="docs/_static/manual_step_0_1.png"> |
| 98 | + |
| 99 | + * If you want to compile the **v3.x version**, click `Manual Build SDK For (v3) the Specific Target`, then click `Run workflow`. Here you can select the branch (only available for the `xx/v3.x.x` branches), the target and log level. So there are no `debug/v3.x.x` branches, you can specify the log level when compiling. |
| 100 | + |
| 101 | + <img src="docs/_static/manual_step_0_2.png"> |
| 102 | + |
| 103 | + * Then the compilation process will start. After it is complete, download the zip file from the `Artifacts`. |
| 104 | + |
| 105 | + <img src="docs/_static/manual_step_3.png"> |
| 106 | + |
| 107 | + <img src="docs/_static/auto_step_7.png"> |
| 108 | + |
| 109 | +6. To replace the original SDK, please refer to the [steps](https://github.com/esp-arduino-libs/arduino-esp32-sdk#how-to-use) for more details. |
| 110 | + |
| 111 | +### Compilation in Local |
| 112 | + |
| 113 | +1. Choose a branch version based on your application requirements and download it to the local. |
| 114 | +2. Modify the files in the `configs` folder based on your application requirements. |
| 115 | +3. Consult its README for compilation instructions. Note that the process involves downloading `ESP-IDF`, `arduino-esp32`, and several large components, which may take a considerable amount of time. Please be patient. |
| 116 | +6. After the compilation is complete, the SDK will be located in the `out` folder. |
| 117 | +7. To replace the original SDK, please refer to the [steps](https://github.com/esp-arduino-libs/arduino-esp32-sdk#how-to-use) for more details. |
0 commit comments