Skip to content

Commit 59a4ad6

Browse files
Qinghao ShiQinghao Shi
Qinghao Shi
authored and
Qinghao Shi
committed
EXAMPLES: add README file
1 parent 52b4c39 commit 59a4ad6

File tree

1 file changed

+169
-0
lines changed

1 file changed

+169
-0
lines changed

‎tools/test/examples/README.md

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Examples testing script
2+
3+
The scripts in this folder are used for testing mbed-os official examples. it contains following files:
4+
5+
- `examples.py` the main script which serves as command line interface
6+
- `examples.json` the default configuration file for the script, which contains the information to the examples. if required, a customised configuration file can be pass as argument to the script
7+
- `examples_lib.py` the library file, which contains the main function of the testing scripts
8+
9+
10+
## The Scripts
11+
12+
`examples.py` provide command line interface and sub commands that makes easier to test examples. included sub commands are:
13+
14+
* **import** - Imports each of the repos and its dependencies (.lib files) associated with the specific examples name from the json configuration file. Note if there is already a clone of the repo then it will first be removed to ensure a clean, up to date cloning.
15+
16+
* **clone** - clones each of the repos associated with the specific examples name from the json configuration file. Note if there is already a clone of the repo then it will first be removed to ensure a clean, up to date cloning.
17+
18+
* **deploy** - If the example directory exists as provided by the json configuration file, pull in the examples dependencies by using `mbed-cli deploy`.
19+
20+
* **update** - For each example repo identified in the config json object, update the version of mbed-os to that specified by the supplied GitHub tag. This function assumes that each example repo has already been cloned.
21+
22+
* **compile** - Compiles combinations of example programs, targets and compile chains.
23+
24+
* **export** - Exports and builds combinations of example programs, targets and IDEs.
25+
26+
* **list** - display examples in configuration file in a table
27+
28+
* **symlink** - create symbolic link to given mbed-os PATH
29+
30+
for more detailed options, please use `-h` or `--help`
31+
32+
33+
## The Configuration file
34+
35+
here is the section of default configuration file:
36+
37+
```json
38+
{
39+
"examples": [
40+
{
41+
"name": "mbed-os-example-blinky",
42+
"github": "https://github.com/ARMmbed/mbed-os-example-blinky",
43+
"sub-repo-example": false,
44+
"subs": [],
45+
"features" : [],
46+
"targets" : [],
47+
"toolchains" : [],
48+
"exporters": [],
49+
"compile" : true,
50+
"export": true,
51+
"test" : true,
52+
"baud_rate": 9600,
53+
"compare_log": ["mbed-os-example-blinky/tests/blinky.log"],
54+
"auto-update" : true
55+
},
56+
57+
...
58+
59+
{
60+
"name": "mbed-os-example-tls",
61+
"github": "https://github.com/ARMmbed/mbed-os-example-tls",
62+
"sub-repo-example": true,
63+
"subs": [
64+
"benchmark",
65+
"tls-client",
66+
"hashing",
67+
"authcrypt"
68+
],
69+
"features" : [],
70+
"targets" : ["K66F", "NUCLEO_F429ZI"],
71+
"toolchains" : ["GCC_ARM", "ARM"],
72+
"exporters": [],
73+
"compile" : false,
74+
"export": false,
75+
"test" : false,
76+
"baud_rate": 9600,
77+
"compare_log": [
78+
"mbed-os-example-tls/tests/benchmark.log",
79+
"mbed-os-example-tls/tests/tls-client.log",
80+
"mbed-os-example-tls/tests/hashing.log",
81+
"mbed-os-example-tls/tests/authcrypt.log"
82+
],
83+
"auto-update" : true
84+
}
85+
]
86+
}
87+
88+
```
89+
90+
### Fields
91+
92+
* **name** - name of the example, should be the base name of the example repository address, will throw if not match
93+
* **github** - example github repository address
94+
* **sub-repo-example** specify if the example repository have sub folder for each examples
95+
* **subs** - array of sub examples names
96+
* **features** The features that must be in the features array of a target in targets.json
97+
* **baud_rate** example default baud rate
98+
* **compare_log** array of log which is compared to command line output when testing, if example has many sub examples, the order of log should match with the order of sub examples.
99+
* **targets** - list of mbed-os dev boards that runs this example.
100+
* **targets** list of targeted development boards
101+
* **toolchains** toolchain to use for compile
102+
* **exporters** allowed exporters
103+
* **compile** enable compiling
104+
* **export** enable exporting
105+
* **test** enable testing
106+
107+
### Values
108+
109+
`[ ]` means all possible alternatives
110+
111+
112+
113+
## Typical usage
114+
115+
In mbed-OS CI, we usually following the bellow steps to compile and test mbed-os-examples.
116+
117+
1. Clone mbed-os repository to current folder
118+
119+
```
120+
git clone https://github.com/ARMmbed/mbed-os.git
121+
```
122+
123+
2. Clone the examples repo to current folder , users can pass a `-e` option to the script to filter out rest of the exmpale and let the scripts only run on particular one
124+
125+
```
126+
python mbed-os/tools/test/examples/examples.py clone
127+
```
128+
129+
3. Create symbolic link to mbed-os for every examples. this is step is to let the all the examples share a single mbed-os folder, rather that checkout the mbed-os folder many times . In bellow command pass an absolute path as the argument is highly recommended
130+
131+
```
132+
python mbed-os/tools/test/examples/examples.py symlink $PWD/mbedos
133+
```
134+
4. deploy mbed-os other dependency libraries
135+
136+
```
137+
python mbed-os/tools/test/examples/examples.py deploy
138+
```
139+
5. compile test for the examples on a specific target
140+
```
141+
python mbed-os/tools/test/examples/examples.py compile -m <target>
142+
```
143+
once the compile test finished, the scripts will prints the result table as follows:
144+
145+
```
146+
Passed Example Compilation:
147+
+---------------------------------+--------+-----------+----------+--------------+
148+
| EXAMPLE NAME | TARGET | TOOLCHAIN | TEST GEN | BUILD RESULT |
149+
+---------------------------------+--------+-----------+----------+--------------+
150+
| mbed-os-example-kvstore | K64F | GCC_ARM | TEST_ON | PASSED |
151+
| mbed-os-example-tls-socket | K64F | GCC_ARM | TEST_ON | PASSED |
152+
| mbed-os-example-blockdevice | K64F | GCC_ARM | TEST_ON | PASSED |
153+
| mbed-os-example-wifi | K64F | GCC_ARM | TEST_OFF | PASSED |
154+
| mbed-os-example-error-handling | K64F | GCC_ARM | TEST_ON | PASSED |
155+
| mbed-os-example-sd-driver | K64F | GCC_ARM | TEST_ON | PASSED |
156+
| mbed-os-example-crash-reporting | K64F | GCC_ARM | TEST_ON | PASSED |
157+
| mbed-os-example-filesystem | K64F | GCC_ARM | TEST_ON | PASSED |
158+
| mbed-os-example-blinky | K64F | GCC_ARM | TEST_ON | PASSED |
159+
| mbed-os-example-bootloader | K64F | GCC_ARM | TEST_OFF | PASSED |
160+
| mbed-os-example-cpu-stats | K64F | GCC_ARM | TEST_ON | PASSED |
161+
| mbed-os-example-sys-info | K64F | GCC_ARM | TEST_ON | PASSED |
162+
| mbed-os-example-attestation | K64F | GCC_ARM | TEST_ON | PASSED |
163+
+---------------------------------+--------+-----------+----------+--------------+
164+
Number of failures = 0
165+
```
166+
167+
after the compilation stage, a `test_spec.json` file will be generated, later this file will be consumed by GreenTea tests, which is going to test the compiled example on hardware platform.
168+
169+

0 commit comments

Comments
 (0)