.. _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 ``simple_peripheral`` project from the BLE5-Stack,
but the steps can be adopted for 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
#. Stop SysConfig from running by either:

    a. Excluding generated files from building.
    b. Changing the ``.cproject`` file and disabling the pre-build step

.. tip:: Check if configuring SysConfig to :ref:`sysconfig-reserve-peripherals`
         could help.

.. _sec-locate-generated-files:

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

After building the ``simple_peripheral`` 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 ``simple_peripheral`` 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.png
  :align: center
  :width: 60%

  SysConfig generated files. Command files are marked with yellow.

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

.. 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 ``simple_peripheral`` this means:

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

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

2. Change location of ``.opt`` files
(Project > Properties > ARM Compiler > Advanced Options > Command Files)

 - Change the location of the ``ti_build_config.opt`` and ``ti_ble_app_config.opt``
   to be in ``${PROJECT_ROOT}/syscfg``

3. Modify linker include paths (Project > Properties > ARM Linker > File Search Path)

 - Change the location of ``ti_utils_build_linker.cmd.genlibs``
   from ``${PROJECT_BUILD_DIR}/syscfg/`` to be in ``${PROJECT_ROOT}/syscfg/``

First method: Excluding Generated Files from Building
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This method is recommended if users only want to modify some of the .c/h files 
which are generated, but not stop Sysconfig from running during a project 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.

Second method: Stop SysConfig from Running Entirely
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following steps are required to completely remove SysConfig's
involvement during a project build.

1. Open the ``.cproject`` file.

  .. figure:: resources/cproject_file.png 
    :align: center
    :width: 60%

    Find the .cproject file.

2. In this file, find and comment out or remove the XML element 
   ``<tool name="SysConfig"/>,`` as shown below:

  .. code-block:: xml

    . . . 
    </tool>
    <tool id="com.ti.ccstudio.buildDefinitions.TMS470_20.2.hex.1150171138" name="ARM Hex Utility" superClass="com.ti.ccstudio.buildDefinitions.TMS470_20.2.hex"/>
    <!--tool id="com.ti.ccstudio.buildDefinitions.sysConfig.752181800" name="SysConfig" superClass="com.ti.ccstudio.buildDefinitions.sysConfig">
      <option IS_BUILTIN_EMPTY="false" IS_VALUE_EMPTY="false" id="com.ti.ccstudio.buildDefinitions.sysConfig.PRODUCTS.967104601" name="Root system config meta data file in a product or SDK (-s, -/-product)" superClass="com.ti.ccstudio.buildDefinitions.sysConfig.PRODUCTS" useByScannerDiscovery="false" valueType="stringList">
        <listOptionValue builtIn="false" value="${COM_TI_SIMPLELINK_CC13XX_26XX_SDK_SYSCONFIG_MANIFEST}"/>
      </option>
    </tool-->
    <tool id="com.ti.rtsc.buildDefinitions.XDC_3.16.tool.499843531" name="XDCtools" superClass="com.ti.rtsc.buildDefinitions.XDC_3.16.tool">
    . . .

  **Note 1**: Make sure that you also break-up any double dashes inside that 
  commented out XML section (e.g. see the string ``-/-product`` above, which 
  used to be ``--product``).

  **Note 2**: Make sure that you comment out the ``<tool>`` element which is 
  inside the (build) ``<configuration>`` element for which you wish to disable the 
  SysConfig tool. I.e. build config Debug or Release.

3. Open the Project Explorer view's menu (the triple dot icon in the top-right 
   corner of the Project Explorer view), and open the Filters and 
   Customization... dialog.

4. In the dialog, de-select the ``.* resources`` entry (second entry from the 
   top), and click OK.

After applying these steps, SysConfig will no longer run (and it will not show 
up in the Project overview).  To remove SysConfig entirely, the build step must be 
removed as well.  Disabling SysConfig is slightly different for IAR vs CCS. Expand 
the relevant section below to see how to disable SysConfig.

.. container:: toggle

    .. container:: header

        **Click to IAR Instructions**

    In IAR, SysConfig is treated as a Custom Build step. To access the custom
    build steps select Project > Options > Custom Build. Remove all the fields
    that are populated under the Custom Tool Configuration tab as shown below:

    .. _fig-disable-iar:
    .. figure:: resources/sysconfig-disable-iar.png
        :align: center

        Disable SysConfig IAR

.. container:: toggle

    .. container:: header

        **Click to CCS Instructions**

    In CCS, files ending in ``.syscfg`` are automatically flagged as
    SysConfig files. If you have a file active in your workspace, it will
    invoke the SysConfig tool. This can be disabled by excluding
    the ``.syscfg`` files from build.