diff --git a/.github/workflows/lib.json b/.github/workflows/lib.json new file mode 100644 index 00000000000..222de0f8849 --- /dev/null +++ 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" + ] + } +] \ No newline at end of file diff --git a/.github/workflows/lib.yml b/.github/workflows/lib.yml new file mode 100644 index 00000000000..8c87214ba07 --- /dev/null +++ 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 github-actions@github.com + 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 index 72496f2d170..8d2dd9796c5 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/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 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..e305c41d276 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..d7c9bbc0b76 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..55345c7d1f2 --- /dev/null +++ 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 `_ + +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 \ 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