diff --git a/.github/workflows/lib.json b/.github/workflows/lib.json new file mode 100644 index 00000000000..3b21a715271 --- /dev/null +++ b/.github/workflows/lib.json @@ -0,0 +1,37 @@ +[ + { + "library": "Adafruit NeoPixel", + "exclude_targets": null, + "sketches": [ + {"name": "strandtest", "path": "~/Arduino/libraries/Adafruit_NeoPixel/examples/strandtest/strandtest.ino"} + ] + }, + { + "library": "FastLED", + "exclude_targets": null, + "sketches": [ + {"name": "Blink", "path": "~/Arduino/libraries/FastLED/examples/Blink/Blink.ino"} + ] + }, + { + "library": "IRremote", + "exclude_targets": null, + "sketches": [ + {"name": "SendDemo", "path": "~/Arduino/libraries/IRremote/examples/SendDemo/SendDemo.ino"} + ] + }, + { + "library": "ESP32Servo", + "exclude_targets": null, + "sketches": [ + {"name": "Knob", "path": "~/Arduino/libraries/ESP32Servo/examples/Knob/Knob.ino"} + ] + }, + { + "library": "ArduinoBLE", + "exclude_targets": ["esp32s2"], + "sketches": [ + {"name": "Scan", "path": "~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino"} + ] + } +] diff --git a/.github/workflows/lib.yml b/.github/workflows/lib.yml new file mode 100644 index 00000000000..6de2bd926ba --- /dev/null +++ b/.github/workflows/lib.yml @@ -0,0 +1,165 @@ +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 +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: + # Libraries list to be installed + UNIVERSAL_LIBRARIES: | + - source-path: ./ + - name: Adafruit NeoPixel + - name: FastLED + - name: IRremote + - name: ESP32Servo + + # Libs with no compilable example found + # - name: Blynk + + # 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 + + strategy: + matrix: + fqbn: + - espressif:esp32:esp32 + - espressif:esp32:esp32s2 + - espressif:esp32:esp32c3 + - espressif:esp32:esp32s3 + + # compile only the libraries/examples compatible with specific chip + # use when some chip dont have the peripheral which is used in library (e.g. ESP32-S2 dont have BLE, so it is not tested) + 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 + + steps: + # This step makes the contents of the repository available to the workflow + - name: Checkout repository + uses: actions/checkout@v3 + + # Install Arduino ESP32 core, because compile-sketch wont call get.py + - name: Install Arduino ESP32 core + run: | + bash .github/scripts/install-arduino-core-esp32.sh + + # For more information: https://github.com/arduino/compile-sketches#readme + - name: Compile sketch + uses: P-R-O-C-H-Y/compile-sketches@main + with: + platforms: | + - source-path: '.' + name: "espressif:esp32" + fqbn: ${{ matrix.fqbn }} + libraries: | + ${{ env.UNIVERSAL_LIBRARIES }} + ${{ matrix.additional-libraries }} + sketch-paths: | + ${{ env.UNIVERSAL_SKETCHES }} + ${{ matrix.additional-sketches }} + 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/.github/workflows/lib_v2.yml b/.github/workflows/lib_v2.yml new file mode 100644 index 00000000000..338ab17399a --- /dev/null +++ b/.github/workflows/lib_v2.yml @@ -0,0 +1,219 @@ +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' + + push: +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 +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: + # How should be the ESP32 Arduino core installed + BOARD_MANAGER: | + - name: "esp32:esp32" + source-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json + version: 2.0.3 + + REPOSITORY: | + - source-path: '.' + name: "esp32:esp32" + + GITHUB_URL: | + - name: "esp32:esp32" + source-url: "espressif/arduino-esp32.git" + version: 2.0.7 + + strategy: + matrix: + target: + - esp32 + - esp32s2 + - esp32c3 + - esp32s3 + + include: + - target: esp32 + fqbn: esp32:esp32:esp32 + - target: esp32s2 + fqbn: esp32:esp32:esp32s2 + - target: esp32c3 + fqbn: esp32:esp32:esp32c3 + - target: esp32s3 + fqbn: esp32:esp32:esp32s3 + + + steps: + # This step makes the contents of the repository available to the workflow + - name: Checkout repository + uses: actions/checkout@v3 + + - name: JSON to variables + uses: rgarcia-phi/json-to-variables@v1.1.0 + with: + filename: '.github/workflows/lib.json' + prefix: test + masked: true + + - name: Show output + run: echo "The time was ${{ env.test_library }}, ${{ env.test_sketches_0_name }}" + + - name: Set up Python + uses: actions/setup-python@v2 + with: + python-version: '3.x' + + - name: Install dependencies + run: python3 -m pip install jsonschema + + - name: Load JSON file to variable + id: load-json + run: echo "::set-output name=json::$(cat .github/workflows/lib.json)" + + - name: Parse JSON and set environment variables + run: | + #!/usr/bin/env python3 + import json + data = json.loads('${{ steps.load-json.outputs.json }}') + + for item in data: + library = item['library'] + exclude_targets = item['exclude_targets'] + sketches = item['sketches'] + name = sketches[0]['name'] + path = sketches[0]['path'] + + # Set environment variables for each item + env_var_library = f'{library.replace(" ", "_").upper()}_LIBRARY' + env_var_exclude_targets = f'{library.replace(" ", "_").upper()}_EXCLUDE_TARGETS' + env_var_sketch_name = f'{library.replace(" ", "_").upper()}_SKETCH_NAME' + env_var_sketch_path = f'{library.replace(" ", "_").upper()}_SKETCH_PATH' + + env_var_library_value = f'{library}' + env_var_exclude_targets_value = f'{exclude_targets}' + env_var_sketch_name_value = f'{sketch_name} + env_var_sketch_path_value = f'{sketch_path} + + echo ${{ env.env_var_library_value }} + echo ${{ env.env_var_exclude_targets_value }} + echo ${{ env.env_var_sketch_name_value }} + echo ${{ env.env_var_sketch_path_value }} + + + # Install Arduino ESP32 core -> move to compile-sketch + #- name: Install Arduino ESP32 core + # run: | + # bash .github/scripts/install-arduino-core-esp32.sh + + # For more information: https://github.com/arduino/compile-sketches#readme + - name: Compile sketch + uses: P-R-O-C-H-Y/compile-sketches@main + with: + platforms: | + ${{ env.BOARD_MANAGER }} + # ${{ env.REPOSITORY }} + # ${{ env.GITHUB_URL }} + fqbn: ${{ matrix.fqbn }} + libraries: | + # ${{ env.UNIVERSAL_LIBRARIES }} + # ${{ matrix.additional-libraries }} + sketch-paths: | + # ${{ env.UNIVERSAL_SKETCHES }} + # ${{ matrix.additional-sketches }} + 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 == 'push' #'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 + + +# - name: "Read JSON" +# uses: actions/github-script@v6 +# id: check-env +# with: +# result-encoding: string +# script: | +# try { +# const fs = require('fs') +# const jsonString = fs.readFileSync('./dir/file.json') +# var apps = JSON.parse(jsonString) +# } catch(err) { +# core.error("Error while reading or parsing the JSON") +# core.setFailed(err) +# } \ No newline at end of file diff --git a/README.md b/README.md index 72496f2d170..9af69770630 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 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) +![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=Libraries_CI_test&event=push)](https://github.com/espressif/arduino-esp32/blob/Libraries_CI_test/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 +51,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