.. _sysconfig-disable:

Disable SysConfig
=================

This section will describe the steps necessary to disable SysConfig, either
entirely or just a few selected files.
Disabling SysConfig may be necessary when freezing source code for production
or when you are satisfied with the output.

This example will use the ``basic_ble`` project from the BLE5-Stack,
but the steps can be adopted for other project.

A summarization of the steps can be found below:

1. Build the project at least once so that SysConfig can generate output
#. Locate the generated files
#. Copy generated files from build directory
#. Modify compiler/linker files to point to moved files
#. Exclude generated files from build:

    a. Optional: Exclude .syscfg from build

.. _sec-locate-generated-files:

Locating Generated Files
^^^^^^^^^^^^^^^^^^^^^^^^

After building the ``basic_ble`` project using default settings, the first 
step to disabling SysConfig is to determine which files it has generated.

Click the ``<>`` button in SysConfig to see which files it is currently
generating. See :ref:`fig-generated-files-sp` for an example of which files
are generated by SysConfig for the ``basic_ble`` project.

In **CCS** these files are placed in ``<build_config>/syscfg``

 - ``<build_config>`` is the build configuration of the project. (e.g. ``Debug``)

In **IAR** these files are placed in the project folder (e.g. ``~/<proj_import>/``)

 - ``<proj_import>`` is the location selected when importing the project in IAR
 - In the IDE the SysConfig files reside in a virtual folder called SysConfig
   Generated Files. You can find their location by right clicking any of the
   files in this folder and selecting **Open Containing folder...**

.. _fig-generated-files-sp:
.. figure:: resources/generated_files_sp_cc23xx.png
  :align: center
  :width: 60%

  SysConfig generated files

Copy Generated Files
^^^^^^^^^^^^^^^^^^^^

**IAR Users may skip this step**

In CCS the build directory is cleaned every time the project is rebuilt,
so it is necessary to copy the generated files to a permanent location
before the project is rebuilt. Follow the steps below to do so. We will
place the files in the application in a folder called ``syscfg`` but it
can be called anything.

 1. Right click on the project -> New -> Folder
 2. Copy the files from ``<build_config>/syscfg`` to the new folder.

  - See :ref:`fig-generated-files` to see which files to copy. Note that the .syscfg file should not be moved.

.. attention::

  When debugging using ROV, be sure to place ``syscfg_c.rov.xs`` in the root
  directory of the project. This way, the ROV tool can pull in the appropriate
  debug tools as selected by SysConfig initially.

Modifying Compiler/Linker Settings
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**IAR Users may skip this step as the SysConfig output is already in
a non destructive location.** 
However, if you moved the SysConfig generated
content to a new location elsewhere in the file system, you may need to change
the project settings.

The ``.c``, ``.h``, and ``.opt`` files generated by SysConfig are consumed
by the compiler and linker as part of the build process. Moving the files
to a new location means that we need to modify the project settings to
find them. For the case of ``basic_ble`` this means:

1. Change include paths (Project > Properties > ARM Compiler > Include Options)

 - Add ``${PROJECT_ROOT}/syscfg``

2. Add ``.opt`` file path. **You may skip this step if you do not want to exclude the .opt file from SysConfig.**
(Project > Properties > ARM Compiler > Advanced Options > Command Files)

 - Add the path of the ``ti_utils_build_compiler.opt`` file: ``${PROJECT_ROOT}/syscfg/ti_utils_build_compiler.opt``

3. Add linker include path (Project > Properties > ARM Linker > File Search Path) 
**You may skip this step if you do not want to exclude the .genlibs file from SysConfig.**

 - Add the directory ``${PROJECT_ROOT}/syscfg/`` so that the linker can find the file ``ti_utils_build_linker.cmd.genlibs``

Exclude Generated Files from Build
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to do this, click the ``<>`` button in SysConfig and deselect the
``Include in Build`` button of files you no longer want generated by SysConfig.  
Make sure that these files are the only ones which have been copied into your
custom ``syscfg`` application folder.

.. _fig-exclude-generated-files-sp:
.. figure:: resources/exclude_generated_files_sp.png
  :align: center
  :width: 60%

  SysConfig generated files, excluded ones of which have been deselected.

Optional: Exclude .syscfg from build
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following step is required to completely remove SysConfig's
involvement during a project build.

Right click on the ``.syscfg`` file. Select the option "Exclude from build".

.. note:: Your project will not compile unless either you copied all the SysConfig generated files or 
write your own code with the necessary defines and initializations.

