Mbed test framework allows users to test their mbed devices’ applications, build mbed SDK library, re-run tests, run mbed SDK regression, add new tests and get all this results automatically. Everything is done on your machine so you have a full control over compilation, and tests you run.
It's is using Python 2.7 programming language to drive all tests so make sure Python 2.7 is installed on your system and included in your system PATH. To compile mbed SDK and tests you will need one or more supported compilers installed on your system.
To follow this short introduction you should already:
* Know what mbed SDK is in general.
* Know how to install Python 2.7, ARM target cross compilers.
* You have C/C++ programming experience and at least willingness to learn a bit about Python.
## Test automation
Currently our simple test framework allows users to run tests on their machines (hosts) in a fully automated manner. All you need to do is to prepare two configuration files.
## Test automation limitations
Note that for tests which require connected external peripherals, for example Ethernet, SD flash cards, external EEPROM tests, loops etc. you need to:
* Modify test source code to match components' pin names to actual mbed board pins where peripheral is connected or
mbed test suite and build scripts are Python 2.7 applications and require Python 2.7 runtime environment and [setuptools](https://pythonhosted.org/an_example_pypi_project/setuptools.html) to install dependencies.
* Optionally you can install [pip](https://pip.pypa.io/en/latest/installing.html) which is the PyPA recommended tool for installing Python packages from command line.
mbed SDK in its repo root directory specifies ```setup.py``` file which holds information about all packages which are dependencies for it. Bear in mind only few simple steps are required to install all dependencies.
First, clone mbed SDK repo and go to mbed SDk repo's directory:
```
$ git clone https://github.com/mbedmicro/mbed.git
$ cd mbed
```
Second, invoke ```setup.py``` so ```setuptools``` can install mbed SDK's dependencies (external Python modules required by mbed SDK):
```
$ python setup.py install
```
or
```
$ sudo python setup.py install
```
when your system requires administrator rights to install new Python packages.
In case you do not want to install whole mbed package using ```setuptools```, you can use ```requirements.txt``` file and with help of ```pip`` package manager install only mbed's Python package dependencies:
**Please only read this chapter if you had problems installing mbed SDK dependencies to Python packages**.
Below you can find the list of mbed SDK dependencies to Python modules with instructions how to install them manually.
You can skip this part if you've already install [Python 2.7](https://www.python.org/download/releases/2.7) and [setuptools](https://pythonhosted.org/an_example_pypi_project/setuptools.html) and successfully [installed all dependencies](#prerequisites).
* Please make sure you've installed [pip](https://pip.pypa.io/en/latest/installing.html) or [easy_install](https://pythonhosted.org/setuptools/easy_install.html#installing-easy-install)
Note: Easy Install is a python module (easy_install) bundled with [setuptools](https://pythonhosted.org/an_example_pypi_project/setuptools.html#installing-setuptools-and-easy-install) that lets you automatically download, build, install, and manage Python packages.
IntelHex may be downloaded from https://launchpad.net/intelhex/+download or http://www.bialix.com/intelhex/.
Assuming Python is properly installed on your platform, installation should just require running the following command from the root directory of the archive:
```
sudo python setup.py install
```
This will install the intelhex package into your system’s site-packages directory. After that is done, any other Python scripts or modules should be able to import the package using:
Keil ARM Compiler | ARM, uARM | ARM C/C++ Compiler, 5.03 [Build 117]
GCC ARM | GCC_ARM | gcc version 4.8.3 20131129 (release)
GCC CodeRed | GCC_CR | gcc version 4.6.2 20121016 (release)
IAR Embedded Workbench | IAR | IAR ANSI C/C++ Compiler V6.70.1.5641/W32 for ARM
* Mbed board. You can find list of supported platforms [here](https://mbed.org/platforms/).
### Getting Mbed SDK sources with test suite
So you have already installed Python (with required modules) together with at least one supported compiler you will use with your mbed board. Great!
Now let's go further and try to get Mbed SDK with test suite together. So let's clone latest Mbed SDK source code and configure path to our compiler(s) in next few steps.
* Open console and run command below to clone Mbed SDK repository hosted on [Github](https://github.com/mbedmicro/mbed).
* Now you can go to mbed directory you've just cloned and you can see root directory structure of our Mbed SDK library sources. Just type following commands:
# This is moved to separate JSON configuration file used by singletest.py
MUTs = {
}
```
Note: You need to provide the absolute path to your compiler(s) installed on your host machine. Replace corresponding variable values with paths to compilers installed in your system:
* ```ARM_PATH``` for armcc compiler.
* ```GCC_ARM_PATH``` for GCC ARM compiler.
* ```GCC_CR_PATH``` for GCC CodeRed compiler.
* ```IAR_PATH``` for IAR compiler.
If for example you do not use ```IAR``` compiler you do not have to modify anything. Workspace tools will use ```IAR_PATH`` variable only if you explicit ask for it from command line. So do not worry and replace only paths for your installed compilers.
Note: Because this is a Python script and ```ARM_PATH```, ```GCC_ARM_PATH```, ```GCC_CR_PATH```, ```IAR_PATH``` are Python string variables please use double backlash or single slash as path's directories delimiter to avoid incorrect path format. For example:
Let's build mbed SDK library off-line from sources using your compiler. We've already cloned mbed SDK sources, we've also installed compilers and added their paths to ```mbed_settings.py```.
or if you want to take advantage from multi-threaded compilation please use option ```-j X``` where ```X``` is number of cores you want to use to compile mbed SDK. See below:
Above command will build mbed SDK for [LPC1768](http://developer.mbed.org/platforms/mbed-LPC1768/) platform using ARM compiler.
Let's have a look at directory structure under ```mbed/build/```. We can see for ```LPC1768``` new directory ```TARGET_LPC1768``` was created. This directory contains all build primitives.
Directory ```mbed/TARGET_LPC1768/TOOLCHAIN_ARM_STD/``` contains mbed SDK library ```mbed.ar```. This directory structure also stores all needed headers which you should use with ```mbed.ar``` when building your own software.
Note: Why ```LCP1768```? For this example we are using ```LPC1768``` because this platform supports all compilers so you are sure you only need to specify proper compiler.
If you are not using ARM Compiler replace ```ARM``` with your compiler nickname: ```GCC_ARM```, ```GCC_CR``` or ```IAR```. For example if you are using IAR type command:
Note: Workspace tools track changes in source code. So if for example mbed SDK or test source code changes ```build.py``` script will recompile project with all dependencies. If there are no changes in code consecutive mbed SDK re-builds using build.py will not rebuild project if this is not necessary. Try to run last command once again, we can see script ```build.py``` will not recompile project (there are no changes):
* mbed SDK (with libs like Ethernet, RTOS, USB, USB host).
* Tests which also can be linked with libraries like RTOS or Ethernet.
Note: Test suite also uses the same build script, inheriting the same properties like auto dependency tracking and project rebuild in case of source code changes.
Build.py script is a powerful tool to build mbed SDK for all available platforms using all supported by mbed cross-compilers. Script is using our workspace tools build API to create desired platform-compiler builds. Use script option ```--h``` (help) to check all script parameters.
```
$ python build.py --help
```
* The command line parameter ```-m``` specifies the MCUs/platforms for which you want to build the mbed SDK. More than one MCU(s)/platform(s) may be specified with this parameter using comma as delimiter.
Example for one platform build:
```
$ python build.py -m LPC1768 -t ARM
```
or for many platforms:
```
$ python build.py -m LPC1768,NUCLEO_L152RE -t ARM
```
* Parameter ```-t``` defined which toolchain should be used for mbed SDK build. You can build Mbed SDK for multiple toolchains using one command.
Below example (note there is no space after commas) will compile mbed SDK for Freescale Freedom KL25Z platform using ARM and GCC_ARM compilers:
```
$ python build.py -m KL25Z -t ARM,GCC_ARM
```
* You can combine this technique to compile multiple targets with multiple compilers.
Below example will compile mbed SDK for Freescale's KL25Z and KL46Z platforms using ARM and GCC_ARM compilers:
```
$ python build.py -m KL25Z,KL46Z -t ARM,GCC_ARM
```
* Building libraries included in mbed SDK's source code. Parameters ```-r```, ```-e```, ```-u```, ```-U```, ```-d```, ```-b``` will add ```RTOS```, ```Ethernet```, ```USB```, ```USB Host```, ```DSP```, ```U-Blox``` libraries respectively.
Below example will build Mbed SDK library for for NXP LPC1768 platform together with RTOS (```-r``` switch) and Ethernet (```-e``` switch) libraries.
```
$ python build.py -m LPC1768 -t ARM -r -e
Building library CMSIS (LPC1768, ARM)
Building library MBED (LPC1768, ARM)
Building library RTX (LPC1768, ARM)
Building library RTOS (LPC1768, ARM)
Building library ETH (LPC1768, ARM)
Completed in: (0.48)s
Build successes:
* ARM::LPC1768
```
* If you’re unsure which platforms and toolchains are supported please use switch ```-S``` to print simple matrix of platform to compiler dependencies.
[Cppcheck](http://cppcheck.sourceforge.net/) is a static analysis tool for C/C++ code. Unlike C/C++ compilers and many other analysis tools it does not detect syntax errors in the code. Cppcheck primarily detects the types of bugs that the compilers normally do not detect. The goal is to detect only real errors in the code (i.e. have zero false positives).
Prerequisites:
* Please install ```CppCheck``` on your system before you want to use it with build scripts.
* You should also add Cppcheck to your system path.
```build.py``` script supports switching between compilation, building and just static code analysis testing. You can use switch ```--cppcheck``` to perform CppCheck static code analysis.
* When you are using --cppcheck switch all macros, toolchain dependencies etc. are preserved so you are sure you are checking exactly the same code you would compile for your application.
* Cppcheck analysis can take up to few minutes on slower machines.
* Usually you will use switches ```-t``` and ```-m``` to define toolchain and MCU (platform) respectively. You should do the same in case of CppCheck analysis. Please note that build script can also compile and build RTOS, Ethernet library etc. If you want to check those just use corresponding build script switches (e.g. ```-r```, ```-e```, ...).
```make.py``` is a ```mbed/tools/``` script used to build tests (we call them sometimes 'programs') one by one manually. This script allows you to flash board, execute and test it. However, this script is deprecated and will not be described here. Instead please use ```singletest.py``` file to build mbed SDK, tests and run automation for test cases included in ```mbedmicro/mbed```.
Note: ```make.py``` script depends on existing already built mbed SDK and library sources so you need to pre-build mbed SDK and other libraries (such as RTOS library) to link 'program' (test) with mbed SDK and RTOS library. To pre-build mbed SDK please use ```build.py``` script.
Because we previously have built mbed SDK we are now able to drive test case compilation and linking with mbed SDK and produce ```MBED_A3``` test case binary in build directory:
For more help type ```$ python make.py --help``` in your command line.
# project.py script
```project.py``` script is used to export test cases ('programs') from test case portfolio to off-line IDE. This is a easy way to export test project to IDEs such as:
* codesourcery.
* coide.
* ds5_5.
* emblocks.
* gcc_arm.
* iar.
* kds.
* lpcxpresso.
* uvision.
You can export project using command line. All you need to do is to specify mbed platform name (option ```-m```), your IDE (option ```-i```) and project name you want to export (option ```-n``` or (option ```-p```).
In below example we export our project so we can work on it using GCC ARM cross-compiler. Building mechanism used to drive exported build will be ```Make```.
