SLAU132 User guide

SLAU132Y September 2004 – June 2021

2.3 Changing the Compiler's Behavior with Options

Options control the operation of the compiler. This section provides a description of option conventions and an option summary table. It also provides detailed descriptions of the most frequently used options, including options used for type-checking and assembling.

For a help screen summary of the options, enter cl430 with no parameters on the command line.

The following apply to the compiler options:

There are typically two ways of specifying a given option. The "long form" uses a two hyphen prefix and is usually a more descriptive name. The "short form" uses a single hyphen prefix and a combination of letters and numbers that are not always intuitive.
Options are usually case sensitive.
Individual options cannot be combined.
An option with a parameter should be specified with an equal sign before the parameter to clearly associate the parameter with the option. For example, the option to undefine a constant can be expressed as --undefine=name. Likewise, the option to specify the maximum amount of optimization can be expressed as -O=3. You can also specify a parameter directly after certain options, for example -O3 is the same as -O=3. No space is allowed between the option and the optional parameter, so -O 3 is not accepted.
Files and options except the --run_linker option can occur in any order. The --run_linker option must follow all compiler options and precede any linker options.

You can define default options for the compiler by using the MSP430_C_OPTION environment variable. For a detailed description of the environment variable, see Section 3.5.1.

Table 3-8 through Table 3-29 summarize all options (including link options). Use the references in the tables for more complete descriptions of the options.

Table 2-1 Processor Options

Option	Alias	Effect	Section
--silicon_version={msp\|mspx}	-v	Selects the instruction set.	Section 3.4.4
--code_model={small\|large}		Specifies the code memory model.	Section 7.2.1
--data_model={small\|large\| restricted}		Specifies the data memory model.	Section 7.2.2
--near_data={globals\|none}		Specifies what data must be near. Default is globals.	Section 7.2.3

Table 2-2 Optimization Options⁽¹⁾

Option	Alias	Effect	Section
--opt_level=off		Disables all optimization.	Section 4.2
--opt_level=n	-On	Level 0 (-O0) optimizes register usage only (default if option not used) . Level 1 (-O1) uses Level 0 optimizations and optimizes locally. Level 2 (-O2) uses Level 1 optimizations and optimizes globally . Level 3 (-O3) uses Level 2 optimizations and optimizes the file. Level 4 (-O4) uses Level 3 optimizations and performs link-time optimization.	Section 4.2, Section 4.4, Section 4.7
--opt_for_speed[=n]	-mf	Controls the tradeoff between size and speed (0-5 range). If this option is specified without n, the default value is 4. If this option is not specified, the default setting is 1.	Section 4.3

(1) Note: Machine-specific options (see Table 3-14) can also affect optimization.

Table 2-3 Advanced Optimization Options⁽¹⁾

Option	Alias	Effect	Section
--align_for_power		Aligns all functions and loops to 4-byte boundaries. Power savings can be achieved if a small function or loop aligns to the 32-bit buffer for fetching code from flash memory. Power savings is less significant for larger functions and loops.	--
--auto_inline=[size]	-oi	Sets automatic inlining size (--opt_level=3 only). If size is not specified, the default is 1.	Section 4.6
--call_assumptions=n	-opn	Level 0 (-op0) specifies that the module contains functions and variables that are called or modified from outside the source code provided to the compiler. Level 1 (-op1) specifies that the module contains variables modified from outside the source code provided to the compiler but does not use functions called from outside the source code. Level 2 (-op2) specifies that the module contains no functions or variables that are called or modified from outside the source code provided to the compiler (default). Level 3 (-op3) specifies that the module contains functions that are called from outside the source code provided to the compiler but does not use variables modified from outside the source code.	Section 4.5.1
--disable_inlining		Prevents any inlining from occurring.	Section 3.12
--fp_mode={relaxed\|strict}		Enables or disables relaxed floating-point mode.	Section 3.4.3
--fp_reassoc={on\|off}		Enables or disables the reassociation of floating-point arithmetic.	Section 3.4.3
--gen_opt_info=n	-onn	Level 0 (-on0) disables the optimization information file. Level 1 (-on2) produces an optimization information file. Level 2 (-on2) produces a verbose optimization information file.	Section 4.4.1
--optimizer_interlist	-os	Interlists optimizer comments with assembly statements.	Section 4.12
--program_level_compile	-pm	Combines source files to perform program-level optimization.	Section 4.5
--aliased_variables	-ma	Assumes variables are aliased	Section 4.10

(1) Note: Machine-specific options (see Table 3-14) can also affect optimization.

Table 2-4 Debug Options

Option	Alias	Effect	Section
--symdebug:dwarf	-g	Default behavior. Enables symbolic debugging. The generation of debug information does not impact optimization. Therefore, generating debug information is enabled by default.	Section 3.4.5 Section 4.13
--symdebug:dwarf_version=2\|3\|4		Specifies the DWARF format version.	Section 3.4.5
--symdebug:none		Disables all symbolic debugging.	Section 3.4.5 Section 4.13
--symdebug:skeletal		(Deprecated; has no effect.)

Table 2-5 Include Options

Option	Alias	Effect	Section
--include_path=directory	`-I`	Adds the specified directory to the #include search path.	Section 3.6.2.1
--preinclude=filename		Includes filename at the beginning of compilation.	Section 3.4.3

Table 2-6 ULP Advisor Options

Option	Alias	Effect	Section
--advice:power[={all\|none\|rulespec}]		Enables checking the specified ULP Advisor rules. (Default is all.)	Section 3.4.3
--advice:power_severity={error\| warning\|remark\|suppress}		Sets the diagnostic severity for ULP Advisor rules.	Section 3.4.3

Table 2-7 Hardware Configuration Advisor Options

Option	Alias	Effect	Section
--advice:hw_config[={all\|none\| rulespec}		Enables checking the device configuration settings. (Default is none if this option is not included on the command line. Default is all if this option is used, but with no value specified.)	Section 3.4.3

Table 2-8 Control Options

Option	Alias	Effect	Section
--compile_only	-c	Disables linking (negates --run_linker).	Section 5.2.3
--help	-h	Prints (on the standard output device) a description of the options understood by the compiler.	Section 3.4.2
--run_linker	-z	Causes the linker to be invoked from the compiler command line.	Section 3.4.2
--skip_assembler	-n	Compiles C/C++ source file , producing an assembly language output file. The assembler is not run and no object file is produced.	Section 3.4.2

Table 2-9 Language Options

Option	Alias	Effect	Section
--c89		Processes C files according to the ISO C89 standard.	Section 6.16
--c99		Processes C files according to the ISO C99 standard.	Section 6.16
--c11		Processes C files according to the ISO C11 standard.	Section 6.16
--c++14		Processes C++ files according to the ISO C++14 standard. The --c++03 option has been deprecated.	Section 6.16
--cpp_default	-fg	Processes all source files with a C extension as C++ source files.	Section 3.4.7
--enum_type={packed\|unpacked}		Choose whether to use compact integer types to store small enumerated types.	Section 3.4.4
--exceptions		Enables C++ exception handling.	Section 6.9
--extern_c_can_throw		Allow extern C functions to propagate exceptions.	--
--float_operations_allowed ={none\|all\|32\|64}		Restricts the types of floating point operations allowed.	Section 3.4.3
--gen_cross_reference	-px	Generates a cross-reference listing file (.crl).	Section 3.10
--pending_instantiations=#		Specify the number of template instantiations that may be in progress at any given time. Use 0 to specify an unlimited number.	Section 3.4.4
--plain_char={signed\|unsigned}	-mc	Changes variables of type char from unsigned to signed. Default is unsigned.	Section 3.4.4
--printf_support={nofloat\|full\| minimal}		Enables support for smaller, limited versions of the printf function family (sprintf, fprintf, etc.) and the scanf function family (sscanf, fscanf, etc.) run-time-support functions.	Section 3.4.3
--relaxed_ansi	-pr	Enables relaxed mode; ignores strict ISO violations. This is on by default. To disable this mode, use the --strict_ansi option.	Section 6.16.3
--rtti	-rtti	Enables C++ run-time type information (RTTI).	–-
--strict_ansi	-ps	Enables strict ANSI/ISO mode (for C/C++, not for K&R C). In this mode, language extensions that conflict with ANSI/ISO C/C++ are disabled. In strict ANSI/ISO mode, most ANSI/ISO violations are reported as errors. Violations that are considered discretionary may be reported as warnings instead.	Section 6.16.3

Table 2-10 Parser Preprocessing Options

Option	Alias	Effect	Section
--preproc_dependency[=filename]	-ppd	Performs preprocessing only, but instead of writing preprocessed output, writes a list of dependency lines suitable for input to a standard make utility.	Section 3.6.8
--preproc_includes[=filename]	-ppi	Performs preprocessing only, but instead of writing preprocessed output, writes a list of files included with the #include directive.	Section 3.6.9
--preproc_macros[=filename]	-ppm	Performs preprocessing only. Writes list of predefined and user-defined macros to a file with the same name as the input but with a .pp extension.	Section 3.6.10
--preproc_only	-ppo	Performs preprocessing only. Writes preprocessed output to a file with the same name as the input but with a .pp extension.	Section 3.6.4
--preproc_with_comment	-ppc	Performs preprocessing only. Writes preprocessed output, keeping the comments, to a file with the same name as the input but with a .pp extension.	Section 3.6.6
--preproc_with_compile	-ppa	Continues compilation after preprocessing with any of the -pp<x> options that normally disable compilation.	Section 3.6.5
--preproc_with_line	-ppl	Performs preprocessing only. Writes preprocessed output with line-control information (#line directives) to a file with the same name as the input but with a .pp extension.	Section 3.6.7

Table 2-11 Predefined Macro Options

Option	Alias	Effect	Section
--define=name[=def]	-D	Predefines name.	Section 3.4.2
--undefine=name	-U	Undefines name.	Section 3.4.2

Table 2-12 Diagnostic Message Options

Option	Alias	Effect	Section
--compiler_revision		Prints out the compiler release revision and exits.	--
--diag_error=num	-pdse	Categorizes the diagnostic identified by num as an error.	Section 3.8.1
--diag_remark=num	-pdsr	Categorizes the diagnostic identified by num as a remark.	Section 3.8.1
--diag_suppress=num	-pds	Suppresses the diagnostic identified by num.	Section 3.8.1
--diag_warning=num	-pdsw	Categorizes the diagnostic identified by num as a warning.	Section 3.8.1
--diag_wrap={on\|off}		Wrap diagnostic messages (default is on). Note that this command-line option cannot be used within the Code Composer Studio IDE.
--display_error_number	-pden	Displays a diagnostic's identifiers along with its text. Note that this command-line option cannot be used within the Code Composer Studio IDE.	Section 3.8.1
--emit_warnings_as_errors	-pdew	Treat warnings as errors.	Section 3.8.1
--gen_func_info_listing		Generate user information file (.aux).	Section 3.4.2
--issue_remarks	-pdr	Issues remarks (non-serious warnings).	Section 3.8.1
--no_warnings	-pdw	Suppresses diagnostic warnings (errors are still issued).	Section 3.8.1
--quiet	-q	Suppresses progress messages (quiet).	--
--set_error_limit=num	-pdel	Sets the error limit to num. The compiler abandons compiling after this number of errors. (The default is 100.)	Section 3.8.1
--super_quiet	-qq	Super quiet mode.	--
--tool_version	-version	Displays version number for each tool.	--
--verbose		Display banner and function progress information.	--
--verbose_diagnostics	-pdv	Provides verbose diagnostic messages that display the original source with line-wrap. Note that this command-line option cannot be used within the Code Composer Studio IDE.	Section 3.8.1
--write_diagnostics_file	-pdf	Generates a diagnostic message information file. Compiler only option. Note that this command-line option cannot be used within the Code Composer Studio IDE.	Section 3.8.1

Table 2-13 Supplemental Information Options

Option	Alias	Effect	Section
--gen_preprocessor_listing	-pl	Generates a raw listing file (.rl).	Section 3.11
--section_sizes={on\|off}		Generates section size information, including sizes for sections containing executable code and constants, constant or initialized data (global and static variables), and uninitialized data. (Default is off if this option is not included on the command line. Default is on if this option is used with no value specified.)	Section 3.8.1

Table 2-14 Run-Time Model Options

Option	Alias	Effect	Section
--common={on\|off}		On by default. When on, uninitialized file scope variables are emitted as common symbols. When off, common symbols are not created.	Section 3.4.4
--disable_interrupts_around_hw_mpy=off		Setting this option to off leaves interrupts enabled during inlined hardware multiply operations. This option can only be used if all ISRs do not use multiplication or call other functions.	Section 3.4.4
--gen_data_subsections={on\|off}		Place all aggregate data (arrays, structs, and unions) into subsections. This gives the linker more control over removing unused data during the final link step. See the link to the right for details about the default setting.	Section 5.3.2
--global_register={r4\|r5}		Reserves register for use by user.
--large_memory_model	-ml	Uses a large memory model when compiling for the MSP430X. (Deprecated)	Section 3.4.4
--ramfunc={on\|off}		If set to on, specifies that all functions should be placed in the .TI.ramfunc section, which is placed in RAM.	Section 3.4.4
--silicon_errata={errata}		Generates code to work around the specified silicon errata. The errata value may be CPU12, CPU13, CPU15, CPU18, CPU19, CPU21, CPU22, CPU23, or CPU40. See the corresponding device errata sheet for details.
--use_hw_mpy[={16\|32\|F5\|none}]		If --opt_for_speed is set to 1 or higher, replaces all references to the default integer/long multiply routine with the version of the multiply routine that uses the hardware multiplier support. Additionally, if --opt_for_speed is set to 4 or 5, hardware multiplication is inlined during code generation.	Section 3.4.4

Table 2-15 Entry/Exit Hook Options

Option	Effect	Section
--entry_hook[=name]	Enables entry hooks.	Section 3.15
--entry_parm={none\|name\| address}	Specifies the parameters to the function to the --entry_hook option.	Section 3.15
--exit_hook[=name]	Enables exit hooks.	Section 3.15
--exit_parm={none\|name\|address}	Specifies the parameters to the function to the --exit_hook option.	Section 3.15
--remove_hooks_when_inlining	Removes entry/exit hooks for auto-inlined functions.	Section 3.15

Table 2-16 Feedback Options

Option	Effect	Section
--analyze=codecov	Generate analysis info from profile data.	Section 4.9.2.2
--analyze_only	Only generate analysis.	Section 4.9.2.2
--gen_profile_info	Generates instrumentation code to collect profile information.	Section 4.8.1.3
--use_profile_info=file1[, file2,...]	Specifies the profile information file(s).	Section 4.8.1.3

Table 2-17 Assembler Options

Option	Alias	Effect	Section
--keep_asm	-k	Keeps the assembly language (.asm) file.	Section 3.4.11
--asm_listing	-al	Generates an assembly listing file.	Section 3.4.11
--c_src_interlist	-ss	Interlists C source and assembly statements.	Section 3.13 Section 4.12
--src_interlist	-s	Interlists optimizer comments (if available) and assembly source statements; otherwise interlists C and assembly source statements.	Section 3.4.2
--absolute_listing	-aa	Enables absolute listing.	Section 3.4.11
--asm_define=name[=def]	-ad	Sets the name symbol.	Section 3.4.11
--asm_dependency	-apd	Performs preprocessing; lists only assembly dependencies.	Section 3.4.11
--asm_includes	-api	Performs preprocessing; lists only included #include files.	Section 3.4.11
--asm_undefine=name	-au	Undefines the predefined constant name.	Section 3.4.11
--asm_listing_cross_reference	-ax	Generates the cross-reference file.	Section 3.4.11
--include_file=filename	-ahi	Includes the specified file for the assembly module.	Section 3.4.11

Table 2-18 File Type Specifier Options

Option	Alias	Effect	Section
--asm_file=filename	-fa	Identifies filename as an assembly source file regardless of its extension. By default, the compiler and assembler treat .asm files as assembly source files.	Section 3.4.7
--c_file=filename	-fc	Identifies filename as a C source file regardless of its extension. By default, the compiler treats .c files as C source files.	Section 3.4.7
--cpp_file=filename	-fp	Identifies filename as a C++ file, regardless of its extension. By default, the compiler treats .C, .cpp, .cc and .cxx files as a C++ files.	Section 3.4.7
--obj_file=filename	-fo	Identifies filename as an object code file regardless of its extension. By default, the compiler and linker treat .obj files as object code files, including both .c.obj and .cpp.obj files.	Section 3.4.7

Table 2-19 Directory Specifier Options

Option	Alias	Effect	Section
--abs_directory=directory	-fb	Specifies an absolute listing file directory. By default, the compiler uses the object file directory.	Section 3.4.10
--asm_directory=directory	-fs	Specifies an assembly file directory. By default, the compiler uses the current directory.	Section 3.4.10
--list_directory=directory	-ff	Specifies an assembly listing file and cross-reference listing file directory By default, the compiler uses the object file directory.	Section 3.4.10
--obj_directory=directory	-fr	Specifies an object file directory. By default, the compiler uses the current directory.	Section 3.4.10
--output_file=filename	-fe	Specifies a compilation output file name; can override --obj_directory.	Section 3.4.10
--pp_directory=dir		Specifies a preprocessor file directory. By default, the compiler uses the current directory.	Section 3.4.10
--temp_directory=directory	-ft	Specifies a temporary file directory. By default, the compiler uses the current directory.	Section 3.4.10

Table 2-20 Default File Extensions Options

Option	Alias	Effect	Section
--asm_extension=[.]extension	-ea	Sets a default extension for assembly source files.	Section 3.4.9
--c_extension=[.]extension	-ec	Sets a default extension for C source files.	Section 3.4.9
--cpp_extension=[.]extension	-ep	Sets a default extension for C++ source files.	Section 3.4.9
--listing_extension=[.]extension	-es	Sets a default extension for listing files.	Section 3.4.9
--obj_extension=[.]extension	-eo	Sets a default extension for object files.	Section 3.4.9

Table 2-21 Command Files Options

Option	Alias	Effect	Section
--cmd_file=filename	-@	Interprets contents of a file as an extension to the command line. Multiple -@ instances can be used.	Section 3.4.2