Skip to content

Commit df75f38

Browse files
P-R-O-C-H-YP-R-O-C-H-Y
authored
[CI] External libraries compilation test (#8003)
* Workflow final + docs added Delete LIBRARY_TEST.md Update readme + documentation Generated External Libraries Test Results Updated docs Generated External Libraries Test Results revert last commit DOnt install arduino-core manually Update external_libraries_test.rst Generated External Libraries Test Results Align FQBNs to platform name use manula platform installation Generated External Libraries Test Results remove verbose remove - before sketch path Add libs and examples for specific chip Generated External Libraries Test Results Generated External Libraries Test Results Update README.md Generated External Libraries Test Results Update README.md Update README.md Generated External Libraries Test Results change name of GH action replace - for / Generated External Libraries Test Results Generated External Libraries Test Results Update lib.yml Update lib.yml Generated External Libraries Test Results remove types from pull_rewuest add pull to lib.yml Generated External Libraries Test Results add back deltas_report Update LIBRARY_TEST.md add verbose logs remove deltas report Generated External Libraries Test Results Change from schedule to push for testing add P-R-O-C-H-Y repo to cron job rename workflow Update LIBRARY_TEST.md Update LIBRARY_TEST.md Edit URL Generated External Libraries Test Results remove unused ymls + run job on schedule generated Add action link push only result file generated fix names fix workflow run workflow on push Add report to file action remove separator fix example paths fix library name yaml list of examples edit update universal sketches examples path fix update example paths Add ESP32Servo warnings -> all change warnings to "default" fix library name fix list add matrix to compile sketches test compile for only 1 chip remove GPIO example use edited action Add Blynk library use v1 print arduino cli version fix listing update libs list fix remove if fix typo fix path path test list fix fix folder creating add install IDE list fix fix missing run command Added V3 lib test + script for lib install fix typo add platform updated on: Lib testing v2 fix fqbn test all chips typo fix replace blynk with Adafruit Neopixel change blynk example fix yml format add action name Add report for PR Enable warnings report changed position typo test remove dbg level add log level option split command typo typo add empty space change position of cli flags fix typo cli compile flags not marking warning as error Add new lib+example install core manually Install core by compile-sketch fix url->path fix typo Install core from repo remove external lib checkout add lib example update board change platform name change platform name use BoardManager update example update example use repo as platform Initial commit Update README.md Update README.md * fix readme links * added JSON + lib_v2 YAML * Update lib_v2.yml * Update lib_v2.yml * Update lib_v2.yml * Update lib_v2.yml * Update lib_v2.yml * Update lib_v2.yml * Update lib_v2.yml * update JSON file * Added json file * Update lib.yml * Update lib_v2.yml * Update lib_v2.yml * change JSON * edit json + add version * edit json * update version * fix path * update fqbn platform name * add empty test result file * Add latest changes * Update docs * Update docs + clean YAML fifle * Add ESPAsyncWebServer library * Add test multiple required libs (will revert) * Update docs + json * Update lib.yml * Fix typos in docs * fix readme links
1 parent 7fd956d commit df75f38

11 files changed

+324
-0
lines changed

‎.github/workflows/lib.json

+56
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
[
2+
{
3+
"name": "Adafruit NeoPixel",
4+
"version": "1.10.6",
5+
"exclude_targets": [],
6+
"sketch_path": [
7+
"~/Arduino/libraries/Adafruit_NeoPixel/examples/strandtest/strandtest.ino"
8+
]
9+
},
10+
{
11+
"name": "ArduinoBLE",
12+
"exclude_targets": [
13+
"esp32s2"
14+
],
15+
"sketch_path": [
16+
"~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino"
17+
]
18+
},
19+
{
20+
"name": "ESP32Servo",
21+
"exclude_targets": [],
22+
"sketch_path": [
23+
"~/Arduino/libraries/ESP32Servo/examples/Knob/Knob.ino",
24+
"~/Arduino/libraries/ESP32Servo/examples/Sweep/Sweep.ino",
25+
"~/Arduino/libraries/ESP32Servo/examples/PWMExample/PWMExample.ino",
26+
"~/Arduino/libraries/ESP32Servo/examples/Multiple-Servo-Example-Arduino/Multiple-Servo-Example-Arduino.ino"
27+
]
28+
},
29+
{
30+
"source-url": "https://github.com/me-no-dev/ESPAsyncWebServer.git",
31+
"required-libs": [
32+
{"source-url": "https://github.com/me-no-dev/AsyncTCP.git"}
33+
],
34+
"exclude_targets": [],
35+
"sketch_path": [
36+
"~/Arduino/libraries/ESPAsyncWebServer/examples/CaptivePortal/CaptivePortal.ino",
37+
"~/Arduino/libraries/ESPAsyncWebServer/examples/ESP_AsyncFSBrowser/ESP_AsyncFSBrowser.ino",
38+
"~/Arduino/libraries/ESPAsyncWebServer/examples/regex_patterns/regex_patterns.ino",
39+
"~/Arduino/libraries/ESPAsyncWebServer/examples/simple_server/simple_server.ino"
40+
]
41+
},
42+
{
43+
"name": "FastLED",
44+
"exclude_targets": [],
45+
"sketch_path": [
46+
"~/Arduino/libraries/FastLED/examples/Blink/Blink.ino"
47+
]
48+
},
49+
{
50+
"name": "IRremote",
51+
"exclude_targets": [],
52+
"sketch_path": [
53+
"~/Arduino/libraries/IRremote/examples/SendDemo/SendDemo.ino"
54+
]
55+
}
56+
]

‎.github/workflows/lib.yml

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
name: External Libraries Test
2+
3+
# The workflow will run on schedule and labeled pull requests
4+
on:
5+
pull_request:
6+
types: [opened, reopened, synchronize, labeled]
7+
8+
# Schedule weekly builds on every Sunday at 4 am
9+
schedule:
10+
- cron: '0 4 * * SUN'
11+
12+
env:
13+
# It's convenient to set variables for values used multiple times in the workflow
14+
SKETCHES_REPORTS_PATH: libraries-report
15+
SKETCHES_REPORTS_ARTIFACT_NAME: libraries-report
16+
RESULT_LIBRARY_TEST_FILE: LIBRARIES_TEST.md
17+
JSON_LIBRARY_LIST_FILE: .github/workflows/lib.json
18+
jobs:
19+
compile-sketch:
20+
if: |
21+
contains(github.event.pull_request.labels.*.name, 'lib_test') ||
22+
(github.event_name == 'schedule' && github.repository == 'espressif/arduino-esp32')
23+
runs-on: ubuntu-latest
24+
25+
env:
26+
REPOSITORY: |
27+
- source-path: '.'
28+
name: "espressif:esp32"
29+
30+
strategy:
31+
matrix:
32+
target:
33+
- esp32
34+
- esp32s2
35+
- esp32c3
36+
- esp32s3
37+
38+
include:
39+
- target: esp32
40+
fqbn: espressif:esp32:esp32
41+
- target: esp32s2
42+
fqbn: espressif:esp32:esp32s2
43+
- target: esp32c3
44+
fqbn: espressif:esp32:esp32c3
45+
- target: esp32s3
46+
fqbn: espressif:esp32:esp32s3
47+
48+
49+
steps:
50+
# This step makes the contents of the repository available to the workflow
51+
- name: Checkout repository
52+
uses: actions/checkout@v3
53+
54+
- name: Compile sketch
55+
uses: P-R-O-C-H-Y/compile-sketches@main
56+
with:
57+
platforms: |
58+
${{ env.REPOSITORY }}
59+
target: ${{ matrix.target }}
60+
fqbn: ${{ matrix.fqbn }}
61+
use-json-file: true
62+
json-path: ${{ env.JSON_LIBRARY_LIST_FILE }}
63+
enable-deltas-report: true
64+
sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }}
65+
enable-warnings-report: true
66+
cli-compile-flags: |
67+
- --warnings="all"
68+
69+
- name: Upload artifact
70+
uses: actions/upload-artifact@v3
71+
with:
72+
name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
73+
path: ${{ env.SKETCHES_REPORTS_PATH }}
74+
75+
report-comment:
76+
needs: compile-sketch # Wait for the compile job to finish to get the data for the report
77+
if: github.event_name == 'pull_request' # Only run the job when the workflow is triggered by a pull request
78+
runs-on: ubuntu-latest
79+
steps:
80+
# This step is needed to get the size data produced by the compile jobs
81+
- name: Download sketches reports artifact
82+
uses: actions/download-artifact@v3
83+
with:
84+
name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
85+
path: ${{ env.SKETCHES_REPORTS_PATH }}
86+
87+
- name: Report results
88+
uses: P-R-O-C-H-Y/report-size-deltas@main
89+
with:
90+
sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }}
91+
92+
report-to-file:
93+
needs: compile-sketch # Wait for the compile job to finish to get the data for the report
94+
if: github.event_name == 'schedule' # Only run the job when the workflow is triggered by a schedule
95+
runs-on: ubuntu-latest
96+
steps:
97+
# Check out repository
98+
- name: Checkout repository
99+
uses: actions/checkout@v3
100+
101+
# This step is needed to get the size data produced by the compile jobs
102+
- name: Download sketches reports artifact
103+
uses: actions/download-artifact@v3
104+
with:
105+
name: ${{ env.SKETCHES_REPORTS_ARTIFACT_NAME }}
106+
path: ${{ env.SKETCHES_REPORTS_PATH }}
107+
108+
- name: Report results
109+
uses: P-R-O-C-H-Y/report-size-deltas@main
110+
with:
111+
sketches-reports-source: ${{ env.SKETCHES_REPORTS_PATH }}
112+
destination-file: ${{ env.RESULT_LIBRARY_TEST_FILE }}
113+
114+
- name: Append file with action URL
115+
uses: DamianReeves/write-file-action@master
116+
with:
117+
path: ${{ env.RESULT_LIBRARY_TEST_FILE }}
118+
contents: |
119+
/ [GitHub Action Link](https://github.com/${{github.repository}}/actions/runs/${{github.run_id}})
120+
write-mode: append
121+
122+
- name: Push to github repo
123+
run: |
124+
git config user.name github-actions
125+
git config user.email github-actions@github.com
126+
git add ${{ env.RESULT_LIBRARY_TEST_FILE }}
127+
git commit -m "Generated External Libraries Test Results"
128+
git push

‎LIBRARIES_TEST.md

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Empty file

‎README.md

+6
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Arduino core for the ESP32, ESP32-S2, ESP32-S3 and ESP32-C3
22

33
![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)
4+
[![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)
45

56
### 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)
67

@@ -51,6 +52,11 @@ Before reporting an issue, make sure you've searched for similar one that was al
5152

5253
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).
5354

55+
### External libraries compilation test
56+
57+
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).
58+
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.
59+
5460
### Contributing
5561

5662
We welcome contributions to the Arduino ESP32 project!

‎docs/source/_static/cross.png

3.99 KB
Loading

‎docs/source/_static/external_library_test_pr.png

170 KB
Loading

‎docs/source/_static/external_library_test_schedule.png

115 KB
Loading

‎docs/source/_static/green_checkmark.png

4.2 KB
Loading

‎docs/source/_static/warning.png

3.6 KB
Loading

‎docs/source/external_libraries_test.rst

+132
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
##########################
2+
External Libraries Testing
3+
##########################
4+
5+
About
6+
-----
7+
8+
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.
9+
External libraries test is running periodically (once a week) against master branch and can also run on PR by adding a label ``lib_test``.
10+
The test is running on all supported ESP32 chips.
11+
12+
.. note::
13+
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.
14+
15+
How to Add Library to Test
16+
--------------------------
17+
18+
To add a library to the CI test you need to add your library to the `lib.json`_. file located in ``./github/workflows/``.
19+
20+
.. note::
21+
Please add the libraries to the `lib.json`_ in alphabetical order, thanks.
22+
23+
List of parameters:
24+
*******************
25+
26+
Where the library will be installed from (use only 1 option):
27+
28+
* ``name`` - Name of the Library in Arduino Library Manager.
29+
* ``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.
30+
31+
Required:
32+
33+
* ``exclude_targets`` - List of targets to be excluded from testing. Use only when the SoC dont support used peripheral.
34+
* ``sketch_path`` - Path / paths to the sketch / sketches to be tested.
35+
36+
Optional:
37+
38+
* ``version`` - Version of the library.
39+
* ``required-libs`` - Libraries that are necessary to be installed to compile the tested library.
40+
* ``destination-name`` - Folder name used for the installation of library (use only when needed).
41+
42+
43+
Example of library addition from Arduino Library Manager with ESP32-S2 excluded:
44+
********************************************************************************
45+
46+
.. code-block:: json
47+
48+
{
49+
"name": "ArduinoBLE",
50+
"exclude_targets": [
51+
"esp32s2"
52+
],
53+
"sketch_path": [
54+
"~/Arduino/libraries/ArduinoBLE/examples/Central/Scan/Scan.ino"
55+
]
56+
}
57+
58+
Example of library addition from Github URL with required library:
59+
******************************************************************
60+
61+
.. code-block:: json
62+
63+
{
64+
"source-url": "https://github.com/me-no-dev/ESPAsyncWebServer.git",
65+
"required-libs": [
66+
{"source-url": "https://github.com/me-no-dev/AsyncTCP.git"}
67+
],
68+
"exclude_targets": [],
69+
"sketch_path": [
70+
"~/Arduino/libraries/ESPAsyncWebServer/examples/CaptivePortal/CaptivePortal.ino",
71+
"~/Arduino/libraries/ESPAsyncWebServer/examples/ESP_AsyncFSBrowser/ESP_AsyncFSBrowser.ino",
72+
"~/Arduino/libraries/ESPAsyncWebServer/examples/regex_patterns/regex_patterns.ino",
73+
"~/Arduino/libraries/ESPAsyncWebServer/examples/simple_server/simple_server.ino"
74+
]
75+
},
76+
77+
Submit a PR
78+
***********
79+
80+
* 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.
81+
82+
* After merging your PR, the next scheduled test will test your library and add the results to the `LIBRARIES_TEST.md`_.
83+
84+
Test Results
85+
------------
86+
87+
Icons meaning
88+
*************
89+
90+
There is a number before each icon, which means the number of examples which were compiled with that result.
91+
92+
* |success| - Compilation was successful.
93+
94+
* |warning| - Compilation was successful, but some warnings occurs.
95+
96+
* |fail| - Compilation failed.
97+
98+
* ``N/A`` - Not tested (target is in exclude_targets list).
99+
100+
Scheduled test result
101+
*********************
102+
103+
You can check the results in `LIBRARIES_TEST.md`_.
104+
105+
The results file example:
106+
107+
.. image:: _static/external_library_test_schedule.png
108+
:width: 600
109+
110+
Pull Request test result
111+
************************
112+
113+
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.
114+
In the table the results are in order ``BEFORE -> AFTER``.
115+
116+
.. image:: _static/external_library_test_pr.png
117+
:width: 600
118+
119+
.. |success| image:: _static/green_checkmark.png
120+
:height: 2ex
121+
:class: no-scaled-link
122+
123+
.. |warning| image:: _static/warning.png
124+
:height: 2ex
125+
:class: no-scaled-link
126+
127+
.. |fail| image:: _static/cross.png
128+
:height: 2ex
129+
:class: no-scaled-link
130+
131+
.. _LIBRARIES_TEST.md: https://github.com/espressif/arduino-esp32/LIBRARIES_TEST.md
132+
.. _lib.json: https://github.com/espressif/arduino-esp32/.github/workflow/lib.json

‎docs/source/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -19,3 +19,4 @@ Here you will find all the relevant information about the project.
1919
FAQ <faq>
2020
Troubleshooting <troubleshooting>
2121
Contributing <contributing>
22+
External Libraries Testing <external_libraries_test>

0 commit comments

Comments
 (0)