espressif · P-R-O-C-H-Y · Mar 14, 2023 · Mar 14, 2023 · Mar 14, 2023 · Mar 14, 2023
diff --git a/.github/workflows/lib.json b/.github/workflows/lib.json
@@ -0,0 +1,43 @@
+[
+    {
+        "name": "Adafruit NeoPixel",
+        "version": "1.10.6",
+        "exclude_targets": [],
+        "sketch_path": [
+            "~/Arduino/libraries/Adafruit_NeoPixel/examples/strandtest/strandtest.ino"
+        ]
+    },
+    {
+        "name": "FastLED",
+        "exclude_targets": [],
+        "sketch_path": [
+            "~/Arduino/libraries/FastLED/examples/Blink/Blink.ino"
+        ]
+    },
+    {
+        "name": "IRremote",
+        "exclude_targets": [],
+        "sketch_path": [
+            "~/Arduino/libraries/IRremote/examples/SendDemo/SendDemo.ino"
+        ]
+    },
+    {
+        "name": "ESP32Servo",
+        "exclude_targets": [],
+        "sketch_path": [
+            "~/Arduino/libraries/ESP32Servo/examples/Knob/Knob.ino",
+            "~/Arduino/libraries/ESP32Servo/examples/Sweep/Sweep.ino",
+            "~/Arduino/libraries/ESP32Servo/examples/PWMExample/PWMExample.ino",
+            "~/Arduino/libraries/ESP32Servo/examples/Multiple-Servo-Example-Arduino/Multiple-Servo-Example-Arduino.ino"
+        ]
+    },
+    {
+        "name": "ArduinoBLE",
+        "exclude_targets": [
+            "esp32s2"
+        ],
+        "sketch_path": [
+            "~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino"
+        ]
+    }
+]
diff --git a/.github/workflows/lib.yml b/.github/workflows/lib.yml
@@ -0,0 +1,147 @@
+name: External Libraries Test V2
+
+# The workflow will run on schedule and labeled pull requests
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, labeled]
+
+  # Schedule weekly builds on every Sunday at 4 am
+  schedule:
+    - cron: '0 4 * * SUN' 
+
+env:
+  # It's convenient to set variables for values used multiple times in the workflow
+  SKETCHES_REPORTS_PATH: libraries-report
+  SKETCHES_REPORTS_ARTIFACT_NAME: libraries-report
+  RESULT_LIBRARY_TEST_FILE: LIBRARIES_TEST.md
+  JSON_LIBRARY_LIST_FILE: .github/workflows/lib.json
+jobs:
+  compile-sketch:
+    if: |
+      contains(github.event.pull_request.labels.*.name, 'lib_test') ||
+      (github.event_name == 'schedule' && github.repository == 'espressif/arduino-esp32')
+    runs-on: ubuntu-latest
+
+    env:
+      # Options of how will be the ESP32 Arduino core installed
+      BOARD_MANAGER: |
+        - name: "espressif:esp32"
+          source-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_dev_index.json
+          version: 2.0.7
+
+      REPOSITORY: |
+        - source-path: '.'
+          name: "espressif:esp32"
+
+      GITHUB_URL: |
+        - name: "espressif:esp32"
+          source-url: https://github.com/espressif/arduino-esp32.git
+          version: 2.0.7
+
+    strategy:
+      matrix:
+        target:
+          - esp32
+          - esp32s2
+          - esp32c3
+          - esp32s3
+
+        include:
+          - target: esp32
+            fqbn: espressif:esp32:esp32
+          - target: esp32s2
+            fqbn: espressif:esp32:esp32s2
+          - target: esp32c3
+            fqbn: espressif:esp32:esp32c3
+          - target: esp32s3
+            fqbn: espressif:esp32:esp32s3
+
+
+    steps:
+      # This step makes the contents of the repository available to the workflow
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      # Possible platforms input for compile-sketches
+      # ${{ env.BOARD_MANAGER }}
+      # ${{ env.GITHUB_URL }}
+      # ${{ env.REPOSITORY }}
+
+      - name: Compile sketch
+        uses: P-R-O-C-H-Y/compile-sketches@main
+        with:
+          platforms: |
+            ${{ env.GITHUB_URL }}
+          target: ${{ matrix.target }}
+          fqbn: ${{ matrix.fqbn }}
+          #libraries: commented as json file is used instead
+          #sketch-paths: commented as json file is used instead
+          use-json-file: true
+          json-path: ${{ env.JSON_LIBRARY_LIST_FILE }}
+          enable-deltas-report: true
+          sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
+          enable-warnings-report: true
+          #verbose: true
+          cli-compile-flags: |
+            - --warnings="all"
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
+          path: ${{ env.SKETCHES_REPORTS_PATH }}
+
+  report-comment:
+    needs: compile-sketch  # Wait for the compile job to finish to get the data for the report
+    if: github.event_name == 'pull_request' # Only run the job when the workflow is triggered by a pull request
+    runs-on: ubuntu-latest
+    steps:
+      # This step is needed to get the size data produced by the compile jobs
+      - name: Download sketches reports artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
+          path: ${{ env.SKETCHES_REPORTS_PATH }}
+
+      - name: Report results
+        uses: P-R-O-C-H-Y/report-size-deltas@main
+        with:
+          sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }}
+
+  report-to-file:
+    needs: compile-sketch  # Wait for the compile job to finish to get the data for the report
+    if: github.event_name == 'schedule' # Only run the job when the workflow is triggered by a schedule
+    runs-on: ubuntu-latest
+    steps:
+      # Check out repository
+      - name: Checkout repository    
+        uses: actions/checkout@v3
+
+      # This step is needed to get the size data produced by the compile jobs
+      - name: Download sketches reports artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
+          path: ${{ env.SKETCHES_REPORTS_PATH }}
+
+      - name: Report results
+        uses: P-R-O-C-H-Y/report-size-deltas@main
+        with:
+          sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }}
+          destination-file: ${{ env.RESULT_LIBRARY_TEST_FILE }}
+
+      - name: Append file with action URL
+        uses: DamianReeves/write-file-action@master
+        with:
+          path: ${{ env.RESULT_LIBRARY_TEST_FILE }}
+          contents: |
+            / [GitHub Action Link](https://github.com/${{github.repository}}/actions/runs/${{github.run_id}})
+          write-mode: append
+
+      - name: Push to github repo
+        run: |
+          git config user.name github-actions
+          git config user.email [email protected]
+          git add ${{ env.RESULT_LIBRARY_TEST_FILE }}
+          git commit -m "Generated External Libraries Test Results"
+          git push
diff --git a/README.md b/README.md
@@ -1,6 +1,7 @@
 # Arduino core for the ESP32, ESP32-S2, ESP32-S3 and ESP32-C3
 
 ![Build Status](https://github.com/espressif/arduino-esp32/workflows/ESP32%20Arduino%20CI/badge.svg) [![Documentation Status](https://readthedocs.com/projects/espressif-arduino-esp32/badge/?version=latest)](https://docs.espressif.com/projects/arduino-esp32/en/latest/?badge=latest)
+[![External Libraries Test](https://github.com/P-R-O-C-H-Y/arduino-esp32/actions/workflows/lib.yml/badge.svg?branch=Libraries_CI_test&event=push)](https://github.com/P-R-O-C-H-Y/arduino-esp32/actions/workflows/lib.yml?link=http://https://github.com/P-R-O-C-H-Y/arduino-esp32/LIBRARIES_TEST.md)
 
 ### Need help or have a question? Join the chat at [Gitter](https://gitter.im/espressif/arduino-esp32) or [open a new Discussion](https://github.com/espressif/arduino-esp32/discussions)
 
@@ -51,6 +52,11 @@ Before reporting an issue, make sure you've searched for similar one that was al
 
 Finally, if you are sure no one else had the issue, follow the **Issue template** or **Feature request template** while reporting any [new Issue](https://github.com/espressif/arduino-esp32/issues/new/choose).
 
+### External libraries compilation test
+
+We have set-up CI testing for external libraries for ESP32 Arduino core. You can check test results in file [LIBRARIES_TEST](https://github.com/espressif/arduino-esp32/blob/Libraries_CI_test/LIBRARIES_TEST.md). 
+For more information and how to add your library to the test see [external library testing](https://docs.espressif.com/projects/arduino-esp32/en/latest/external_library_test.html) in documentation.
+
 ### Contributing
 
 We welcome contributions to the Arduino ESP32 project!

diff --git a/docs/source/_static/cross.png b/docs/source/_static/cross.png
diff --git a/docs/source/_static/external_library_test_pr.png b/docs/source/_static/external_library_test_pr.png
diff --git a/docs/source/_static/external_library_test_schedule.png b/docs/source/_static/external_library_test_schedule.png
diff --git a/docs/source/_static/green_checkmark.png b/docs/source/_static/green_checkmark.png
diff --git a/docs/source/_static/warning.png b/docs/source/_static/warning.png
diff --git a/docs/source/external_libraries_test.rst b/docs/source/external_libraries_test.rst
@@ -0,0 +1,140 @@
+##########################
+External Libraries Testing
+##########################
+
+About
+-----
+
+External libraries testing is a compilation test for listed libraries on arduino-esp32 master branch. The test was made for users, so they can check which libraries are compiling without errors on which SoC.
+External libraries test is running periodicaly (once a week) agains master branch and can also run on PR by adding a label ``lib_test``.
+The test is running on all supported ESP32 chips.
+
+.. note:: 
+  As the test is just a compilation of example, that does not guarrantee that the library/sketch will run without any problems after flashing it on your device.
+
+How to Add Library to Test
+--------------------------
+
+.. note:: 
+  Library must be listed in Arduino Library Manager. 
+  If you want to add your library to the Arduino Library Manager see `Adding a library to library manager <https://github.com/arduino/library-registry#adding-a-library-to-library-manager>`_
+
+Adding a library is divided to 2 categories:
+
+1. Adding a library which can work on all chips (eg. all chips have support for the peripherals used)
+2. Adding a chip specific library which cannot work on all chips (e.g. BLE / Ethernet peripheral is not supported by all chips)
+
+For both categories only 2 simple steps are required to add a library to the test workflow file ``lib.yml``.
+Workflow file is located in ``./github/workflows/lib.yml``.
+
+Library uses peripheral which is has all chips
+**********************************************
+
+* Add new line with the library name to the list of ``UNIVERSAL_LIBRARIES`` in ``lib.yml`` file:
+
+  .. code-block:: yaml
+
+    # Libraries list to be installed
+    UNIVERSAL_LIBRARIES: |
+      - source-path: ./
+      - name: Adafruit NeoPixel
+      - name: FastLED
+      - name: IRremote
+      - name: ESP32Servo
+
+* Add new line with the sketch path to the list of ``UNIVERSAL_SKETCHES`` in ``lib.yml`` file (sketch needs to be from the examples of the library):
+
+  .. code-block:: yaml
+
+    # List of sketches to build (1 for each library)
+    UNIVERSAL_SKETCHES: 
+      ~/Arduino/libraries/Adafruit_NeoPixel/examples/strandtest/strandtest.ino
+      ~/Arduino/libraries/FastLED/examples/Blink/Blink.ino
+      ~/Arduino/libraries/IRremote/examples/SendDemo/SendDemo.ino
+      ~/Arduino/libraries/ESP32Servo/examples/Knob/Knob.ino
+
+Library uses peripheral specific to some chips
+**********************************************
+
+* Add new line with the library name to the list of ``additional-libraries`` under each SOC which supports the peripheral used by library in ``lib.yml`` file:
+
+* Add new line with the sketch path to the list of ``additional-sketches`` under each SOC which supports the peripheral in ``lib.yml`` file 
+   (sketch needs to be from the examples of the library):
+
+  Example for adding ``ArduinoBLE`` library (ESP32-S2 dont have BLE peripheral)
+
+  .. code-block:: yaml
+
+    include:
+      - fqbn: espressif:esp32:esp32
+        additional-libraries: |
+          - name: ArduinoBLE
+        additional-sketches: |
+          ~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino
+      - fqbn: espressif:esp32:esp32s2
+        additional-libraries:
+        additional-sketches:
+      - fqbn: espressif:esp32:esp32c3
+        additional-libraries: |
+          - name: ArduinoBLE
+        additional-sketches: |
+          ~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino
+      - fqbn: espressif:esp32:esp32s3
+        additional-libraries: |
+          - name: ArduinoBLE
+        additional-sketches: |
+          ~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino
+
+Common part
+***********
+
+* Open a PR with the changes and someone from Espressif team will add a label ``lib_test`` to the PR and CI will run the test to check, if the addition is fine and library / example are compiling.
+
+* After merging your PR, the next scheduled test will test your library and add the results to the `LIBRARIES_TEST.md`_.
+
+Test Results
+------------
+
+Icons meaning
+*************
+
+* |success| - Compilation was successful.
+
+* |warning| - Compilation was successful with some warnings. (number of warnings is printed next to the icon)
+
+* |fail| - Compilation failed.
+
+* ``N/A`` - Not tested.
+
+Scheduled test result
+*********************
+
+You can check the results in `LIBRARIES_TEST.md`_.
+
+The results file example:
+
+.. image:: _static/external_library_test_schedule.png
+  :width: 600
+
+Pull Request test result
+************************
+
+If the test run on Pull Request, it will compile all libraries and sketches 2 times (before/after changes in PR) to see, if the PR is breaking/fixing libraries.
+In the table the results are in order ``BEFORE -> AFTER``.
+
+.. image:: _static/external_library_test_pr.png
+  :width: 600
+
+.. |success| image:: _static/green_checkmark.png
+   :height: 2ex
+   :class: no-scaled-link
+
+.. |warning| image:: _static/warning.png
+   :height: 2ex
+   :class: no-scaled-link
+
+.. |fail| image:: _static/cross.png
+   :height: 2ex
+   :class: no-scaled-link
+
+.. _LIBRARIES_TEST.md: https://github.com/espressif/arduino-esp32/LIBRARIES_TEST.md
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -19,3 +19,4 @@ Here you will find all the relevant information about the project.
    FAQ <faq>
    Troubleshooting <troubleshooting>
    Contributing <contributing>
+   External Libraries Testing <external_libraries_test>