ARMmbed · iriark01 · Oct 15, 2018 · Oct 15, 2018 · Oct 15, 2018 · Oct 15, 2018
diff --git a/docs.json b/docs.json
@@ -857,10 +857,6 @@
                             {
                                 "type": "markdown",
                                 "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/CLI/debug_builds_cli.md"
-                            },
-                            {
-                                "type": "markdown",
-                                "url": "https://github.com/ARMmbed/mbed-os-5-docs/blob/development/docs/tools/CLI/toolchain_profiles.md"
                             }
                         ]
                     }

diff --git a/docs/reference/configuration/configuration.md b/docs/reference/configuration/configuration.md
@@ -13,6 +13,8 @@ The Arm Mbed OS configuration system gathers and interprets the configuration de
 
 <span class="notes">**Note:** In prior releases, the configuration system provided a method for adding custom targets. The Mbed OS tools now look for custom targets in a file named `custom_targets.json` in the root of an application and treat custom targets the same as [Mbed targets](/docs/development/tools/adding-and-configuring-targets.html).</span>
 
+<span class="notes">**Note:** This document only deals with passing macros to part of the toolchain suite. For documentation about how to control other flags to the compiler see the [build profiles documentation](/docs/latest/tools/CLI/build_profiles.html).</span>
+
 ### Examining available configuration parameters
 
 Mbed CLI includes a command for listing and explaining the compile time configuration, `mbed compile --config`. This command prints a summary of configuration parameters, such as:

diff --git a/docs/tools/CLI/build_profiles.md b/docs/tools/CLI/build_profiles.md
@@ -25,3 +25,74 @@ Arm Mbed OS 5 supports three primary build profiles: *develop*, *debug* and *rel
 - Chip goes to sleep when going idle:
     - Debugger is likely to drop connection.
     - Breaks the local file system on the [Mbed interface](/docs/development/introduction/index.html) on some boards.
+
+### User defined profiles
+
+A toolchain or build system profile is a set of flags that is guaranteed to be passed to the underlying compiler suite.
+
+These flags are stored in a JSON file that may be merged with other JSON files of the same structure.
+
+#### JSON toolchain profile format
+
+The JSON object that represents a toolchain profile is a dictionary mapping from toolchains, such as `GCC_ARM`, to their flags, such as `-O3`.
+
+The structure is as follows: each toolchain supported by a toolchain profile has a dictionary in the root dictionary. This dictionary contains a mapping from a flag type to a list of flags that should be passed to the corresponding part of the compiler suite.
+
+The required flag types are:
+
+| Key      | Description                           |
+|:---------|:--------------------------------------|
+| `asm`    | Flags for the Assembler               |
+| `c`      | Flags for the C Compiler              |
+| `common` | Flags for both the C and C++ Compilers|
+| `cxx`    | Flags for the C++ Compiler            |
+| `ld`     | Flags for the Linker                  |
+
+#### Example
+
+An example of a toolchain profile:
+
+```json
+{
+    "GCC_ARM": {
+        "common": ["-c", "-Wall", "-Wextra",
+                   "-Wno-unused-parameter", "-Wno-missing-field-initializers",
+                   "-fmessage-length=0", "-fno-exceptions", "-fno-builtin",
+                   "-ffunction-sections", "-fdata-sections", "-funsigned-char",
+                   "-MMD", "-fno-delete-null-pointer-checks",
+                   "-fomit-frame-pointer", "-Os"],
+        "asm": ["-x", "assembler-with-cpp"],
+        "c": ["-std=gnu99"],
+        "cxx": ["-std=gnu++98", "-fno-rtti", "-Wvla"],
+        "ld": ["-Wl,--gc-sections", "-Wl,--wrap,main", "-Wl,--wrap,_malloc_r",
+               "-Wl,--wrap,_free_r", "-Wl,--wrap,_realloc_r",
+               "-Wl,--wrap,_calloc_r", "-Wl,--wrap,exit", "-Wl,--wrap,atexit"]
+    },
+    "ARM": {
+        "common": ["-c", "--gnu", "-Otime", "--split_sections",
+                   "--apcs=interwork", "--brief_diagnostics", "--restrict",
+                   "--multibyte_chars", "-O3"],
+        "asm": [],
+        "c": ["--md", "--no_depend_system_headers", "--c99", "-D__ASSERT_MSG"],
+        "cxx": ["--cpp", "--no_rtti", "--no_vla"],
+        "ld": []
+    },
+    "IAR": {
+        "common": [
+            "--no_wrap_diagnostics", "non-native end of line sequence", "-e",
+            "--diag_suppress=Pa050,Pa084,Pa093,Pa082", "-Oh"],
+        "asm": [],
+        "c": ["--vla"],
+        "cxx": ["--guard_calls", "--no_static_destruction"],
+        "ld": ["--skip_dynamic_initialization", "--threaded_lib"]
+    }
+}
+```
+
+From this toolchain profile, we can tell that:
+
+- `GCC_ARM`, `ARM` and `IAR` compiler suites are supported.
+- The `ARM` C and C++ compilers will be using optimization level `-O3`.
+- The `IAR` linker will skip dynamic initialization.
+
+And so on.
diff --git a/docs/tools/CLI/cli-compile.md b/docs/tools/CLI/cli-compile.md
@@ -42,7 +42,7 @@ The arguments for *compile* are:
 - `--source <SOURCE>` selects the source directory. The default is `.` (the current directory). You can specify multiple source locations, even outside the program tree.
 - `--build <BUILD>` selects the build directory. Default: `BUILD/` inside your program root.
    <span class="notes">**Note**: `mbed compile` ignores the current build directory; creating multiple build directories leads to errors.</span>
-- `--profile <PATH_TO_BUILD_PROFILE>` selects a path to a build profile configuration file. Example: `mbed-os/tools/profiles/debug.json`.
+- `--profile <PATH_TO_BUILD_PROFILE>` selects a path to a build profile configuration file. Example: `debug`. See the dedicated [build profile documentation](/docs/tools/CLI/build_profiles.html) for more detail.
 - `--library` compiles the code as a [static `.a/.ar` library](#compiling-static-libraries).
 - `--no-archive` suppresses the creation of `.a/.ar` files created by `--library`, producing many `.o` files instead.
    <span class="notes">**Note**: This option does nothing without `--library`.</span>
@@ -128,14 +128,12 @@ $ mbed compile -t GCC_ARM -m K64F -c -DUVISOR_PRESENT
 
 ##### Compile in debug mode
 
-To compile in debug mode (as opposed to the default *develop* mode), use `--profile mbed-os/tools/profiles/debug.json` in the compile command-line:
+To compile in debug mode (as opposed to the default *develop* mode), use `--profile debug` in the compile command-line:
 
 ```
-$ mbed compile -t GCC_ARM -m K64F --profile mbed-os/tools/profiles/debug.json
+$ mbed compile -t GCC_ARM -m K64F --profile debug
 ```
 
-<span class="tips">**Tip:** If you have files that you want to compile only in debug mode, put them in a directory called `TARGET_DEBUG` at any level of your tree (then use `--profile` as explained above).
-</span>
 
 #### Automate toolchain and target selection
 

diff --git a/docs/tools/CLI/cli-test-debug.md b/docs/tools/CLI/cli-test-debug.md
@@ -17,7 +17,7 @@ The arguments to `test` are:
 - `-n <TESTS_BY_NAME>`: to limit the tests built or run to a comma separated list, for example, `test1, test2, test3`.
 - `--source <SOURCE>`: to select the source directory. The default is `.` for the the current directory. You can specify multiple source locations, even outside the program tree.
 - `--build <BUILD>`: to select the build directory. The default is `BUILD/` inside your program.
-- `--profile <PATH_TO_BUILD_PROFILE>`: to select a path to a build profile configuration file, for example, `mbed-os/tools/profiles/debug.json`.
+- `--profile <PATH_TO_BUILD_PROFILE>`: to select a path to a build profile configuration file, for example, `mbed-os/tools/profiles/debug.json`. See the dedicated [build profile documentation](/docs/tools/CLI/build_profiles.html) for more detail.
 - `-c or --clean`: to clean the build directory before compiling.
 - `--test-spec <TEST_SPEC>`: to set the path for the test specification file used when building and running tests. The default path is the build directory.
 - `--build-data <BUILD_DATA>`: dumps build_data to this file.

diff --git a/docs/tools/CLI/debug_builds_cli.md b/docs/tools/CLI/debug_builds_cli.md
@@ -21,19 +21,19 @@ $ mbed compile -o debug-info
 **Arm Mbed 2.0**
 
 ```
-$ mbed compile --profile .temp/tools/profiles/debug.json
+$ mbed compile --profile debug
 ```
 
 ### Exporting with debug symbols
 
 You can also enable debug symbols when [exporting your project](exporting.html) by using:
 
 ```
-$ mbed export -i uvision -m K64F --profile mbed-os/tools/profiles/debug.json
+$ mbed export -i uvision -m K64F --profile debug
 ```
 
 Make release builds by using:
 
 ```
-$ mbed export -i uvision -m K64F --profile mbed-os/tools/profiles/default.json
+$ mbed export -i uvision -m K64F --profile release
 ```
diff --git a/docs/tools/CLI/toolchain_profiles.md b/docs/tools/CLI/toolchain_profiles.md
diff --git a/docs/tools/build_rules.md b/docs/tools/build_rules.md
@@ -1,6 +1,6 @@
 ## Mbed OS build rules
 
-The Mbed OS build tools scan your project for source files every time you compile. This document describes the rules that the build tools use to decide which source files to include in each build. The Mbed OS build tools use the [target configuration](adding-and-configuring-targets.html) found in `targets.json`, `mbed_app.json` and `mbed_lib.json` as input to these rules.
+The Mbed OS build tools scan your project for source files every time you compile. This document describes the rules that the build tools use to decide which source files to include in each build. The Mbed OS build tools use the [target configuration](adding-and-configuring-targets.html) found in `targets.json`, `mbed_app.json` and `mbed_lib.json` as input to these rules. If you are looking for how to pass options to the compilers, please see the [build profiles documentation](http://os.mbed.com/docs/latest/tools/CLI/build_profiles.html).
 
 The build tools include every source file found in the project unless it is in a label directory, it is in a test directory or it matches a pattern in an `.mbedignore file`.
 

diff --git a/docs/tools/debug/debug_intro.md b/docs/tools/debug/debug_intro.md
@@ -24,7 +24,7 @@ In your project folder, run:
 # alternatively, use -i make_armc5 for ARMCC, or -i make_iar for IAR
 # replace K64F with your target board
 
-$ mbed export -i make_gcc_arm -m K64F --profile mbed-os/tools/profiles/debug.json
+$ mbed export -i make_gcc_arm -m K64F
 ```
 
 ##### Serial terminal

diff --git a/docs/tutorials/debug/eclipse_pyocd.md b/docs/tutorials/debug/eclipse_pyocd.md
@@ -43,7 +43,7 @@ In your project folder, run:
 # Replace K64F with your target board
 # If you're not using GCC ARM, use -i eclipse_armc5 for ARMCC, or -i eclipse_iar for IAR
 
-$ mbed export -i eclipse_gcc_arm -m K64F --profile mbed-os/tools/profiles/debug.json
+$ mbed export -i eclipse_gcc_arm -m K64F --profile debug
 ```
 
 ### Importing the project in Eclipse
@@ -121,5 +121,5 @@ We build using Make, but you can also use Mbed CLI for building from Eclipse:
 1. Go to *Project > Properties > C/C++ Build*.
 1. Remove the check *Use default build command*.
 1. Set *Build command* to `mbed`.
-1. Under *Behavior* > *Build (Incremental build)*, select your Mbed CLI build options. For example: `compile -m K64F -t GCC_ARM --profile ${CWD}mbed-os/tools/profiles/debug.json`.
+1. Under *Behavior* > *Build (Incremental build)*, select your Mbed CLI build options. For example: `compile -m K64F -t GCC_ARM --profile debug`.
 1. Make sure to update the paths to the `.elf` file in your debug configuration.
diff --git a/docs/tutorials/debug/keil_uvision.md b/docs/tutorials/debug/keil_uvision.md
@@ -23,7 +23,7 @@ To export your project to uVision, you can use either the Online Compiler or Mbe
 
     ```
     # replace K64F with your target board
-    $ mbed export -i uvision5 -m K64F --profile mbed-os/tools/profiles/debug.json
+    $ mbed export -i uvision5 -m K64F
     ```
 
 ### Starting a debug session

diff --git a/docs/tutorials/debug/vs_code.md b/docs/tutorials/debug/vs_code.md
@@ -40,7 +40,7 @@ In your project folder, run:
 # alternatively, use -i vscode_armc5 for ARMCC, or -i vscode_iar for IAR
 # replace K64F with your target board
 
-$ mbed export -i vscode_gcc_arm -m K64F --profile mbed-os/tools/profiles/debug.json
+$ mbed export -i vscode_gcc_arm -m K64F --profile debug
 ```
 
 ### Configuring the debugger