User Guide¶

Welcome to the IAR-vsc user guide!

This guide will take you through all the features the IAR-vsc plugin provides to enhance your workflow with IAR using the power of Visual Studio Code. If you just want to get going, take a look at the Quickstart below.

Quickstart¶

Configure the following items:
- IAR: Select Workbench
- IAR: Select Compiler
- IAR: Select Project
- IAR: Select Configuration
Configure an IAR - build task using Tasks: Configure Task
Build your project

Installation¶

IAR-vsc can be installed simply through the extension marketplace from Visual Studio Code.

Requirements¶

This extensions presumes that you installed the cpptools plugin by Microsoft. Also a working IAR installation is needed.

Configuring¶

It is adviced to use the extension UI to configure the extension. The UI are statusbar items which will execute a command when clicking on them.

https://raw.githubusercontent.com/pluyckx/iar-vsc/master/Extension/images/readme/statusbar.png

You can also call the commands behind those buttons, see the contribution tab in the extension section of VS Code.

To configure your project, configure the following options:

IAR workbench installation
Compiler
Project (ewp file)
Configuration

Building¶

When you execute the VSCode command Tasks: Configure Task two items are added which are generated by this extension:

iar: IAR Build - template using selected workbench, project and config
iar: IAR Rebuild - template using selected workbench, project and config

When selecting one of the two, a default task is generated which uses the workbench, project and configuration selected using the UI. When you select a different configuration, project or workbench, this script will use the newly selected items.

Deprecated Method: Create manually¶

In previous plugins there was a build command. However, from now on you can create a task because all necessary information is available through settings. You can use the following snippets to create a build and rebuild command. In alpha2 or beta1 will contain a problem matcher. Use the following template as a starting point:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "IAR Build",
            "type": "process",
            "command": "${config:iarvsc.workbench}\\common\\bin\\IarBuild.exe",
            "args": [
                "${config:iarvsc.ewp}",
                "-make",
                "${config:iarvsc.configuration}"
            ],
            "problemMatcher": [
                "$iar-cc",
                "$iar-linker"
            ],
            "group": {
                "kind": "build",
                "isDefault": true
            }
        },
        {
            "label": "IAR Rebuild",
            "type": "process",
            "command": "${config:iarvsc.workbench}\\common\\bin\\IarBuild.exe",
            "args": [
                "${config:iarvsc.ewp}",
                "-build",
                "${config:iarvsc.configuration}"
            ],
            "problemMatcher": [
                "$iar-cc",
                "$iar-linker"
            ]
        }
    ]
}

Debugging¶

In v1.1.0 settings are added to configure a gdbserver and a gdb executable. The following data for the launch.json file will use this configuration to start debugging. Currently this is only for testing and is work in progress. The settings are nog yet automatically updated when selecting different projects or confiugrations (even though the description of the settings mention this).

Open or create the launch.json file and place your cursor at the beginning of the configurations array. Now press Ctrl + Space to activate autocompletion. You should see an item like IAR: Debug using gdb server. If you select this, the configuration below is automatically generated.

Some information about the used config parameters:

iarvsc.debugger: The path to the debugger to use. In case your debugger is on your PATH environment you can just enter the debugger executable like arm-none-eabi-gdb.exe, otherwise, use the absolute path to the debugger.
iarvsc.gdbServer: The path to the gdb server. If you are using a J-Link Segger, you will probably have to enter the full path like: C:\GNU Tools ARM Embedded\2018-q4-major\bin\arm-none-eabi-gdb.exe. Keep in mind you have to escape the backslashes \ in json.
iarvsc.device: The device you are want to flash and debug. Check your debug server documentation which values you can use here.
iarvsc.outFile: This field is not yet used in the current release, but it is mentioned here for completeness. You can use it, but keep in mind the value you enter here can conflict in future releases.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug GDBServer",
            "type": "cppdbg",
            "request": "launch",
            "program": "Path to the out file",
            "stopAtEntry": true,
            "cwd": "${workspaceFolder}",
            "externalConsole": true,
            "MIMode": "gdb",
            "miDebuggerPath": "${config:iarvsc.debugger}",
            "debugServerPath": "${config:iarvsc.gdbServer}",
            "debugServerArgs": "-if swd -singlerun -strict -endian little -speed auto -port 3333 -device ${config:iarvsc.device} -vd -strict -halt",
            "serverStarted": "Connected\\ to\\ target",
            "serverLaunchTimeout": 5000,
            "filterStderr": false,
            "filterStdout": true,
            "setupCommands": [
                {
                    "text": "target remote localhost:3333"
                },
                {
                    "text": "monitor flash breakpoints = 1"
                },
                {
                    "text": "monitor flash download = 1"
                },
                {
                    "text": "monitor reset"
                },
                {
                    "text": "load \\\"Path to the out file\\\""
                },
                {
                    "text": "monitor reset"
                }
            ]
        }
    ]
}

Extension Settings¶

This extension contributes the following settings:

iarvsc.iarInstallDirectories: The rootfolders where all IAR workbenches are installed. By default this is C:\Program Files (x86)\Iar Systems. The default settings contain also the non-x86 folder in case IAR will move to 64-bit installations.
iarvsc.workbench: The last selected workbench in this workspace.
iarvsc.compiler: The last selected compiler.
iarvsc.ewp: The last selected project file.
iarvsc.configuration: The last selected configuration.
iarvsc.defines: Some custom defines you can add to the define list. They folow the identifier=value structure. This list will contain all intrinsic compiler functions that are known by the author of this extension. If some are missing, create a GitHub issue.

An important note for the settings iarvsc.workbench, iarvsc.compiler, iarvsc.ewp, iarvsc.configuration: Those values get overwritten by the extension when invalid values are defined or you select different values using the extension UI (the status bar items) or commands.

Advanced usage¶

Using the settings it is possible to automate other IAR tasks. You can for instance automate flashing the device or running tests in the simulator using the generated cspy scripts. These scripts are available in the settings folder present in the same folder as you .ewp file.