.. _sec-compiler_and_linker_options:

===========================
Compiler and Linker Options
===========================

.. _sec-compiler-options:

Compiler Options
================

.. tip::
  More advanced documentation can be found in the compiler's documentation:

  * `TI Arm Clang Compiler Tools User Guide <https://software-dl.ti.com/codegen/docs/tiarmclang/compiler_tools_user_guide/index.html>`_
  * `IAR Development Guide <https://wwwfiles.iar.com/arm/webic/doc/EWARM_DevelopmentGuide.ENU.pdf>`_

For |STACK| projects, compiler options are generated by SysConfig and stored in 
the project's ``Debug\syscfg`` folder if using Debug version or it can be found in
the project’s ``Release\syscfg`` folder if using Release version. The compiler.opt 
file contains a set of options (typically include options and preprocessor defines) 
to be passed to the compiler when compiling user source files. In the |STACK|, 
SysConfig is used to generate compile time options to configure |STACK|. For 
info on configurable SysConfig see :ref:`sysconfig-ble5`.

The ``.opt`` files are generated through SysConfig when the project is built.
All Bluetooth LE example projects included in the |SDK| come with SysConfig
enabled by default.

.. note::
    host_test's SysConfig file is configured such that it cannot
    be used to make Bluetooth LE configuration modifications. This is because
    host_test's Bluetooth LE configuration has been carefully configured to
    facilitate the intended use-case of host_test.

The predefined symbols in the ``.opt`` files are prefixed with a ``-D``, which
is standard commandline prefix notation across all the supported toolchains.
Of the predefined symbols in the ``.opt`` files, some of them are configurable
and some are not. ``.opt`` files generated by SysConfig cannot be directly
modified but instead must be modified through SysConfig. See :ref:`appconfigurablefeatures` and
:ref:`stackconfigurablefeatures` for reference as to which options are
configurable.

The convention to disable a symbol in the ``.opt`` files is to put an 'x' in
front of the name. For example, to disable power management,
change ``-DPOWER_SAVING`` to ``-DxPOWER_SAVING``. It is also possible to
disable a symbol by commenting it out via 'C - style' syntax
(e.g. ``/* -DPOWER_SAVING */``). 

.. warning::
  Changes in an ``.opt`` file may not be detected by the compiler/toolchain.
  It is best to rebuild the entire project when a define is changed.

Linker Options
==============

Linker symbols may need to be set or adjusted at the project level in order to
control the memory layout of the generated image.
The following procedure describes how to access and modify linker
symbols.

CCS
^^^

.. only:: sdk_targets_cc23xx

    #.  Open **Project Properties**
    #.  Navigate in CCS to **Build** -> **ARM Linker** -> **Advanced Options** -> **Command File Preprocessing**
    #.  Use the buttons highlighted in :numref:`fig-ccs-linker-defines-box-cc23xx` to add,
        delete, or edit a linker symbol.

    .. _fig-ccs-linker-defines-box-cc23xx:
    .. figure:: resources/ccs_linker_opts_cc23xx.png
        :align: center

        CCS Linker Symbols

.. only:: not sdk_targets_cc23xx

    #.  Open **Project Properties**
    #.  Navigate to **CCS Build** -> **ARM Linker** -> **Advanced Options** -> **Command File Preprocessing**
    #.  Use the buttons highlighted in :numref:`fig-ccs-linker-defines-box` to add,
        delete, or edit a linker symbol.

    .. _fig-ccs-linker-defines-box:
    .. figure:: resources/ccs_linker_opts.png
        :align: center

        CCS Linker Symbols

IAR
^^^

.. only:: sdk_targets_cc23xx

    #. Open the Project's **Options** and select the **Linker** Category.
    #. Open the **Config** tab.
    #. View the **Configuration File symbol definitions** box (see :numref:`fig-iar-linker-defines-box-cc23xx`).
    #. Add or edit the preprocessor symbols.

    .. _fig-iar-linker-defines-box-cc23xx:
    .. figure:: resources/iar_linker_opts_cc23xx.png
        :align: center

        IAR Defined Symbols Box

.. only:: not sdk_targets_cc23xx

    #. Open the Project's **Options** and select the **Linker** Category.
    #. Open the **Config** tab.
    #. View the **Configuration File symbol definitions** box (see :numref:`fig-iar-linker-defines-box`).
    #. Add or edit the preprocessor symbols.

    .. _fig-iar-linker-defines-box:
    .. figure:: resources/iar_linker_opts.png
        :align: center

        IAR Defined Symbols Box

Linker Command File
===================

Linker command files (or linker command scripts)
allow to put linker options and directives in a file. 
These are used to control how the sections in the input files should be mapped
into the output file, and to control the memory layout of the output file.

Per convention, the linker command files are named depending on the toolchain
used:

* ``xxx.cmd`` for TI Clang (for more details, see 
  `here <https://software-dl.ti.com/codegen/docs/tiarmclang/rel1_0_0_sts/tiarmclang_ug/tiarmclang-portfolio/compiler_manual/linker_description/05_linker_command_files/linker-command-files-stdz0751521.html>`_)
* ``xxx.icf`` for IAR
