.. _config_ide:

Configuring an IDE
==================

Some users may choose to use an Integrated Development Environment to augment
their use of the tools. The tools can be integrated to varying degrees with a
number of common user-supplied IDEs.

The instructions given below are simply suggestions; there are many ways of
integrating the tools with even a single IDE, and the user is encouraged to
experiment to suit their workflow.

Configuration common to all IDEs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. _config_ide_create_content:

Creation of project content
---------------------------

In order to reduce the amount of repetition later in this document, we define a
set of example projects which will be used as a basis for each specific IDE.

Create two example projects:

.. code-block:: bash

  $ mkdir -p projects/single-tile
  $ mkdir -p projects/switch-setup

Within :file:`projects/single-tile`:

* Create :file:`main.c` as per :doc:`../../quick-start/single-tile`
* Create the following three bash scripts:

  .. literalinclude:: ../../quick-start/examples/single-tile/build.sh
    :caption: build.sh
    :language: bash

  .. literalinclude:: ../../quick-start/examples/single-tile/run.sh
    :caption: run.sh
    :language: bash

  .. literalinclude:: ../../quick-start/examples/single-tile/debug.sh
    :caption: debug.sh
    :language: bash

Within :file:`projects/switch-setup`:

* Create :file:`mapfile.xc` and :file:`main.c` as per
  :doc:`../../quick-start/switch-setup`

* Create three bash scripts as above, but with a slight modification to
  :file:`build.sh`:

  .. literalinclude:: ../../quick-start/examples/switch-setup/build.sh
    :caption: build.sh
    :language: bash

You might later choose to customise these bash scripts; they will act as
placeholders for now.

Choice of build System
----------------------

Users of the tools may use any build system. The examples below demonstrate use
of deliberately basic "build system" such that the examples are not dependent on
installation of a build system.

Users are encouraged to use their favourite build system.

Integration of "Run" and "Debug" functionality
----------------------------------------------

The current architecture of the XRUN and XGDB tools is such that integration
with 3rd-party IDEs is limited to terminal operation only. The guidance below
therefore "integrates" the run and debug functionality into the terminal window
of the respective IDE.

Future releases of the tools will re-architect XRUN and XGDB such that they can
be fully integrated into 3rd-party IDEs.

Visual Studio Code
^^^^^^^^^^^^^^^^^^

.. figure:: images/vs_code_example.png

  Example of tools plugged into VS Code

Pre-requisites
--------------

#. Install `Visual Studio Code <https://code.visualstudio.com/>`_.

#. Install the `C/C++ extension for VS Code <https://marketplace.visualstudio.com/items?itemName=ms-vscode.cpptools>`_.

#. Ensure the :ref:`command line environment is working <get_started>`.

#. Create the :ref:`example project content <config_ide_create_content>`

Start VS Code and check the environment
---------------------------------------

From a bash terminal where the
:ref:`command line environment is working <get_started>`, start VS Code such
that it can see both projects within its workspace:

.. code-block:: bash

  $ cd projects
  $ code .

Check that the tools are available within VS Code. Select
:menuselection:`View-->Terminal` and check that the following command gives the
expected results:

.. code-block:: bash

  $ xcc --version

Configure VS Code
-----------------

If not already present, create a folder :file:`.vscode` within the
:file:`projects` folder and, within it, create two files:

.. literalinclude:: /.vscode/tasks.json
  :caption: tasks.json
  :language: json

.. literalinclude:: /.vscode/c_cpp_properties.json
  :caption: c_cpp_properties.json
  :language: json

Use VS Code
-----------

For the :file:`projects/single-tile` application:

* Open :file:`projects/single-tile/main.c`. With this file active, use the
  keyboard shortcut :kbd:`Ctrl+Shift+B` to build the application.

* To run the application without debugging, hit :kbd:`Ctrl+P`, then start typing
  :samp:`task Run`. When `Run active file` is highlighted, press enter. The
  application output will appear in the Terminal view.

* To debug the application, hit :kbd:`Ctrl+P`, then start typing
  :samp:`task Debug`. When `Debug active file` is highlighted, press enter. An
  interactive debug session will begin in the Terminal view. When finished
  debugging, be sure to issue :samp:`quit` to end the session.

To build, run and debug the :file:`projects/switch-setup` application, carry out
the same actions, but first make sure that :file:`projects/switch-setup/main.c`
is the active file.

You may check that VS Code's 'Intellisense' is working correctly by hovering the
mouse over :samp:`chan_out_word` in :file:`projects/switch-setup/main.c`.

Further suggestions
-------------------

With the tools now integrated into VS Code, you might try:

* Setting up some keyboard shortcuts for the Run and Debug tasks
* Adding the :doc:`XSCOPE example <../../quick-start/fast-printf>` to your
  projects folder and using the
  `WaveTrace <https://marketplace.visualstudio.com/items?itemName=wavetrace.wavetrace>`_
  VS Code extension to view the generated .vcd file.

.. _config_ide_eclipse:

Eclipse
^^^^^^^

.. figure:: images/eclipse_example.png

  Example of tools plugged into Eclipse

Pre-requisites
--------------

#. Install `Eclipse CDT <https://www.eclipse.org/cdt/>`_.

#. Ensure the :ref:`command line environment is working <get_started>`.

#. Create the :ref:`example project content <config_ide_create_content>`

Start Eclipse and check the environment
---------------------------------------

From a bash terminal where the
:ref:`command line environment is working <get_started>`, start Eclipse:

.. code-block:: bash

  $ eclipse

Create a new Eclipse workspace in the :file:`projects` folder you have created.

Next check that Eclipse can access the tools. Open a Terminal window using
:menuselection:`Window-->Show View->Terminal`. Within the window, click the
"Open a Terminal" icon and launch a bash terminal. Confirm that the following
command produces the expected results:

.. code-block:: bash

  $ xcc --version

Configure Eclipse
-----------------

Follow these steps to import the :samp:`single-tile` project content you've
already created into your Eclipse workspace:

#. Navigate to :menuselection:`File-->New-->Makefile Project with Existing Code`
#. Project Name: :samp:`single-tile`
#. Existing Code Location: "Browse" to :file:`projects/single-tile`
#. Toolchain for Indexer Settings: Select :samp:`Cross GCC` (Untick "Show
   only..." if not visible)
#. Click "Finish"

This will create the :samp:`single-tile` project in the "Project Explorer"
window. We next make some adjustments (because we're not actually using GCC as
previously selected):

#. Right-click the :samp:`single-tile` project and select "Properties"
#. Navigate to
   :menuselection:`C/C++ General-->Preprocessor Include Paths, Macros etc.`
#. Select the "Providers" tab
#. Adjust the "Command to get compiler specs" to read:
   :samp:`xcc ${FLAGS} -march=xs2a -E -P -vv -dD "${INPUTS}"`
#. Click "Apply and Close"

These adjustments allow the Eclipse source code indexer to find the correct
include files within the toolkit. Confirm this is working in two ways:

#. Within the "Project Explorer" window, navigate to
   :menuselection:`single-tile-->Includes`. Confirm that the path to the
   contained include files is as expected.
#. Open the file :file:`main.c`. Confirm that the "Problems" window is empty
   (which indicates that indexing has completed successfully).

We now make further modifications because, in this example, we're not going to
use a :file:`Makefile` as previously selected:

#. Right-click the :samp:`single-tile` project and select "Properties"
#. Navigate to
   :menuselection:`C/C++ Build` and select the "Builder Settings" tab
#. Untick "Use default build command" and set "Build command" to
   :samp:`bash build.sh`
#. Click "Apply and Close"

Repeat these steps for the :samp:`switch-setup` project.

We now configure Eclipse for running and debugging:

#. Navigate to
   :menuselection:`Run-->External Tools-->External Tools Configurations...`
#. Click the icon "New launch configuration".
#. Select the "Main" tab and enter the following details:
   
   * Name: :samp:`Launch selected bash script`
   * Location: "Browse File System" to locate bash executable
   * Working Directory: :samp:`${container_loc}`
   * Arguments: :samp:`${selected_resource_name}`

#. Select the "Build" tab and select "The project containing the selected
   resource"

#. Click "Apply"
#. Click "Close"

Use Eclipse
-----------

Within the :samp:`single-tile` project:

* To build:

  #. Select any file within the project
  #. Click on the "Build" icon

* To build and run:

  #. Select :file:`run.sh` within the project
  #. Navigate to
     :menuselection:`Run-->External Tools-->Launch selected bash script`

* To build and debug:

  #. Select :file:`debug.sh` within the project
  #. Navigate to
     :menuselection:`Run-->External Tools-->Launch selected bash script`

Now try the same within the :samp:`switch-setup` project.

xTIMEcomposer Studio
^^^^^^^^^^^^^^^^^^^^

Integration of the 15.0.x toolchain with the xTIMEcomposer Studio IDE packaged
with previous tools releases is not recommended. Developers desiring a similar
IDE experience should follow the instructions for :ref:`config_ide_eclipse`.