You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/ghub_action_workflow.md
+48-42Lines changed: 48 additions & 42 deletions
Original file line number
Diff line number
Diff line change
@@ -7,29 +7,34 @@ Here you will find a brief description of how to configure and customize the bui
7
7
This repository follows the project layout as described in detail in [Build System](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html) section of ESP-IDF Programming Guide.
8
8
9
9
**See as example layout of this repository:**
10
-
1. Application code is in the [components](../components/) and [main](../main) directories (example of a real application)
You can have multiple apps in a GitHub repository and add them all to the testing process by specifying their paths in the `test_app/CMakeLists.txt` file (see the following text).
19
-
20
-
2. In the file ` test_app/CMakeLists.txt` specify the path to your testable components (components that contain unit tests):
21
-
```sh
22
-
├── components
23
-
├── /test_app
24
-
│ ├── CMakeLists.txt # <--- (define paths for the build system)
25
-
26
-
```
27
-
```cmake
28
-
...
29
-
# Specify the path to testable components
30
-
set(EXTRA_COMPONENT_DIRS ../components) # <--- (these components will be built and tested)
31
-
...
32
-
```
10
+
11
+
1. Application code is in the [components](../components/) and [main](../main) directories (example of a real application)
You can have multiple apps in a GitHub repository and add them all to the testing process by specifying their paths in the `test_app/CMakeLists.txt` file (see the following text).
22
+
23
+
2. In the file ` test_app/CMakeLists.txt` specify the path to your testable components (components that contain unit tests):
24
+
25
+
```sh
26
+
├── components
27
+
├── /test_app
28
+
│ ├── CMakeLists.txt # <--- (define paths for the build system)
29
+
30
+
```
31
+
32
+
```cmake
33
+
...
34
+
# Specify the path to testable components
35
+
set(EXTRA_COMPONENT_DIRS ../components) # <--- (these components will be built and tested)
@@ -50,7 +55,7 @@ name: Build and Run Test Application Workflow
50
55
51
56
on:
52
57
schedule:
53
-
- cron: '0 0 * * *'# (scheduled - once per day at midnight)
58
+
- cron: '0 0 * * *'# (scheduled - once per day at midnight)
54
59
pull_request: # (for every push to Pull Request)
55
60
types: [opened, reopened, synchronize]
56
61
workflow_dispatch: # (to start the workflow manually)
@@ -69,7 +74,7 @@ jobs:
69
74
70
75
### Jobs
71
76
72
-
In this file, you will see two `jobs`defined as follows:
77
+
In this file, you will see two `jobs`defined as follows:
73
78
74
79
#### Job build_project
75
80
@@ -79,7 +84,7 @@ This job will call the build workflow, defined by the file `.github/workflows/bu
79
84
80
85
This job will call the test workflow, defined by the file `.github/workflows/test_esp_app.yml`.
81
86
82
-
As default, this workflow is disabled if the namespace is different from `espressif`. To enable, please set the `if: ${{ github.repository_owner == 'espressif' }}`to your namespace or remove this line.
87
+
As default, this workflow is disabled if the namespace is different from `espressif`. To enable, please set the `if: ${{ github.repository_owner == 'espressif' }}`to your namespace or remove this line.
83
88
84
89
```yml
85
90
test_project:
@@ -92,7 +97,7 @@ As default, this workflow is disabled if the namespace is different from `espres
92
97
93
98
## Project Build Workflow (`build_esp_app.yml`)
94
99
95
-
### Build Binaries (`build`Job)
100
+
### Build Binaries (`build`Job)
96
101
97
102
First, the binaries must be built with respect to each Espressif chip (`esp-idf target`). Using the GitHub action [matrix strategy](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs), you can build for several targets (chip types) in parallel.
98
103
@@ -125,13 +130,13 @@ Here you can customize the ESI-IDF version, the target (see the previous step),
125
130
- name: Build Test Application with ESP-IDF
126
131
uses: espressif/esp-idf-ci-action@v1
127
132
with:
128
-
esp_idf_version: "latest"# latest is the default version
133
+
esp_idf_version: "latest"# latest is the default version
129
134
target: ${{ matrix.espidf_target }}
130
135
path: 'test_app'
131
136
...
132
137
```
133
138
134
-
To set the ESP-IDF version, you can use the release tag name in the `esp_idf_version`field.
139
+
To set the ESP-IDF version, you can use the release tag name in the `esp_idf_version`field.
135
140
136
141
**Example**
137
142
@@ -145,27 +150,28 @@ To see the full release tag list, please see the [project release list](https://
145
150
146
151
## Test on Hardware Workflow (`test_esp_app.yml`)
147
152
148
-
Binaries built in the `build`job are downloaded via GH Action artifact and used in this job,
153
+
Binaries built in the `build`job are downloaded via GH Action artifact and used in this job,
149
154
which is running on your self-hosted runner with connected Espressif boards.
150
155
151
-
-binaries are flashed to boards
152
-
-tests are performed
153
-
-results are gathered for the final report
156
+
-binaries are flashed to boards
157
+
-tests are performed
158
+
-results are gathered for the final report
154
159
155
160
GitHub needs to know which of your self-hosted runner it should use for the test. It is a good practice to tag self-hosted runners in the same format as targets in `esp-idf`.
156
161
157
-
For example, the runner tag `esp32c3`is also the `IDF_TARGET`target. By defining this value in [matrix](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs), the same value can be used as a `IDF_TARGET`for the `build`job and as a runner tag for the `run-target`job.
162
+
For example, the runner tag `esp32c3`is also the `IDF_TARGET`target. By defining this value in [matrix](https://docs.github.com/en/actions/using-jobs/using-a-matrix-for-your-jobs), the same value can be used as a `IDF_TARGET`for the `build`job and as a runner tag for the `run-target`job.
158
163
159
164
### Tests in Docker Containers
160
165
161
166
We recommend running all tests in Docker containers because
162
-
- you always start with a clean and identical test environment
163
-
- there is no need to clean up after testing
164
-
- no risk of permanent unwanted system changes on runner machines
165
167
166
-
The Docker container must have **access to the computer's USB ports** - set the `--privileged` option in the job container definition:
168
+
- you always start with a clean and identical test environment
169
+
- there is no need to clean up after testing
170
+
- no risk of permanent unwanted system changes on runner machines
171
+
172
+
The Docker container must have **access to the computer's USB ports** - set the `--privileged` option in the job container definition:
167
173
168
-
Since the testing framework uses Python (`pytest`), it is a good idea to have a base image for a container with Python already included, e.g. `python:3.7-buster`(based on Debian, with Python 3).
174
+
Since the testing framework uses Python (`pytest`), it is a good idea to have a base image for a container with Python already included, e.g. `python:3.7-buster`(based on Debian, with Python 3).
0 commit comments