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#

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:

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

Within projects/single-tile:

  • Create main.c as per A single-tile program

  • Create the following three bash scripts:

    build.sh#
    #!/bin/bash

CWD=`pwd`
xcc -target=XCORE-200-EXPLORER -g $CWD/main.c
    run.sh#
    #!/bin/bash

xrun --io a.xe
    debug.sh#
    #!/bin/bash

xgdb a.xe

Within projects/switch-setup:

  • Create multitile.xc and main.c as per Communicating between tiles

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

    build.sh#
    #!/bin/bash

CWD=`pwd`
xcc -target=XCORE-200-EXPLORER -g $CWD/mapfile.xc $CWD/main.c

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#

../../../_images/vs_code_example.png

Example of tools plugged into VS Code#

Start VS Code and check the environment#

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

$ cd projects
$ code .

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

$ xcc --version

Configure VS Code#

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

tasks.json#
{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "Build active file",
            "type": "shell",
            "command": "bash",
            "args": [
                "./build.sh"
            ],
            "options": {
                "cwd": "${fileDirname}"
            },
            "problemMatcher": [
                "$gcc"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "Run active file",
            "type": "shell",
            "command": "bash",
            "args": [
                "./run.sh"
            ],
            "options": {
                "cwd": "${fileDirname}"
            },
            "problemMatcher": []
        },
        {
            "label": "Debug active file",
            "type": "shell",
            "command": "bash",
            "args": [
                "./debug.sh"
            ],
            "options": {
                "cwd": "${fileDirname}"
            },
            "problemMatcher": []
        }
    ]
}
c_cpp_properties.json#
{
    "version": 4,
    "configurations": [
        {
            "name": "Xcore",
            "includePath": [
                "${workspaceFolder}/**"
            ],
            "defines": ["XSCOPE_IMPL"],
            "compilerPath": "${XMOS_TOOL_PATH}/bin/xcc",
            "cStandard": "gnu11",
            "cppStandard": "gnu++14",
            "intelliSenseMode": "clang-x64",
            "compilerArgs": [
                "-save-temps"
            ]
        }
    ]
}

Use VS Code#

For the projects/single-tile application:

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

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

  • To debug the application, hit Ctrl+P, then start typing 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 quit to end the session.

To build, run and debug the projects/switch-setup application, carry out the same actions, but first make sure that 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 chan_out_word in 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 XSCOPE example to your projects folder and using the WaveTrace VS Code extension to view the generated .vcd file.

Eclipse#

../../../_images/eclipse_example.png

Example of tools plugged into Eclipse#

Pre-requisites#

  1. Install Eclipse CDT.

  2. Ensure the command line environment is working.

  3. Create the example project content

Start Eclipse and check the environment#

From a bash terminal where the command line environment is working, start Eclipse:

$ eclipse

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

Next check that Eclipse can access the tools. Open a Terminal window using 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:

$ xcc --version

Configure Eclipse#

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

  1. Navigate to File‣New‣Makefile Project with Existing Code

  2. Project Name: single-tile

  3. Existing Code Location: “Browse” to projects/single-tile

  4. Toolchain for Indexer Settings: Select Cross GCC (Untick “Show only…” if not visible)

  5. Click “Finish”

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

  1. Right-click the single-tile project and select “Properties”

  2. Navigate to C/C++ General‣Preprocessor Include Paths, Macros etc.

  3. Select the “Providers” tab

  4. Adjust the “Command to get compiler specs” to read: xcc $FLAGS -march=xs2a -E -P -vv -dD "$INPUTS"

  5. 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:

  1. Within the “Project Explorer” window, navigate to single-tile‣Includes. Confirm that the path to the contained include files is as expected.

  2. Open the 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 Makefile as previously selected:

  1. Right-click the single-tile project and select “Properties”

  2. Navigate to C/C++ Build and select the “Builder Settings” tab

  3. Untick “Use default build command” and set “Build command” to bash build.sh

  4. Click “Apply and Close”

Repeat these steps for the switch-setup project.

We now configure Eclipse for running and debugging:

  1. Navigate to Run‣External Tools‣External Tools Configurations…

  2. Click the icon “New launch configuration”.

  3. Select the “Main” tab and enter the following details:

    • Name: Launch selected bash script

    • Location: “Browse File System” to locate bash executable

    • Working Directory: $container_loc

    • Arguments: $selected_resource_name

  4. Select the “Build” tab and select “The project containing the selected resource”

  5. Click “Apply”

  6. Click “Close”

Use Eclipse#

Within the single-tile project:

  • To build:

    1. Select any file within the project

    2. Click on the “Build” icon

  • To build and run:

    1. Select run.sh within the project

    2. Navigate to Run‣External Tools‣Launch selected bash script

  • To build and debug:

    1. Select debug.sh within the project

    2. Navigate to Run‣External Tools‣Launch selected bash script

Now try the same within the switch-setup project.

xTIMEcomposer Studio#

Integration of the XTC 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 Eclipse.