erkin yucel / mbed-os

mbed os with nrf51 internal bandgap enabled to read battery level

Dependents:   BLE_file_test BLE_Blink ExternalEncoder

docs/BUILDING.md@0:f269e3021894, 2016-10-23 (annotated)

Committer:
elessair
Date:
Sun Oct 23 15:10:02 2016 +0000
Revision:
0:f269e3021894
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
elessair 0:f269e3021894 1 # Mbed SDK build script environment
elessair 0:f269e3021894 2 ## Introduction
elessair 0:f269e3021894 3 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.
elessair 0:f269e3021894 4
elessair 0:f269e3021894 5 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.
elessair 0:f269e3021894 6
elessair 0:f269e3021894 7 To follow this short introduction you should already:
elessair 0:f269e3021894 8 * Know what mbed SDK is in general.
elessair 0:f269e3021894 9 * Know how to install Python 2.7, ARM target cross compilers.
elessair 0:f269e3021894 10 * You have C/C++ programming experience and at least willingness to learn a bit about Python.
elessair 0:f269e3021894 11
elessair 0:f269e3021894 12 ## Test automation
elessair 0:f269e3021894 13 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.
elessair 0:f269e3021894 14
elessair 0:f269e3021894 15 ## Test automation limitations
elessair 0:f269e3021894 16 Note that for tests which require connected external peripherals, for example Ethernet, SD flash cards, external EEPROM tests, loops etc. you need to:
elessair 0:f269e3021894 17
elessair 0:f269e3021894 18 * Modify test source code to match components' pin names to actual mbed board pins where peripheral is connected or
elessair 0:f269e3021894 19 * Wire your board the same way test defines it.
elessair 0:f269e3021894 20
elessair 0:f269e3021894 21 ## Prerequisites
elessair 0:f269e3021894 22 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.
elessair 0:f269e3021894 23
elessair 0:f269e3021894 24 What we need:
elessair 0:f269e3021894 25 * Installed [Python 2.7](https://www.python.org/download/releases/2.7) programming language.
elessair 0:f269e3021894 26 * Installed [setuptools](https://pythonhosted.org/an_example_pypi_project/setuptools.html#installing-setuptools-and-easy-install)
elessair 0:f269e3021894 27 * 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.
elessair 0:f269e3021894 28
elessair 0:f269e3021894 29 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.
elessair 0:f269e3021894 30
elessair 0:f269e3021894 31 First, clone mbed SDK repo and go to mbed SDk repo's directory:
elessair 0:f269e3021894 32 ```
elessair 0:f269e3021894 33 $ git clone https://github.com/mbedmicro/mbed.git
elessair 0:f269e3021894 34 $ cd mbed
elessair 0:f269e3021894 35 ```
elessair 0:f269e3021894 36
elessair 0:f269e3021894 37 Second, invoke ```setup.py``` so ```setuptools``` can install mbed SDK's dependencies (external Python modules required by mbed SDK):
elessair 0:f269e3021894 38 ```
elessair 0:f269e3021894 39 $ python setup.py install
elessair 0:f269e3021894 40 ```
elessair 0:f269e3021894 41 or
elessair 0:f269e3021894 42 ```
elessair 0:f269e3021894 43 $ sudo python setup.py install
elessair 0:f269e3021894 44 ```
elessair 0:f269e3021894 45 when your system requires administrator rights to install new Python packages.
elessair 0:f269e3021894 46
elessair 0:f269e3021894 47 ### Manual Python package dependency installation
elessair 0:f269e3021894 48 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:
elessair 0:f269e3021894 49 ```
elessair 0:f269e3021894 50 $ pip install -r requirements.txt
elessair 0:f269e3021894 51 ```
elessair 0:f269e3021894 52 ## Prerequisites (manual Python package dependency installation)
elessair 0:f269e3021894 53 **Please only read this chapter if you had problems installing mbed SDK dependencies to Python packages**.
elessair 0:f269e3021894 54
elessair 0:f269e3021894 55 Below you can find the list of mbed SDK dependencies to Python modules with instructions how to install them manually.
elessair 0:f269e3021894 56
elessair 0:f269e3021894 57 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).
elessair 0:f269e3021894 58
elessair 0:f269e3021894 59 * 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)
elessair 0:f269e3021894 60 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.
elessair 0:f269e3021894 61
elessair 0:f269e3021894 62 * Installed [pySerial](https://pypi.python.org/pypi/pyserial) module for Python 2.7.
elessair 0:f269e3021894 63 pySerial can be installed from PyPI, either manually downloading the files and installing as described below or using:
elessair 0:f269e3021894 64 ```
elessair 0:f269e3021894 65 $ pip install pyserial
elessair 0:f269e3021894 66 ```
elessair 0:f269e3021894 67 or:
elessair 0:f269e3021894 68 ```
elessair 0:f269e3021894 69 easy_install -U pyserial
elessair 0:f269e3021894 70 ```
elessair 0:f269e3021894 71 * Installed [prettytable](https://code.google.com/p/prettytable/wiki/Installation) module for Python 2.7.
elessair 0:f269e3021894 72 prettytable can be installed from PyPI, either manually downloading the files and installing as described below or using:
elessair 0:f269e3021894 73 ```
elessair 0:f269e3021894 74 $ pip install prettytable
elessair 0:f269e3021894 75 ```
elessair 0:f269e3021894 76 * Installed [IntelHex](https://pypi.python.org/pypi/IntelHex) module.
elessair 0:f269e3021894 77 IntelHex may be downloaded from https://launchpad.net/intelhex/+download or http://www.bialix.com/intelhex/.
elessair 0:f269e3021894 78 Assuming Python is properly installed on your platform, installation should just require running the following command from the root directory of the archive:
elessair 0:f269e3021894 79 ```
elessair 0:f269e3021894 80 sudo python setup.py install
elessair 0:f269e3021894 81 ```
elessair 0:f269e3021894 82 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:
elessair 0:f269e3021894 83 ```
elessair 0:f269e3021894 84 $ python
elessair 0:f269e3021894 85 Python 2.7.8 (default, Jun 30 2014, 16:03:49) [MSC v.1500 32 bit (Intel)] on win32
elessair 0:f269e3021894 86 Type "help", "copyright", "credits" or "license" for more information.
elessair 0:f269e3021894 87 >>> from intelhex import IntelHex
elessair 0:f269e3021894 88 >>>
elessair 0:f269e3021894 89 ```
elessair 0:f269e3021894 90 * You can check if you have correctly installed the above modules (or you already have them) by starting Python and importing both modules.
elessair 0:f269e3021894 91 ```
elessair 0:f269e3021894 92 $ python
elessair 0:f269e3021894 93 Python 2.7.8 (default, Jun 30 2014, 16:03:49) [MSC v.1500 32 bit (Intel)] on win32
elessair 0:f269e3021894 94 Type "help", "copyright", "credits" or "license" for more information.
elessair 0:f269e3021894 95 >>> import serial
elessair 0:f269e3021894 96 >>> import prettytable
elessair 0:f269e3021894 97 >>> from intelhex import IntelHex
elessair 0:f269e3021894 98 >>>
elessair 0:f269e3021894 99 ```
elessair 0:f269e3021894 100 * Installed Git open source distributed version control system.
elessair 0:f269e3021894 101 * Installed at least one of the supported by Mbed SDK workspace tools compilers:
elessair 0:f269e3021894 102
elessair 0:f269e3021894 103 Compiler | Mbed SDK Abbreviation | Example Version
elessair 0:f269e3021894 104 -----------------------|-----------------------|-----------
elessair 0:f269e3021894 105 Keil ARM Compiler | ARM, uARM | ARM C/C++ Compiler, 5.03 [Build 117]
elessair 0:f269e3021894 106 GCC ARM | GCC_ARM | gcc version 4.8.3 20131129 (release)
elessair 0:f269e3021894 107 GCC CodeRed | GCC_CR | gcc version 4.6.2 20121016 (release)
elessair 0:f269e3021894 108 IAR Embedded Workbench | IAR | IAR ANSI C/C++ Compiler V6.70.1.5641/W32 for ARM
elessair 0:f269e3021894 109
elessair 0:f269e3021894 110 * Mbed board. You can find list of supported platforms [here](https://mbed.org/platforms/).
elessair 0:f269e3021894 111
elessair 0:f269e3021894 112 ### Getting Mbed SDK sources with test suite
elessair 0:f269e3021894 113 So you have already installed Python (with required modules) together with at least one supported compiler you will use with your mbed board. Great!
elessair 0:f269e3021894 114
elessair 0:f269e3021894 115 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.
elessair 0:f269e3021894 116
elessair 0:f269e3021894 117 * Open console and run command below to clone Mbed SDK repository hosted on [Github](https://github.com/mbedmicro/mbed).
elessair 0:f269e3021894 118 ```
elessair 0:f269e3021894 119 $ git clone https://github.com/mbedmicro/mbed.git
elessair 0:f269e3021894 120 Cloning into 'mbed'...
elessair 0:f269e3021894 121 remote: Counting objects: 37221, done.
elessair 0:f269e3021894 122 remote: Compressing objects: 100% (3/3), done.
elessair 0:f269e3021894 123 remote: Total 37221 (delta 0), reused 0 (delta 0), pack-reused 37218
elessair 0:f269e3021894 124 Receiving objects: 100% (37221/37221), 20.38 MiB | 511.00 KiB/s, done.
elessair 0:f269e3021894 125 Resolving deltas: 100% (24455/24455), done.
elessair 0:f269e3021894 126 Checking connectivity... done.
elessair 0:f269e3021894 127 Checking out files: 100% (3994/3994), done.
elessair 0:f269e3021894 128 ```
elessair 0:f269e3021894 129 * 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:
elessair 0:f269e3021894 130 ```
elessair 0:f269e3021894 131 $ cd mbed
elessair 0:f269e3021894 132 $ ls
elessair 0:f269e3021894 133 LICENSE MANIFEST.in README.md libraries setup.py travis tools
elessair 0:f269e3021894 134 ```
elessair 0:f269e3021894 135 Directory structure we are interested in:
elessair 0:f269e3021894 136 ```
elessair 0:f269e3021894 137 mbed/tools/ - test suite scripts, build scripts etc.
elessair 0:f269e3021894 138 mbed/libraries/tests/ - mbed SDK tests,
elessair 0:f269e3021894 139 mbed/libraries/tests/mbed/ - tests for mbed SDK and peripherals tests,
elessair 0:f269e3021894 140 mbed/libraries/tests/net/echo/ - tests for Ethernet interface,
elessair 0:f269e3021894 141 mbed/libraries/tests/rtos/mbed/ - tests for RTOS.
elessair 0:f269e3021894 142 ```
elessair 0:f269e3021894 143
elessair 0:f269e3021894 144 ### Workspace tools
elessair 0:f269e3021894 145 Workspace tools are set of Python scripts used off-line by Mbed SDK team to:
elessair 0:f269e3021894 146 * Compile and build mbed SDK,
elessair 0:f269e3021894 147 * Compile and build libraries included in mbed SDK repo like e.g. ETH (Ethernet), USB, RTOS or CMSIS,
elessair 0:f269e3021894 148 * Compile, build and run mbed SDK tests,
elessair 0:f269e3021894 149 * Run test regression locally and in CI server,
elessair 0:f269e3021894 150 * Get library, target, test configuration (paths, parameters, names etc.).
elessair 0:f269e3021894 151
elessair 0:f269e3021894 152 ### Configure workspace tools to work with your compilers
elessair 0:f269e3021894 153 Before we can run our first test we need to configure our test environment a little!
elessair 0:f269e3021894 154 Now we need to tell workspace tools where our compilers are.
elessair 0:f269e3021894 155
elessair 0:f269e3021894 156 * Please to go ```mbed``` directory and create empty file called ```mbed_settings.py```.
elessair 0:f269e3021894 157 ```
elessair 0:f269e3021894 158 $ touch mbed_settings.py
elessair 0:f269e3021894 159 ```
elessair 0:f269e3021894 160 * Populate this file the Python code below:
elessair 0:f269e3021894 161 ```python
elessair 0:f269e3021894 162 from os.path import join
elessair 0:f269e3021894 163
elessair 0:f269e3021894 164 # ARMCC
elessair 0:f269e3021894 165 ARM_PATH = "C:/Work/toolchains/ARMCompiler_5.03_117_Windows"
elessair 0:f269e3021894 166 ARM_BIN = join(ARM_PATH, "bin")
elessair 0:f269e3021894 167 ARM_INC = join(ARM_PATH, "include")
elessair 0:f269e3021894 168 ARM_LIB = join(ARM_PATH, "lib")
elessair 0:f269e3021894 169
elessair 0:f269e3021894 170 ARM_CPPLIB = join(ARM_LIB, "cpplib")
elessair 0:f269e3021894 171 MY_ARM_CLIB = join(ARM_PATH, "lib", "microlib")
elessair 0:f269e3021894 172
elessair 0:f269e3021894 173 # GCC ARM
elessair 0:f269e3021894 174 GCC_ARM_PATH = "C:/Work/toolchains/gcc_arm_4_8/4_8_2013q4/bin"
elessair 0:f269e3021894 175
elessair 0:f269e3021894 176 # GCC CodeRed
elessair 0:f269e3021894 177 GCC_CR_PATH = "C:/Work/toolchains/LPCXpresso_6.1.4_194/lpcxpresso/tools/bin"
elessair 0:f269e3021894 178
elessair 0:f269e3021894 179 # IAR
elessair 0:f269e3021894 180 IAR_PATH = "C:/Work/toolchains/iar_6_5/arm"
elessair 0:f269e3021894 181
elessair 0:f269e3021894 182 SERVER_ADDRESS = "127.0.0.1"
elessair 0:f269e3021894 183 LOCALHOST = "127.0.0.1"
elessair 0:f269e3021894 184
elessair 0:f269e3021894 185 # This is moved to separate JSON configuration file used by singletest.py
elessair 0:f269e3021894 186 MUTs = {
elessair 0:f269e3021894 187 }
elessair 0:f269e3021894 188 ```
elessair 0:f269e3021894 189
elessair 0:f269e3021894 190 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:
elessair 0:f269e3021894 191 * ```ARM_PATH``` for armcc compiler.
elessair 0:f269e3021894 192 * ```GCC_ARM_PATH``` for GCC ARM compiler.
elessair 0:f269e3021894 193 * ```GCC_CR_PATH``` for GCC CodeRed compiler.
elessair 0:f269e3021894 194 * ```IAR_PATH``` for IAR compiler.
elessair 0:f269e3021894 195
elessair 0:f269e3021894 196 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.
elessair 0:f269e3021894 197
elessair 0:f269e3021894 198 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:
elessair 0:f269e3021894 199 ```python
elessair 0:f269e3021894 200 ARM_PATH = "C:/Work/toolchains/ARMCompiler_5.03_117_Windows"
elessair 0:f269e3021894 201 GCC_ARM_PATH = "C:/Work/toolchains/gcc_arm_4_8/4_8_2013q4/bin"
elessair 0:f269e3021894 202 GCC_CR_PATH = "C:/Work/toolchains/LPCXpresso_6.1.4_194/lpcxpresso/tools/bin"
elessair 0:f269e3021894 203 IAR_PATH = "C:/Work/toolchains/iar_6_5/arm"
elessair 0:f269e3021894 204 ```
elessair 0:f269e3021894 205
elessair 0:f269e3021894 206 Note: Settings in ```mbed_settings.py``` will overwrite variables with default values in ```mbed/default_settings.py``` file.
elessair 0:f269e3021894 207
elessair 0:f269e3021894 208 ## Build Mbed SDK library from sources
elessair 0:f269e3021894 209 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```.
elessair 0:f269e3021894 210 We now should be ready to use workspace tools script ```build.py``` to compile and build mbed SDK from sources.
elessair 0:f269e3021894 211
elessair 0:f269e3021894 212 We are still using console. You should be already in ```mbed/tools/``` directory if not go to ```mbed/tools/``` and type below command:
elessair 0:f269e3021894 213 ```
elessair 0:f269e3021894 214 $ python build.py -m LPC1768 -t ARM
elessair 0:f269e3021894 215 ```
elessair 0:f269e3021894 216 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:
elessair 0:f269e3021894 217 ```
elessair 0:f269e3021894 218 $ python build.py -m LPC1768 -t ARM -j 4
elessair 0:f269e3021894 219 Building library CMSIS (LPC1768, ARM)
elessair 0:f269e3021894 220 Copy: core_ca9.h
elessair 0:f269e3021894 221 Copy: core_caFunc.h
elessair 0:f269e3021894 222 ...
elessair 0:f269e3021894 223 Compile: us_ticker_api.c
elessair 0:f269e3021894 224 Compile: wait_api.c
elessair 0:f269e3021894 225 Library: mbed.ar
elessair 0:f269e3021894 226 Creating archive 'C:\temp\x\mbed\build\mbed\TARGET_LPC1768\TOOLCHAIN_ARM_STD\mbed.ar'
elessair 0:f269e3021894 227 Copy: board.o
elessair 0:f269e3021894 228 Copy: retarget.o
elessair 0:f269e3021894 229
elessair 0:f269e3021894 230 Completed in: (42.58)s
elessair 0:f269e3021894 231
elessair 0:f269e3021894 232 Build successes:
elessair 0:f269e3021894 233 * ARM::LPC1768
elessair 0:f269e3021894 234 ```
elessair 0:f269e3021894 235 Above command will build mbed SDK for [LPC1768](http://developer.mbed.org/platforms/mbed-LPC1768/) platform using ARM compiler.
elessair 0:f269e3021894 236
elessair 0:f269e3021894 237 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.
elessair 0:f269e3021894 238 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.
elessair 0:f269e3021894 239 ```
elessair 0:f269e3021894 240 $ tree ./mbed/build/
elessair 0:f269e3021894 241 Folder PATH listing
elessair 0:f269e3021894 242 Volume serial number is 006C006F 6243:3EA9
elessair 0:f269e3021894 243 ./MBED/BUILD
elessair 0:f269e3021894 244 +---mbed
elessair 0:f269e3021894 245 +---.temp
elessair 0:f269e3021894 246 ¦ +---TARGET_LPC1768
elessair 0:f269e3021894 247 ¦ +---TOOLCHAIN_ARM_STD
elessair 0:f269e3021894 248 ¦ +---TARGET_NXP
elessair 0:f269e3021894 249 ¦ +---TARGET_LPC176X
elessair 0:f269e3021894 250 ¦ +---TOOLCHAIN_ARM_STD
elessair 0:f269e3021894 251 +---TARGET_LPC1768
elessair 0:f269e3021894 252 +---TARGET_NXP
elessair 0:f269e3021894 253 ¦ +---TARGET_LPC176X
elessair 0:f269e3021894 254 ¦ +---TARGET_MBED_LPC1768
elessair 0:f269e3021894 255 +---TOOLCHAIN_ARM_STD
elessair 0:f269e3021894 256 ```
elessair 0:f269e3021894 257
elessair 0:f269e3021894 258 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.
elessair 0:f269e3021894 259
elessair 0:f269e3021894 260 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:
elessair 0:f269e3021894 261 ```
elessair 0:f269e3021894 262 $ python build.py -m LPC1768 -t IAR
elessair 0:f269e3021894 263 ```
elessair 0:f269e3021894 264
elessair 0:f269e3021894 265 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):
elessair 0:f269e3021894 266 ```
elessair 0:f269e3021894 267 $ python build.py -m LPC1768 -t ARM
elessair 0:f269e3021894 268 Building library CMSIS (LPC1768, ARM)
elessair 0:f269e3021894 269 Building library MBED (LPC1768, ARM)
elessair 0:f269e3021894 270
elessair 0:f269e3021894 271 Completed in: (0.15)s
elessair 0:f269e3021894 272
elessair 0:f269e3021894 273 Build successes:
elessair 0:f269e3021894 274 * ARM::LPC1768
elessair 0:f269e3021894 275 ```
elessair 0:f269e3021894 276
elessair 0:f269e3021894 277 ### build.py script
elessair 0:f269e3021894 278
elessair 0:f269e3021894 279 Build script located in mbed/tools/ is our core script solution to drive compilation, linking and building process for:
elessair 0:f269e3021894 280
elessair 0:f269e3021894 281 * mbed SDK (with libs like Ethernet, RTOS, USB, USB host).
elessair 0:f269e3021894 282 * Tests which also can be linked with libraries like RTOS or Ethernet.
elessair 0:f269e3021894 283
elessair 0:f269e3021894 284 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.
elessair 0:f269e3021894 285
elessair 0:f269e3021894 286 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.
elessair 0:f269e3021894 287 ```
elessair 0:f269e3021894 288 $ python build.py --help
elessair 0:f269e3021894 289 ```
elessair 0:f269e3021894 290
elessair 0:f269e3021894 291 * 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.
elessair 0:f269e3021894 292 Example for one platform build:
elessair 0:f269e3021894 293 ```
elessair 0:f269e3021894 294 $ python build.py -m LPC1768 -t ARM
elessair 0:f269e3021894 295 ```
elessair 0:f269e3021894 296 or for many platforms:
elessair 0:f269e3021894 297 ```
elessair 0:f269e3021894 298 $ python build.py -m LPC1768,NUCLEO_L152RE -t ARM
elessair 0:f269e3021894 299 ```
elessair 0:f269e3021894 300
elessair 0:f269e3021894 301 * Parameter ```-t``` defined which toolchain should be used for mbed SDK build. You can build Mbed SDK for multiple toolchains using one command.
elessair 0:f269e3021894 302 Below example (note there is no space after commas) will compile mbed SDK for Freescale Freedom KL25Z platform using ARM and GCC_ARM compilers:
elessair 0:f269e3021894 303 ```
elessair 0:f269e3021894 304 $ python build.py -m KL25Z -t ARM,GCC_ARM
elessair 0:f269e3021894 305 ```
elessair 0:f269e3021894 306
elessair 0:f269e3021894 307 * You can combine this technique to compile multiple targets with multiple compilers.
elessair 0:f269e3021894 308 Below example will compile mbed SDK for Freescale's KL25Z and KL46Z platforms using ARM and GCC_ARM compilers:
elessair 0:f269e3021894 309 ```
elessair 0:f269e3021894 310 $ python build.py -m KL25Z,KL46Z -t ARM,GCC_ARM
elessair 0:f269e3021894 311 ```
elessair 0:f269e3021894 312
elessair 0:f269e3021894 313 * 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.
elessair 0:f269e3021894 314 Below example will build Mbed SDK library for for NXP LPC1768 platform together with RTOS (```-r``` switch) and Ethernet (```-e``` switch) libraries.
elessair 0:f269e3021894 315 ```
elessair 0:f269e3021894 316 $ python build.py -m LPC1768 -t ARM -r -e
elessair 0:f269e3021894 317 Building library CMSIS (LPC1768, ARM)
elessair 0:f269e3021894 318 Building library MBED (LPC1768, ARM)
elessair 0:f269e3021894 319 Building library RTX (LPC1768, ARM)
elessair 0:f269e3021894 320 Building library RTOS (LPC1768, ARM)
elessair 0:f269e3021894 321 Building library ETH (LPC1768, ARM)
elessair 0:f269e3021894 322
elessair 0:f269e3021894 323 Completed in: (0.48)s
elessair 0:f269e3021894 324
elessair 0:f269e3021894 325 Build successes:
elessair 0:f269e3021894 326 * ARM::LPC1768
elessair 0:f269e3021894 327 ```
elessair 0:f269e3021894 328
elessair 0:f269e3021894 329 * If you’re unsure which platforms and toolchains are supported please use switch ```-S``` to print simple matrix of platform to compiler dependencies.
elessair 0:f269e3021894 330 ```
elessair 0:f269e3021894 331 $ python build.py -S
elessair 0:f269e3021894 332 +-------------------------+-----------+-----------+-----------+-----------+-----------+
elessair 0:f269e3021894 333 | Platform | ARM | uARM | GCC_ARM | IAR | GCC_CR |
elessair 0:f269e3021894 334 +-------------------------+-----------+-----------+-----------+-----------+-----------+
elessair 0:f269e3021894 335 | APPNEARME_MICRONFCBOARD | Supported | Default | Supported | - | - |
elessair 0:f269e3021894 336 | ARCH_BLE | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 337 | ARCH_GPRS | Supported | Default | Supported | Supported | Supported |
elessair 0:f269e3021894 338 ...
elessair 0:f269e3021894 339 | UBLOX_EVK_ODIN_W2 | Supported | Default | Supported | Supported | - |
elessair 0:f269e3021894 340 | WALLBOT_BLE | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 341 | XADOW_M0 | Supported | Default | Supported | Supported | Supported |
elessair 0:f269e3021894 342 +-------------------------+-----------+-----------+-----------+-----------+-----------+
elessair 0:f269e3021894 343 *Default - default on-line compiler
elessair 0:f269e3021894 344 *Supported - supported off-line compiler
elessair 0:f269e3021894 345
elessair 0:f269e3021894 346 Total platforms: 90
elessair 0:f269e3021894 347 Total permutations: 297
elessair 0:f269e3021894 348 ```
elessair 0:f269e3021894 349
elessair 0:f269e3021894 350 Above list can be overwhelming so please do not hesitate to use switch ```-f``` to filter ```Platform``` column.
elessair 0:f269e3021894 351 ```
elessair 0:f269e3021894 352 $ python build.py -S -f ^K
elessair 0:f269e3021894 353 +--------------+-----------+---------+-----------+-----------+--------+
elessair 0:f269e3021894 354 | Platform | ARM | uARM | GCC_ARM | IAR | GCC_CR |
elessair 0:f269e3021894 355 +--------------+-----------+---------+-----------+-----------+--------+
elessair 0:f269e3021894 356 | K20D50M | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 357 | K22F | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 358 | K64F | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 359 | KL05Z | Supported | Default | Supported | Supported | - |
elessair 0:f269e3021894 360 | KL25Z | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 361 | KL43Z | Default | - | Supported | - | - |
elessair 0:f269e3021894 362 | KL46Z | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 363 | NRF51_DK | Default | - | Supported | Supported | - |
elessair 0:f269e3021894 364 | NRF51_DK_OTA | Default | - | Supported | - | - |
elessair 0:f269e3021894 365 +--------------+-----------+---------+-----------+-----------+--------+
elessair 0:f269e3021894 366 *Default - default on-line compiler
elessair 0:f269e3021894 367 *Supported - supported off-line compiler
elessair 0:f269e3021894 368
elessair 0:f269e3021894 369 Total platforms: 9
elessair 0:f269e3021894 370 Total permutations: 28
elessair 0:f269e3021894 371 ```
elessair 0:f269e3021894 372 or just give platform name:
elessair 0:f269e3021894 373 ```
elessair 0:f269e3021894 374 $ python build.py -S -f LPC1768
elessair 0:f269e3021894 375 +----------+---------+-----------+-----------+-----------+-----------+
elessair 0:f269e3021894 376 | Platform | ARM | uARM | GCC_ARM | IAR | GCC_CR |
elessair 0:f269e3021894 377 +----------+---------+-----------+-----------+-----------+-----------+
elessair 0:f269e3021894 378 | LPC1768 | Default | Supported | Supported | Supported | Supported |
elessair 0:f269e3021894 379 +----------+---------+-----------+-----------+-----------+-----------+
elessair 0:f269e3021894 380 *Default - default on-line compiler
elessair 0:f269e3021894 381 *Supported - supported off-line compiler
elessair 0:f269e3021894 382
elessair 0:f269e3021894 383 Total platforms: 1
elessair 0:f269e3021894 384 Total permutations: 6
elessair 0:f269e3021894 385 ```
elessair 0:f269e3021894 386
elessair 0:f269e3021894 387 * You can be more verbose ```-v``` especially if you want to see each compilation / linking command build.py is executing:
elessair 0:f269e3021894 388 ```
elessair 0:f269e3021894 389 $ python build.py -t GCC_ARM -m LPC1768 -j 8 -v
elessair 0:f269e3021894 390 Building library CMSIS (LPC1768, GCC_ARM)
elessair 0:f269e3021894 391 Copy: LPC1768.ld
elessair 0:f269e3021894 392 Compile: startup_LPC17xx.s
elessair 0:f269e3021894 393 [DEBUG] Command: C:/Work/toolchains/gcc_arm_4_8/4_8_2013q4/bin\arm-none-eabi-gcc
elessair 0:f269e3021894 394 -x assembler-with-cpp -c -Wall -Wextra -Wno-unused-parameter -Wno-missing-field-initializers
elessair 0:f269e3021894 395 -fmessage-length=0 -fno-exceptions -fno-builtin -ffunction-sections -fdata-sections -MMD
elessair 0:f269e3021894 396 -fno-delete-null-pointer-checks -fomit-frame-pointer -mcpu=cortex-m3 -mthumb -O2
elessair 0:f269e3021894 397 -DTARGET_LPC1768 -DTARGET_M3 -DTARGET_CORTEX_M -DTARGET_NXP -DTARGET_LPC176X
elessair 0:f269e3021894 398 -DTARGET_MBED_LPC1768 -DTOOLCHAIN_GCC_ARM -DTOOLCHAIN_GCC -D__CORTEX_M3 -DARM_MATH_CM3
elessair 0:f269e3021894 399 -DMBED_BUILD_TIMESTAMP=1424903604.77 -D__MBED__=1 -IC:\Work\mbed\libraries\mbed\targets\cmsis
elessair 0:f269e3021894 400 -IC:\Work\mbed\libraries\mbed\targets\cmsis\TARGET_NXP
elessair 0:f269e3021894 401 -IC:\Work\mbed\libraries\mbed\targets\cmsis\TARGET_NXP\TARGET_LPC176X -IC:\Work\mbed\libraries\mbed\targets\cmsis\TARGET_NXP\TARGET_LPC176X\TOOLCHAIN_GCC_ARM
elessair 0:f269e3021894 402 -o C:\Work\mbed\build\mbed\.temp\TARGET_LPC1768\TOOLCHAIN_GCC_ARM\TARGET_NXP\TARGET_LPC176X\TOOLCHAIN_GCC_ARM\startup_LPC17xx.o
elessair 0:f269e3021894 403 C:\Work\mbed\libraries\mbed\targets\cmsis\TARGET_NXP\TARGET_LPC176X\TOOLCHAIN_GCC_ARM\startup_LPC17xx.s
elessair 0:f269e3021894 404 [DEBUG] Return: 0
elessair 0:f269e3021894 405 ...
elessair 0:f269e3021894 406 ```
elessair 0:f269e3021894 407
elessair 0:f269e3021894 408 ## CppCheck analysis
elessair 0:f269e3021894 409 [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).
elessair 0:f269e3021894 410
elessair 0:f269e3021894 411 Prerequisites:
elessair 0:f269e3021894 412 * Please install ```CppCheck``` on your system before you want to use it with build scripts.
elessair 0:f269e3021894 413 * You should also add Cppcheck to your system path.
elessair 0:f269e3021894 414
elessair 0:f269e3021894 415 ```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.
elessair 0:f269e3021894 416
elessair 0:f269e3021894 417 * 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.
elessair 0:f269e3021894 418
elessair 0:f269e3021894 419 * Cppcheck analysis can take up to few minutes on slower machines.
elessair 0:f269e3021894 420
elessair 0:f269e3021894 421 * 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```, ...).
elessair 0:f269e3021894 422
elessair 0:f269e3021894 423 Example:
elessair 0:f269e3021894 424 ```
elessair 0:f269e3021894 425 $ python build.py -t uARM -m NUCLEO_F334R8 --cppcheck
elessair 0:f269e3021894 426 ```
elessair 0:f269e3021894 427
elessair 0:f269e3021894 428 # make.py script
elessair 0:f269e3021894 429 ```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```.
elessair 0:f269e3021894 430 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.
elessair 0:f269e3021894 431
elessair 0:f269e3021894 432 Just for sake of example please see few ways to use ```make.py``` together with Freedom K64F board.
elessair 0:f269e3021894 433
elessair 0:f269e3021894 434 * We need to build mbed SDK (in directory ```mbed/build/```:
elessair 0:f269e3021894 435 ```
elessair 0:f269e3021894 436 $ python build.py -t GCC_ARM -m K64F -j 8
elessair 0:f269e3021894 437 Building library CMSIS (K64F, GCC_ARM)
elessair 0:f269e3021894 438 Building library MBED (K64F, GCC_ARM)
elessair 0:f269e3021894 439
elessair 0:f269e3021894 440 Completed in: (0.59)s
elessair 0:f269e3021894 441
elessair 0:f269e3021894 442 Build successes:
elessair 0:f269e3021894 443 * GCC_ARM::K64F
elessair 0:f269e3021894 444 ```
elessair 0:f269e3021894 445 * We can print all 'programs' (test cases) ```make.py``` can build for us:
elessair 0:f269e3021894 446 ```
elessair 0:f269e3021894 447 $ python make.py -L
elessair 0:f269e3021894 448 .
elessair 0:f269e3021894 449 [ 0] MBED_A1: Basic
elessair 0:f269e3021894 450 [ 1] MBED_A2: Semihost file system
elessair 0:f269e3021894 451 [ 2] MBED_A3: C++ STL
elessair 0:f269e3021894 452 [ 3] MBED_A4: I2C TMP102
elessair 0:f269e3021894 453 .
elessair 0:f269e3021894 454 ```
elessair 0:f269e3021894 455 For example 'program' under index ```2``` is ```MBED_A3``` test case we can build and flash onto K64F board.
elessair 0:f269e3021894 456 * Building test with ```make.py``` by specifying test case name with ```-n``` option:
elessair 0:f269e3021894 457 ```
elessair 0:f269e3021894 458 $ python make.py -t GCC_ARM -m K64F -n MBED_A3
elessair 0:f269e3021894 459 Building project STL (K64F, GCC_ARM)
elessair 0:f269e3021894 460 Compile: main.cpp
elessair 0:f269e3021894 461 [Warning] main.cpp@76: In function 'int main()': deprecated conversion from string constant to 'char*' [-Wwrite-strings]
elessair 0:f269e3021894 462 .
elessair 0:f269e3021894 463 .
elessair 0:f269e3021894 464 .
elessair 0:f269e3021894 465 [Warning] main.cpp@76: In function 'int main()': deprecated conversion from string constant to 'char*' [-Wwrite-strings]
elessair 0:f269e3021894 466 Compile: test_env.cpp
elessair 0:f269e3021894 467 Link: stl
elessair 0:f269e3021894 468 Elf2Bin: stl
elessair 0:f269e3021894 469 Image: C:\Work\mbed\build\test\K64F\GCC_ARM\MBED_A3\stl.bin
elessair 0:f269e3021894 470 ```
elessair 0:f269e3021894 471 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:
elessair 0:f269e3021894 472 ```
elessair 0:f269e3021894 473 C:\Work\mbed\build\test\K64F\GCC_ARM\MBED_A3\stl.bin
elessair 0:f269e3021894 474 ```
elessair 0:f269e3021894 475
elessair 0:f269e3021894 476 For more help type ```$ python make.py --help``` in your command line.
elessair 0:f269e3021894 477
elessair 0:f269e3021894 478 # project.py script
elessair 0:f269e3021894 479 ```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:
elessair 0:f269e3021894 480 * codesourcery.
elessair 0:f269e3021894 481 * coide.
elessair 0:f269e3021894 482 * ds5_5.
elessair 0:f269e3021894 483 * emblocks.
elessair 0:f269e3021894 484 * gcc_arm.
elessair 0:f269e3021894 485 * iar.
elessair 0:f269e3021894 486 * kds.
elessair 0:f269e3021894 487 * lpcxpresso.
elessair 0:f269e3021894 488 * uvision.
elessair 0:f269e3021894 489
elessair 0:f269e3021894 490 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```).
elessair 0:f269e3021894 491
elessair 0:f269e3021894 492 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```.
elessair 0:f269e3021894 493 ```
elessair 0:f269e3021894 494 $ python project.py -m K64F -n MBED_A3 -i gcc_arm
elessair 0:f269e3021894 495 Copy: test_env.h
elessair 0:f269e3021894 496 Copy: AnalogIn.h
elessair 0:f269e3021894 497 Copy: AnalogOut.h
elessair 0:f269e3021894 498 .
elessair 0:f269e3021894 499 .
elessair 0:f269e3021894 500 .
elessair 0:f269e3021894 501 Copy: K64FN1M0xxx12.ld
elessair 0:f269e3021894 502 Copy: main.cpp
elessair 0:f269e3021894 503
elessair 0:f269e3021894 504 Successful exports:
elessair 0:f269e3021894 505 * K64F::gcc_arm C:\Work\mbed\build\export\MBED_A3_gcc_arm_K64F.zip
elessair 0:f269e3021894 506 ```
elessair 0:f269e3021894 507 You can see exporter placed compressed project export in ```zip``` file in ```mbed/build/export/``` directory.
elessair 0:f269e3021894 508
elessair 0:f269e3021894 509 Example export file ```MBED_A3_gcc_arm_K64F.zip``` structure:
elessair 0:f269e3021894 510 ```
elessair 0:f269e3021894 511 MBED_A3
elessair 0:f269e3021894 512 ├───env
elessair 0:f269e3021894 513 └───mbed
elessair 0:f269e3021894 514 ├───api
elessair 0:f269e3021894 515 ├───common
elessair 0:f269e3021894 516 ├───hal
elessair 0:f269e3021894 517 └───targets
elessair 0:f269e3021894 518 ├───cmsis
elessair 0:f269e3021894 519 │ └───TARGET_Freescale
elessair 0:f269e3021894 520 │ └───TARGET_MCU_K64F
elessair 0:f269e3021894 521 │ └───TOOLCHAIN_GCC_ARM
elessair 0:f269e3021894 522 └───hal
elessair 0:f269e3021894 523 └───TARGET_Freescale
elessair 0:f269e3021894 524 └───TARGET_KPSDK_MCUS
elessair 0:f269e3021894 525 ├───TARGET_KPSDK_CODE
elessair 0:f269e3021894 526 │ ├───common
elessair 0:f269e3021894 527 │ │ └───phyksz8081
elessair 0:f269e3021894 528 │ ├───drivers
elessair 0:f269e3021894 529 │ │ ├───clock
elessair 0:f269e3021894 530 │ │ ├───enet
elessair 0:f269e3021894 531 │ │ │ └───src
elessair 0:f269e3021894 532 │ │ ├───interrupt
elessair 0:f269e3021894 533 │ │ └───pit
elessair 0:f269e3021894 534 │ │ ├───common
elessair 0:f269e3021894 535 │ │ └───src
elessair 0:f269e3021894 536 │ ├───hal
elessair 0:f269e3021894 537 │ │ ├───adc
elessair 0:f269e3021894 538 │ │ ├───can
elessair 0:f269e3021894 539 │ │ ├───dac
elessair 0:f269e3021894 540 │ │ ├───dmamux
elessair 0:f269e3021894 541 │ │ ├───dspi
elessair 0:f269e3021894 542 │ │ ├───edma
elessair 0:f269e3021894 543 │ │ ├───enet
elessair 0:f269e3021894 544 │ │ ├───flextimer
elessair 0:f269e3021894 545 │ │ ├───gpio
elessair 0:f269e3021894 546 │ │ ├───i2c
elessair 0:f269e3021894 547 │ │ ├───llwu
elessair 0:f269e3021894 548 │ │ ├───lptmr
elessair 0:f269e3021894 549 │ │ ├───lpuart
elessair 0:f269e3021894 550 │ │ ├───mcg
elessair 0:f269e3021894 551 │ │ ├───mpu
elessair 0:f269e3021894 552 │ │ ├───osc
elessair 0:f269e3021894 553 │ │ ├───pdb
elessair 0:f269e3021894 554 │ │ ├───pit
elessair 0:f269e3021894 555 │ │ ├───pmc
elessair 0:f269e3021894 556 │ │ ├───port
elessair 0:f269e3021894 557 │ │ ├───rcm
elessair 0:f269e3021894 558 │ │ ├───rtc
elessair 0:f269e3021894 559 │ │ ├───sai
elessair 0:f269e3021894 560 │ │ ├───sdhc
elessair 0:f269e3021894 561 │ │ ├───sim
elessair 0:f269e3021894 562 │ │ ├───smc
elessair 0:f269e3021894 563 │ │ ├───uart
elessair 0:f269e3021894 564 │ │ └───wdog
elessair 0:f269e3021894 565 │ └───utilities
elessair 0:f269e3021894 566 │ └───src
elessair 0:f269e3021894 567 └───TARGET_MCU_K64F
elessair 0:f269e3021894 568 ├───device
elessair 0:f269e3021894 569 │ ├───device
elessair 0:f269e3021894 570 │ │ └───MK64F12
elessair 0:f269e3021894 571 │ └───MK64F12
elessair 0:f269e3021894 572 ├───MK64F12
elessair 0:f269e3021894 573 └───TARGET_FRDM
elessair 0:f269e3021894 574 ```
elessair 0:f269e3021894 575
elessair 0:f269e3021894 576 After unpacking exporter ```zip``` file we can go to directory and see files inside MBED_A3 directory:
elessair 0:f269e3021894 577 ```
elessair 0:f269e3021894 578 $ ls
elessair 0:f269e3021894 579 GettingStarted.htm Makefile env main.cpp mbed
elessair 0:f269e3021894 580 ```
elessair 0:f269e3021894 581 Exporter generated for us ```Makefile``` so now we can build our software:
elessair 0:f269e3021894 582 ```
elessair 0:f269e3021894 583 $ make -j 8
elessair 0:f269e3021894 584 .
elessair 0:f269e3021894 585 .
elessair 0:f269e3021894 586 .
elessair 0:f269e3021894 587 text data bss dec hex filename
elessair 0:f269e3021894 588 29336 184 336 29856 74a0 MBED_A3.elf
elessair 0:f269e3021894 589 ```
elessair 0:f269e3021894 590
elessair 0:f269e3021894 591 We can see root directory of exporter project is now populated with binary files:
elessair 0:f269e3021894 592 * MBED_A3.bin.
elessair 0:f269e3021894 593 * MBED_A3.elf .
elessair 0:f269e3021894 594 * MBED_A3.hex.
elessair 0:f269e3021894 595 You have also map file ```MBED_A3.map``` for your disposal.
elessair 0:f269e3021894 596 ```
elessair 0:f269e3021894 597 $ ls
elessair 0:f269e3021894 598 GettingStarted.htm MBED_A3.bin MBED_A3.elf MBED_A3.hex MBED_A3.map Makefile env main.cpp main.d main.o mbed
elessair 0:f269e3021894 599 ```
elessair 0:f269e3021894 600