Add -o to mbed compile and pass it to the underlying tools

Add documentation regarding `mbed compile -o`
Rename --mcu references to --target (as per Simon's suggestion)

Author: screamerbg

README.md

@@ -315,6 +315,7 @@ The arguments for *compile* are:
 * `-t <TOOLCHAIN>` to select a toolchain (of those defined in `mbed_settings.py`, see above). The value can be either `ARM` (ARM Compiler 5), `GCC_ARM` (GNU ARM Embedded), or `IAR` (IAR Embedded Workbench for ARM).
 * `--source <SOURCE>` to select the source directory. The default is `.` (the current directorty). You can specify multiple source locations, even outside the program tree.
 * `--build <BUILD>` to select the build directory. Default: `.build/` inside your program.
+* `--options <OPTIONS>` to select compile options. Examples: "debug-info": will generate debugging information; "small-build" will use microlib/nanolib, but limit RTOS to single thread; "save-asm": will save the asm generated by the compiler
 * `--library` to compile the code as a [static .a/.ar library](#compiling-static-libraries).
 * `--config` to inspect the run-time compile configuration (see below).
 * `-S` or `--supported` shows a matrix of the supported targets and toolchains.

mbed/mbed.py

@@ -1284,9 +1284,9 @@ def get_tools(self):
             error('The mbed tools were not found in "%s". \n Run `mbed deploy` to install dependencies and tools. ' % self.path, -1)
         return mbed_tools_path
 
-    def get_mcu(self, mcu=None):
+    def get_target(self, target=None):
         target_cfg = self.get_cfg('TARGET')
-        target = mcu if mcu else target_cfg
+        target = target if target else target_cfg
         if target is None:
             error('Please specify compile target using the -m switch or set default target using command "target"', 1)
         return target
@@ -1959,7 +1959,8 @@ def status_(ignore=False):
 # Compile command which invokes the mbed OS native build system
 @subcommand('compile',
     dict(name=['-t', '--toolchain'], help='Compile toolchain. Example: ARM, GCC_ARM, IAR'),
-    dict(name=['-m', '--mcu'], help='Compile target. Example: K64F, NUCLEO_F401RE, NRF51822...'),
+    dict(name=['-m', '--target'], help='Compile target MCU. Example: K64F, NUCLEO_F401RE, NRF51822...'),
+    dict(name=['-o', '--options'], action='append', help='Compile options. Examples: "debug-info": generate debugging information; "small-build" to use microlib/nanolib, but limit RTOS to single thread; "save-asm": save the asm generated by the compiler'),
     dict(name='--library', dest='compile_library', action='store_true', help='Compile the current program or library as a static library.'),
     dict(name='--config', dest='compile_config', action='store_true', help='Show run-time compile configuration'),
     dict(name='--prefix', dest='config_prefix', action='append', help='Restrict listing to parameters that have this prefix'),
@@ -1970,7 +1971,7 @@ def status_(ignore=False):
     dict(name=['-S', '--supported'], dest='supported', action='store_true', help='Shows supported matrix of targets and toolchains'),
     help='Compile code using the mbed build tools',
     description=("Compile this program using the mbed build tools."))
-def compile_(toolchain=None, mcu=None, source=False, build=False, compile_library=False, compile_config=False, config_prefix=None, clean=False, artifact_name=None, supported=False):
+def compile_(toolchain=None, target=None, options=False, compile_library=False, compile_config=False, config_prefix=None, source=False, build=False, clean=False, artifact_name=None, supported=False):
     # Gather remaining arguments
     args = remainder
     # Find the root of the program
@@ -1994,14 +1995,15 @@ def compile_(toolchain=None, mcu=None, source=False, build=False, compile_librar
               env=env)
         return
 
-    target = program.get_mcu(mcu)
+    target = program.get_target(target)
     tchain = program.get_toolchain(toolchain)
     macros = program.get_macros()
 
     if compile_config:
         # Compile configuration
         popen(['python', os.path.join(tools_dir, 'get_config.py')]
               + ['-t', tchain, '-m', target]
+              + list(chain.from_iterable(izip(repeat('-o'), options or [])))
               + list(chain.from_iterable(izip(repeat('--source'), source)))
               + (['-v'] if verbose else [])
               + (list(chain.from_iterable(izip(repeat('--prefix'), config_prefix))) if config_prefix else []),
@@ -2014,9 +2016,10 @@ def compile_(toolchain=None, mcu=None, source=False, build=False, compile_librar
         popen(['python', '-u', os.path.join(tools_dir, 'build.py')]
               + list(chain.from_iterable(izip(repeat('-D'), macros)))
               + ['-t', tchain, '-m', target]
-              + (['-c'] if clean else [])
+              + list(chain.from_iterable(izip(repeat('-o'), options or [])))
               + list(chain.from_iterable(izip(repeat('--source'), source)))
               + ['--build', build]
+              + (['-c'] if clean else [])
               + (['--artifact-name', artifact_name] if artifact_name else [])
               + (['-v'] if verbose else [])
               + args,
@@ -2029,9 +2032,10 @@ def compile_(toolchain=None, mcu=None, source=False, build=False, compile_librar
         popen(['python', '-u', os.path.join(tools_dir, 'make.py')]
               + list(chain.from_iterable(izip(repeat('-D'), macros)))
               + ['-t', tchain, '-m', target]
-              + (['-c'] if clean else [])
+              + list(chain.from_iterable(izip(repeat('-o'), options or [])))
               + list(chain.from_iterable(izip(repeat('--source'), source)))
               + ['--build', build]
+              + (['-c'] if clean else [])
               + (['--artifact-name', artifact_name] if artifact_name else [])
               + (['-v'] if verbose else [])
               + args,
@@ -2043,7 +2047,7 @@ def compile_(toolchain=None, mcu=None, source=False, build=False, compile_librar
 # Test command
 @subcommand('test',
     dict(name=['-t', '--toolchain'], help='Compile toolchain. Example: ARM, GCC_ARM, IAR'),
-    dict(name=['-m', '--mcu'], help='Compile target. Example: K64F, NUCLEO_F401RE, NRF51822...'),
+    dict(name=['-m', '--target'], help='Compile target MCU. Example: K64F, NUCLEO_F401RE, NRF51822...'),
     dict(name='--compile-list', dest='compile_list', action='store_true', help='List all tests that can be built'),
     dict(name='--run-list', dest='run_list', action='store_true', help='List all built tests that can be ran'),
     dict(name='--compile', dest='compile_only', action='store_true', help='Only compile tests'),
@@ -2056,15 +2060,15 @@ def compile_(toolchain=None, mcu=None, source=False, build=False, compile_librar
     dict(name='--test-spec', dest="test_spec", help="Path used for the test spec file used when building and running tests (the default path is the build directory)"),
     help='Find, build and run tests',
     description=("Find, build, and run tests in a program and libraries"))
-def test_(toolchain=None, mcu=None, compile_list=False, run_list=False, compile_only=False, run_only=False, tests_by_name=None, source=False, options=False, build=False, clean=False, test_spec=None):
+def test_(toolchain=None, target=None, compile_list=False, run_list=False, compile_only=False, run_only=False, tests_by_name=None, source=False, options=False, build=False, clean=False, test_spec=None):
     # Gather remaining arguments
     args = remainder
     # Find the root of the program
     program = Program(os.getcwd(), True)
     # Save original working directory
     orig_path = os.getcwd()
 
-    target = program.get_mcu(mcu)
+    target = program.get_target(target)
     tchain = program.get_toolchain(toolchain)
     macros = program.get_macros()
     tools_dir = program.get_tools()
@@ -2134,14 +2138,14 @@ def test_(toolchain=None, mcu=None, compile_list=False, run_list=False, compile_
 # Export command
 @subcommand('export',
     dict(name=['-i', '--ide'], help='IDE to create project files for. Example: UVISION4, UVISION5, GCC_ARM, IAR, COIDE', required=True),
-    dict(name=['-m', '--mcu'], help='Export for target MCU. Example: K64F, NUCLEO_F401RE, NRF51822...'),
+    dict(name=['-m', '--target'], help='Export for target MCU. Example: K64F, NUCLEO_F401RE, NRF51822...'),
     dict(name='--source', action='append', help='Source directory. Default: . (current dir)'),
     dict(name=['-c', '--clean'], action='store_true', help='Clean the build directory before compiling'),
     dict(name=['-S', '--supported'], dest='supported', action='store_true', help='Shows supported matrix of targets and toolchains'),
     help='Generate an IDE project',
     description=(
         "Generate IDE project files for the current program."))
-def export(ide=None, mcu=None, source=False, clean=False, supported=False):
+def export(ide=None, target=None, source=False, clean=False, supported=False):
     # Gather remaining arguments
     args = remainder
     # Find the root of the program
@@ -2161,7 +2165,7 @@ def export(ide=None, mcu=None, source=False, clean=False, supported=False):
               env=env)
         return
 
-    target = program.get_mcu(mcu)
+    target = program.get_target(target)
     macros = program.get_macros()
 
     if not source or len(source) == 0: