Greg Steiert / pegasus_dev

Development mbed library for MAX32630FTHR

Dependents:   blinky_max32630fthr

docs/Toolchain_Profiles.md@0:5c4d7b2438d3, 2016-11-11 (annotated)

Committer:
switches
Date:
Fri Nov 11 20:59:50 2016 +0000
Revision:
0:5c4d7b2438d3
Initial commit

Who changed what in which revision?

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