diff --git a/.github/workflows/lib.json b/.github/workflows/lib.json new file mode 100644 index 00000000000..064d4967f3c --- /dev/null +++ b/.github/workflows/lib.json @@ -0,0 +1,56 @@ +[ + { + "name": "Adafruit NeoPixel", + "version": "1.10.6", + "exclude_targets": [], + "sketch_path": [ + "~/Arduino/libraries/Adafruit_NeoPixel/examples/strandtest/strandtest.ino" + ] + }, + { + "name": "ArduinoBLE", + "exclude_targets": [ + "esp32s2" + ], + "sketch_path": [ + "~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.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" + ] + }, + { + "source-url": "https://github.com/me-no-dev/ESPAsyncWebServer.git", + "required-libs": [ + {"source-url": "https://github.com/me-no-dev/AsyncTCP.git"} + ], + "exclude_targets": [], + "sketch_path": [ + "~/Arduino/libraries/ESPAsyncWebServer/examples/CaptivePortal/CaptivePortal.ino", + "~/Arduino/libraries/ESPAsyncWebServer/examples/ESP_AsyncFSBrowser/ESP_AsyncFSBrowser.ino", + "~/Arduino/libraries/ESPAsyncWebServer/examples/regex_patterns/regex_patterns.ino", + "~/Arduino/libraries/ESPAsyncWebServer/examples/simple_server/simple_server.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" + ] + } +] \ No newline at end of file diff --git a/.github/workflows/lib.yml b/.github/workflows/lib.yml new file mode 100644 index 00000000000..8f7756abaf3 --- /dev/null +++ b/.github/workflows/lib.yml @@ -0,0 +1,128 @@ +name: External Libraries Test + +# 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: + REPOSITORY: | + - source-path: '.' + name: "espressif:esp32" + + 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 + + - name: Compile sketch + uses: P-R-O-C-H-Y/compile-sketches@main + with: + platforms: | + ${{ env.REPOSITORY }} + target: ${{ matrix.target }} + fqbn: ${{ matrix.fqbn }} + 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 + 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 github-actions@github.com + git add ${{ env.RESULT_LIBRARY_TEST_FILE }} + git commit -m "Generated External Libraries Test Results" + git push diff --git a/LIBRARIES_TEST.md b/LIBRARIES_TEST.md new file mode 100644 index 00000000000..013ed0d36bb --- /dev/null +++ b/LIBRARIES_TEST.md @@ -0,0 +1 @@ +Empty file \ No newline at end of file diff --git a/README.md b/README.md index 72496f2d170..8536fab7c1e 100644 --- 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/espressif/arduino-esp32/actions/workflows/lib.yml/badge.svg?branch=master&event=schedule)](https://github.com/espressif/arduino-esp32/actions/workflows/lib.yml?link=http://https://github.com/espressif/arduino-esp32/blob/master/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 the file [LIBRARIES_TEST](https://github.com/espressif/arduino-esp32/blob/master/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 the documentation. + ### Contributing We welcome contributions to the Arduino ESP32 project! diff --git a/docs/source/_static/cross.png b/docs/source/_static/cross.png new file mode 100644 index 00000000000..f3e495e803e Binary files /dev/null and b/docs/source/_static/cross.png differ diff --git a/docs/source/_static/external_library_test_pr.png b/docs/source/_static/external_library_test_pr.png new file mode 100644 index 00000000000..987ad9de752 Binary files /dev/null and b/docs/source/_static/external_library_test_pr.png differ diff --git a/docs/source/_static/external_library_test_schedule.png b/docs/source/_static/external_library_test_schedule.png new file mode 100644 index 00000000000..19288835cfc Binary files /dev/null and b/docs/source/_static/external_library_test_schedule.png differ diff --git a/docs/source/_static/green_checkmark.png b/docs/source/_static/green_checkmark.png new file mode 100644 index 00000000000..5fc5722651f Binary files /dev/null and b/docs/source/_static/green_checkmark.png differ diff --git a/docs/source/_static/warning.png b/docs/source/_static/warning.png new file mode 100644 index 00000000000..e2dd14419ba Binary files /dev/null and b/docs/source/_static/warning.png differ diff --git a/docs/source/external_libraries_test.rst b/docs/source/external_libraries_test.rst new file mode 100644 index 00000000000..b683e8b6f58 --- /dev/null +++ b/docs/source/external_libraries_test.rst @@ -0,0 +1,132 @@ +########################## +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 periodically (once a week) against 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 guarantee that the library/sketch will run without any problems after flashing it on your device. + +How to Add Library to Test +-------------------------- + +To add a library to the CI test you need to add your library to the `lib.json`_. file located in ``./github/workflows/``. + +.. note:: + Please add the libraries to the `lib.json`_ in alphabetical order, thanks. + +List of parameters: +******************* + +Where the library will be installed from (use only 1 option): + +* ``name`` - Name of the Library in Arduino Library Manager. +* ``source-url`` - URL to the library github repository (example: "https://github.com/Arduino-IRremote/Arduino-IRremote.git"). Use when your Library is not listed in Arduino Library Manager. + +Required: + +* ``exclude_targets`` - List of targets to be excluded from testing. Use only when the SoC dont support used peripheral. +* ``sketch_path`` - Path / paths to the sketch / sketches to be tested. + +Optional: + +* ``version`` - Version of the library. +* ``required-libs`` - Libraries that are necessary to be installed to compile the tested library. +* ``destination-name`` - Folder name used for the installation of library (use only when needed). + + +Example of library addition from Arduino Library Manager with ESP32-S2 excluded: +******************************************************************************** + + .. code-block:: json + + { + "name": "ArduinoBLE", + "exclude_targets": [ + "esp32s2" + ], + "sketch_path": [ + "~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino" + ] + } + +Example of library addition from Github URL with required library: +****************************************************************** + + .. code-block:: json + + { + "source-url": "https://github.com/me-no-dev/ESPAsyncWebServer.git", + "required-libs": [ + {"source-url": "https://github.com/me-no-dev/AsyncTCP.git"} + ], + "exclude_targets": [], + "sketch_path": [ + "~/Arduino/libraries/ESPAsyncWebServer/examples/CaptivePortal/CaptivePortal.ino", + "~/Arduino/libraries/ESPAsyncWebServer/examples/ESP_AsyncFSBrowser/ESP_AsyncFSBrowser.ino", + "~/Arduino/libraries/ESPAsyncWebServer/examples/regex_patterns/regex_patterns.ino", + "~/Arduino/libraries/ESPAsyncWebServer/examples/simple_server/simple_server.ino" + ] + }, + +Submit a PR +*********** + +* 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 the library/example is 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 +************* + +There is a number before each icon, which means the number of examples which were compiled with that result. + +* |success| - Compilation was successful. + +* |warning| - Compilation was successful, but some warnings occurs. + +* |fail| - Compilation failed. + +* ``N/A`` - Not tested (target is in exclude_targets list). + +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 +.. _lib.json: https://github.com/espressif/arduino-esp32/.github/workflow/lib.json \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 48f30396270..f504dc342e0 100644 --- 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 Troubleshooting Contributing + External Libraries Testing