erkin yucel / mbed-os

mbed os with nrf51 internal bandgap enabled to read battery level

Dependents:   BLE_file_test BLE_Blink ExternalEncoder

docs/Toolchain_Profiles.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 # Toolchain Profiles User Perspective
elessair 0:f269e3021894 2
elessair 0:f269e3021894 3 A Toolchain or build system Profile is a set of flags that is garenteed to be passed to the underlieing compiler suite.
elessair 0:f269e3021894 4 These flags are stored in a JSON file that may be merged with other JSON files of the same structure.
elessair 0:f269e3021894 5
elessair 0:f269e3021894 6 ## JSON Toolchain Profile Format
elessair 0:f269e3021894 7
elessair 0:f269e3021894 8 The JSON object that represents a Toolchain Profile is a dict mapping from Toolchains, like `GCC_ARM`, to their flags, like `-O3`.
elessair 0:f269e3021894 9 The structure is as follows: Each toolchain supported by a Toolchain Profile has an dict in the root dict.
elessair 0:f269e3021894 10 This dict contains a mapping from a flag type to a list of flags that should be passed the corresponding part of the compiler suite.
elessair 0:f269e3021894 11 The required flag types are:
elessair 0:f269e3021894 12
elessair 0:f269e3021894 13 | Key | Description |
elessair 0:f269e3021894 14 |:---------|:--------------------------------------|
elessair 0:f269e3021894 15 | `c` | Flags for the C Compiler |
elessair 0:f269e3021894 16 | `cxx` | Flags for the C++ Compiler |
elessair 0:f269e3021894 17 | `common` | Flags for both the C and C++ Compilers|
elessair 0:f269e3021894 18 | `asm` | Flags for the Assembler |
elessair 0:f269e3021894 19
elessair 0:f269e3021894 20 ## Example
elessair 0:f269e3021894 21
elessair 0:f269e3021894 22 An example of a Toolchain Profile is given below:
elessair 0:f269e3021894 23 ```json
elessair 0:f269e3021894 24 {
elessair 0:f269e3021894 25 "GCC_ARM": {
elessair 0:f269e3021894 26 "common": ["-c", "-Wall", "-Wextra",
elessair 0:f269e3021894 27 "-Wno-unused-parameter", "-Wno-missing-field-initializers",
elessair 0:f269e3021894 28 "-fmessage-length=0", "-fno-exceptions", "-fno-builtin",
elessair 0:f269e3021894 29 "-ffunction-sections", "-fdata-sections", "-funsigned-char",
elessair 0:f269e3021894 30 "-MMD", "-fno-delete-null-pointer-checks",
elessair 0:f269e3021894 31 "-fomit-frame-pointer", "-Os"],
elessair 0:f269e3021894 32 "asm": ["-x", "assembler-with-cpp"],
elessair 0:f269e3021894 33 "c": ["-std=gnu99"],
elessair 0:f269e3021894 34 "cxx": ["-std=gnu++98", "-fno-rtti", "-Wvla"],
elessair 0:f269e3021894 35 "ld": ["-Wl,--gc-sections", "-Wl,--wrap,main", "-Wl,--wrap,_malloc_r",
elessair 0:f269e3021894 36 "-Wl,--wrap,_free_r", "-Wl,--wrap,_realloc_r",
elessair 0:f269e3021894 37 "-Wl,--wrap,_calloc_r", "-Wl,--wrap,exit", "-Wl,--wrap,atexit"]
elessair 0:f269e3021894 38 },
elessair 0:f269e3021894 39 "ARM": {
elessair 0:f269e3021894 40 "common": ["-c", "--gnu", "-Otime", "--split_sections",
elessair 0:f269e3021894 41 "--apcs=interwork", "--brief_diagnostics", "--restrict",
elessair 0:f269e3021894 42 "--multibyte_chars", "-O3"],
elessair 0:f269e3021894 43 "asm": [],
elessair 0:f269e3021894 44 "c": ["--md", "--no_depend_system_headers", "--c99", "-D__ASSERT_MSG"],
elessair 0:f269e3021894 45 "cxx": ["--cpp", "--no_rtti", "--no_vla"],
elessair 0:f269e3021894 46 "ld": []
elessair 0:f269e3021894 47 },
elessair 0:f269e3021894 48 "IAR": {
elessair 0:f269e3021894 49 "common": [
elessair 0:f269e3021894 50 "--no_wrap_diagnostics", "non-native end of line sequence", "-e",
elessair 0:f269e3021894 51 "--diag_suppress=Pa050,Pa084,Pa093,Pa082", "-Oh"],
elessair 0:f269e3021894 52 "asm": [],
elessair 0:f269e3021894 53 "c": ["--vla"],
elessair 0:f269e3021894 54 "cxx": ["--guard_calls", "--no_static_destruction"],
elessair 0:f269e3021894 55 "ld": ["--skip_dynamic_initialization", "--threaded_lib"]
elessair 0:f269e3021894 56 }
elessair 0:f269e3021894 57 }
elessair 0:f269e3021894 58 ```
elessair 0:f269e3021894 59
elessair 0:f269e3021894 60 From this Toolchain profile, we can tell that:
elessair 0:f269e3021894 61 - `GCC_ARM`, `ARM`, and `IAR` compiler suites are supported.
elessair 0:f269e3021894 62 - The `ARM` C and C++ Compilers will be using optimization level `-O3`
elessair 0:f269e3021894 63 - The `IAR` linker will skip dynamic initialization
elessair 0:f269e3021894 64 - etc.
elessair 0:f269e3021894 65
elessair 0:f269e3021894 66 # Toolchain Profile API Perspective
elessair 0:f269e3021894 67
elessair 0:f269e3021894 68 The Toolchains no longer take in an optional argument, `build_profile`, that will contain a map from flag types to lists of flags.
elessair 0:f269e3021894 69 This looks exactly the same in python as it does in the JSON format above.
elessair 0:f269e3021894 70 The meaning of the flags, and which ones are required is the same as the User Perspective
elessair 0:f269e3021894 71 A developer using the API must parse the User provided files themselves and extract the appropriate sub-dict from the file afterwards.
elessair 0:f269e3021894 72 A convienence function that does this for a developer is `tools.options.extract_profile` and will call args_error when a Toolchain Profile JSON file does not provide flags for the selected Toolchain.