Add Arduino lib to arduino as IDF component (#8721)

* Iniital commit

* Fixed naming of the CMakeLists.txt file in the doc text

* Finished the docmentation

* Updated, but not yet tested script

* Finished script

---------

Co-authored-by: Tomas Pilny <tomas.pilny@espressif.com>

docs/source/esp-idf_component.rst

@@ -163,3 +163,88 @@ Compilation Errors
 ------------------
 
 As commits are made to esp-idf and submodules, the codebases can develop incompatibilities that cause compilation errors.  If you have problems compiling, follow the instructions in `Issue #1142 <https://github.com/espressif/arduino-esp32/issues/1142>`_ to roll esp-idf back to a different version.
+
+Adding arduino library
+----------------------
+
+There are few approaches:
+
+1. Add global library to ``components/arduino-esp32/libraries/new_library``
+2. Add local project library to ``examples/your_project/main/libraries/new_library``
+
+1 Adding global library
+***********************
+
+Download the library:
+
+.. code-block:: bash
+
+    cd ~/esp/esp-idf/components/arduino-esp32/
+    git clone --recursive git@github.com:Author/new_library.git libraries/new_library
+
+
+Edit file ``components/arduino-esp32/CMakeLists.txt``
+
+Get the source file list with shell command:
+
+.. code-block:: bash
+
+    find libraries/new_library/src/ -name '*.c' -o -name '*.cpp'
+      libraries/new_library/src/new_library.cpp
+      libraries/new_library/src/new_library_extra_file.c
+
+Locate block which starts with ``set(LIBRARY_SRCS`` and copy the list there. Now it should look something like this:
+
+.. code-block:: bash
+
+    set(LIBRARY_SRCS
+      libraries/ArduinoOTA/src/ArduinoOTA.cpp
+      libraries/AsyncUDP/src/AsyncUDP.cpp
+      libraries/new_library/src/new_library.cpp
+      libraries/new_library/src/new_library_extra_file.c
+
+
+After this add the library path to block which starts with ``set(includedirs``. It should look like this:
+
+.. code-block:: bash
+
+    set(includedirs
+      variants/${CONFIG_ARDUINO_VARIANT}/
+      cores/esp32/
+      libraries/ArduinoOTA/src
+      libraries/AsyncUDP/src
+      libraries/new_library/src
+
+
+2 Adding local library
+**********************
+
+Download the library:
+
+.. code-block:: bash
+
+    cd ~/esp/esp-idf/examples/your_project
+    mkdir components
+    git clone --recursive git@github.com:Author/new_library.git components/new_library
+
+Create new CMakeists.txt in the library folder: ``components/new_library/CMakeLists.txt``
+
+.. code-block:: bash
+
+    idf_component_register(SRCS "new_library.cpp" "another_source.c"
+                          INCLUDE_DIRS "."
+                          REQUIRES arduino-esp32
+                          )
+
+You can read more about CMakeLists in the IDF documentation regarding the `Build System <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html>`_
+
+Tip
+---
+
+If you want to use arduino-esp32 both as an ESP-IDF component and with Arduino IDE you can simply create a symlink:
+
+.. code-block:: bash
+
+    ln -s ~/Arduino/hardware/espressif/esp32  ~/esp/esp-idf/components/arduino-esp32
+
+This will allow you to install new libraries as usual with Arduino IDE. To use them with IDF component, use ``add_lib.sh -e ~/Arduino/libraries/New_lib``

tools/add_lib.sh

@@ -0,0 +1,144 @@
+#!/bin/bash
+HELP="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"
+
+# Get the directory name where this script is located
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )"
+
+# Construct the absolute path to libraries folder
+ARDUINO_LIBS_PATH="$SCRIPT_DIR/../libraries"
+
+# Define the default values for the parameters
+e_param=""
+l_param=""
+n_param=""
+
+# Parse the command-line arguments using getopts
+while getopts "he:l:n:" opt; do
+  case $opt in
+    h)
+      echo "$HELP"
+      exit 0
+      ;;
+    e)
+      #e_param="$OPTARG"
+      e_param="${OPTARG/#~/$HOME}"
+      ;;
+    l)
+      #l_param="$OPTARG"
+      l_param="${OPTARG/#~/$HOME}"
+      ;;
+    n)
+      n_param=$OPTARG
+      ;;
+    \?)
+      echo "Invalid option: -$OPTARG" >&2
+      echo $HELP
+      exit 1
+      ;;
+    :)
+      echo "Option -$OPTARG requires an argument." >&2
+      echo $HELP
+      exit 1
+      ;;
+  esac
+done
+
+# No parameter check
+if [[ -z "$e_param" ]] && [[ -z "$l_param" ]] && [[ -z "$n_param" ]]; then
+  echo "Error: No parameters" >&2
+  echo "$HELP"
+  exit 1
+fi
+
+# Only local path check (not permitted)
+if [[ -z "$e_param" ]] && [[ ! -z "$l_param" ]] && [[ -z "$n_param" ]]; then
+  echo "Error: -l parameter must be paired with -e or -n" >&2
+  echo "$HELP"
+  exit 1
+fi
+
+# Invalid combination check
+if [[ ! -z $e_param ]] && [[ ! -z $n_param ]]; then
+  echo "ERROR: Cannot combine -n with -e" >&2
+  echo "$HELP"
+  exit 1
+fi
+
+# Check existing lib
+if [[ ! -z "$e_param" ]]; then
+  if  [[ ! -d "${e_param/#~/$HOME}" ]]; then # this works!
+    echo "Error: existing library parameter - path does not exist" >&2
+    exit 1
+  fi
+fi
+
+LIBRARY=""
+
+# Only existing library was supplied
+if [[ ! -z $e_param ]] && [[ -z $l_param ]] && [[ -z $n_param ]]; then
+  LIBRARY=$e_param
+fi
+
+# Install new lib
+if [ ! -z $n_param ]; then
+  INSTALL_TARGET=""
+  if [ -z $l_param ]; then
+    # If local path for project is not supplied - use as INSTALL_TARGET Arduino libraries path
+    INSTALL_TARGET=$ARDUINO_LIBS_PATH/$(basename "$n_param")
+  else
+    INSTALL_TARGET=$l_param/components/$(basename "$n_param")
+    if [ ! -d "$l_param/components" ]; then
+      echo "Folder components does not exist yet: mkdir -p "$l_param/components""
+      mkdir -p "$l_param/components"
+    fi
+  fi
+  # clone the new lib
+  echo "Cloning: git clone --recursive $n_param $INSTALL_TARGET"
+  git clone --recursive $n_param $INSTALL_TARGET
+  LIBRARY=$INSTALL_TARGET
+fi
+
+# Copy existing lib to local project
+if [[ ! -z $e_param ]] && [[ ! -z $l_param ]]; then
+  if [ ! -d "$l_param/components" ]; then
+    echo "Folder components does not exist yet: mkdir -p "$l_param/components""
+    mkdir -p "$l_param/components"
+  fi
+  echo "Copy from $e_param to $l_param"
+  echo "cp -r $e_param $l_param/components/$(basename "$e_param")"
+  cp -r $e_param $l_param/components/$(basename "$e_param")
+  LIBRARY=$l_param/components/$(basename "$e_param")
+fi
+
+
+if [ -z "$LIBRARY" ]; then
+  echo "ERROR: No library path" >&2
+  exit 1
+fi
+
+# 1. get the source list:
+FILES=$(find $LIBRARY -name '*.c' -o -name '*.cpp' |  xargs -I{} basename {})
+
+# Fresh start
+if [ -f $LIBRARY/CMakeLists.txt ]; then
+  rm $LIBRARY/CMakeLists.txt
+  touch $LIBRARY/CMakeLists.txt
+fi
+
+# Generate CMakeLists.txt
+echo "idf_component_register(SRCS $(echo $FILES | sed -e 's/ /" "/g' | sed -e 's/^/"/' -e 's/$/"/')" >> $LIBRARY/CMakeLists.txt
+echo "                       INCLUDE_DIRS \".\"" >> $LIBRARY/CMakeLists.txt
+echo "                       REQUIRES \"arduino-esp32\"" >> $LIBRARY/CMakeLists.txt
+echo "                       )" >> $LIBRARY/CMakeLists.txt