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: tools/test/examples/README.md
+59-61Lines changed: 59 additions & 61 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,38 +1,36 @@
1
1
# Examples testing script
2
2
3
-
The scripts in this folder are used for testing mbed-os official examples. it contains following files:
3
+
The scripts in this folder are used for testing `mbed-os` official examples. It contains the following files:
4
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
5
+
-`examples.py`- the main script that serves as the command-line interface.
6
+
-`examples.json`- the default configuration file for the script, which contains the information to the examples. If required, you can pass a customized configuration file as an argument to the script.
7
+
-`examples_lib.py`- the library file, which contains the main function of the testing scripts.
8
8
9
+
## The scripts
9
10
10
-
## The Scripts
11
+
`examples.py` provides command-line interface and subcommands that makes easier to test examples. Included subcommands are:
11
12
12
-
`examples.py` provide command line interface and sub commands that makes easier to test examples. included sub commands are:
13
+
***import** - imports each of the repos and its dependencies (.lib files) associated with the specific examples name from the .json configuration file. If there is already a clone of the repo, it will first be removed to ensure a clean, up-to-date cloning.
13
14
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
+
***clone** - clones each of the repos associated with the specific examples name from the .json configuration file. If there is already a clone of the repo, it will first be removed to ensure a clean, up-to-date cloning.
15
16
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
+
***deploy** - if the example directory exists as provided by the .json configuration file, pulls in the examples dependencies by using `mbed-cli deploy`.
17
18
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
+
***update** - for each example repo identified in the config .json object, updates the version of `mbed-os` to that specified by the supplied GitHub tag. This function assumes that each example repo has already been cloned.
19
20
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
+
***compile** - compiles combinations of example programs, targets and compile chains.
21
22
22
-
***compile** - Compiles combinations of example programs, targets and compile chains.
23
+
***export** - exports and builds combinations of example programs, targets and IDEs.
23
24
24
-
***export** - Exports and builds combinations of example programs, targets and IDEs.
25
+
***list** - displays examples in a configuration file in a table.
25
26
26
-
***list** - display examples in configuration file in a table
27
+
***symlink** - creates a symbolic link to a given `mbed-os` PATH.
27
28
28
-
***symlink** - create symbolic link to given mbed-os PATH
29
+
For more detailed options, please use `-h` or `--help`.
29
30
30
-
for more detailed options, please use `-h` or `--help`
31
+
## The configuration file
31
32
32
-
33
-
## The Configuration file
34
-
35
-
here is the section of default configuration file:
33
+
Here is the section of default configuration file:
36
34
37
35
```json
38
36
{
@@ -89,61 +87,63 @@ here is the section of default configuration file:
89
87
90
88
### Fields
91
89
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 commandline 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
90
+
***name** - name of the example. It should be the base name of the example repository address and will throw if it doesn't match.
91
+
***github** - example GitHub repository address.
92
+
***sub-repo-example**- specifies if the example repository has a subfolder for each example.
93
+
***subs** - array of subexample names.
94
+
***features**- the features that must be in the features array of a target in `targets.json`.
95
+
***baud_rate**- example default baud rate.
96
+
***compare_log**- array of log compared to command-line output during testing. If the example has many subexamples, the order of log should match the order of subexamples.
97
+
***targets** - list of `mbed-os` development boards that run this example.
98
+
***targets**- list of targeted development boards.
99
+
***toolchains**- toolchain to use for compiling.
100
+
***exporters**- allowed exporters.
101
+
***compile**- enables compiling.
102
+
***export**- enables exporting.
103
+
***test**- enables testing.
106
104
107
105
### Values
108
106
109
-
`[ ]` means all possible alternatives
107
+
`[ ]` means all possible alternatives.
110
108
109
+
## Typical use
111
110
111
+
In the Mbed OS CI, we follow the below steps to compile and test Mbed OS examples.
112
112
113
-
## Typical usage
113
+
1. Clone `mbed-os` repository to the current folder:
114
114
115
-
In mbed-OS CI, we usually following the bellow steps to compile and test mbed-os-examples.
115
+
```
116
+
git clone https://github.com/ARMmbed/mbed-os.git
117
+
```
116
118
117
-
1. Clone mbed-os repository to current folder
119
+
1. Clone the examples repo to the current folder. Users can pass an `-e` option to the script to filter out the rest of the examples, so the scripts only run on one particular example:
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
125
+
1. Create a symbolic link to `mbed-os` for every example. This step lets all the examples share a single `mbed-os` folder, rather than checking out the `mbed-os` folder many times. We highly recommend you pass an absolute path as the argument:
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
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
-
167
+
After the compilation stage, a `test_spec.json` file is generated. Later, Greentea tests will consume this file. They test the compiled example on hardware platform.
0 commit comments