Add Arduino lib to arduino as IDF component

[PilnyTomas]

This Doc update is based on "for reference" issue #7839
This update provides info on how to add Arduino library when using arduino-esp32 as an ESP_IDF component.
There is also new script in tools/add_lib.sh which helps with that. The script also creates the CMakefileLists.txt

Usage of the script:

This script help to add library when using arduino-esp32 as an ESP-IDF component
The script accepts up to three arguments:
-n  NEW: URL address to new library on GIThub (cannot be combined with -e)
-l  LOCAL: Path to the project where the library should be placed locally (must be paired with -e or -n)
-e  EXISTING: path to existing libary- this will simply skip the download (cannot be combined with -n)

Examples:
./add_lib.sh -n https://github.com/me-no-dev/ESPAsyncWebServer
./add_lib.sh -l ~/esp/esp-idf/examples/your_project
./add_lib.sh -e ~/Arduino/libraries/existing_library

./add_lib.sh -n https://github.com/me-no-dev/ESPAsyncWebServer -l ~/esp/esp-idf/examples/your_project
./add_lib.sh -e ~/Arduino/libraries/existing_library -l ~/esp/esp-idf/examples/your_project"

The script was tested with this (manually checked the results):

#!/bin/bash

# test all possible combinations of parameters for the add_lib.sh script

# define test cases
test_cases=(
    "-n https://github.com/me-no-dev/ESPAsyncWebServer -l ~/esp/esp-idf/examples/add_lib"
    "-n https://github.com/me-no-dev/ESPAsyncWebServer -e ~/Arduino/libraries/ESPAsyncWebSrv"
    "-l ~/esp/esp-idf/examples/add_lib -e ~/Arduino/libraries/ESPAsyncWebSrv"
    "-n https://github.com/me-no-dev/ESPAsyncWebServer -l ~/esp/esp-idf/examples/add_lib -e ~/Arduino/libraries/ESPAsyncWebSrv"
    "-n https://github.com/me-no-dev/ESPAsyncWebServer -e ~/nonexistent/folder"
    "-n https://github.com/me-no-dev/ESPAsyncWebServer"
    "-l ~/esp/esp-idf/examples/add_lib"
    "-e ~/Arduino/libraries/ESPAsyncWebSrv"
)

# run each test case
for test_case in "${test_cases[@]}"; do
    echo "Running test case: ./add_lib.sh $test_case"
    ./add_lib.sh $test_case
    if [ $? -eq 1 ]; then
        echo "Test case failed: $test_case"
    else
        echo "Test case passed: $test_case"
    fi
    echo "============================================="
done

[CLAassistant]

All committers have signed the CLA.

[igrr]

In general I would recommend avoiding the error-prone modifications of arduino-esp32/CMakeLists.txt. The main reason is that if a user has done local changes to the file, upgrading to a newer version of arduino-esp32 component becomes difficult.

IDF build system recommends keeping each library as a separate component. With that in mind, my recommendation for adding additional Arduino libraries to an IDF project would be as follows:

1. Keep each library in a separate component. This can be PROJECT/components/MyLibrary (local to the project) or SOME_COMMON_PATH/MyLibrary (global path, subsequently added into EXTRA_COMPONENT_DIRS.
2. In each such component, the user only has to add CMakeLists.txt file with the following content:

   arduino_library_register()

3. The function arduino_library_register would be implemented in arduino-esp32/project_include.cmake, along these lines:

   function(arduino_library_register)
       idf_component_register(SRC_DIRS src
                                                 INCLUDE_DIRS . src
                                                 REQUIRES arduino-esp32)
   endfunction()

   (can be made more complex than this, with optional arguments to customize the Arduino library layout, and such)

[lucasssvaz]

IMO the variable names should be more descriptive to help with code maintenance.

[me-no-dev]

Closed in favor of #8721