blob: acc4595acd645a0f708c1e9d1337a7c335977bdb [file] [log] [blame]
Developing Mynewt Applications with Visual Studio Code
This guide shows you how to set up Visual Studio Code to develop and
debug Mynewt applications. Visual Studio Code is supported on Mac OS,
Linux, and Windows. This guide shows you how to:
1. Install Visual Studio Code.
2. Install the C/C++ and debugger extensions.
3. Define task configurations to build Mynewt applications.
4. Define debugger configurations to debug Mynewt applications.
5. Launch the debugger.
.. contents::
:depth: 2
- Have Internet connectivity to fetch remote Mynewt components.
- Have a computer to build a Mynewt application.
- Perform :doc:`native installation <../get_started/native_install/index>` for the
Mynewt tools and toolchains.
**Note:** For Windows platforms, ensure that the MinGW bash you
install is added to your Windows Path. In addition, if you are using
Windows 10 WSL, you must have the MinGW bash before the Windows 10
WSL bash in your Windows Path.
- Read the Mynewt OS Concepts section.
- Create a project space (directory structure) and populate it with the
core code repository (apache-mynewt-core) or know how to as explained
in Creating Your First Project.
- Complete one of the :ref:`Blinky Tutorials <blinky_tutorials>`.
- This guide is not a tutorial for Visual Studio Code. It assumes you
are familiar with Visual Studio Code. If this is your first time
using Visual Studio Code, we recommend that you read the Visual
Studio Code `documentation and
tutorials <>`__ and evaluate
whether you would like to use it to develop Mynewt applications.
- This guide uses Visual Studio Code on Windows. Visual Studio Code is
supported on Linux and Mac OS but may have some variations in the
keyboard shortcuts and command names for these platforms.
- You can also use the Eclipse IDE to develop Mynewt applications. See
`hacking-mynewt-in-eclipse <>`__ for more
details. On Windows platforms, you must also ensure the MinGW bash is
set in your Windows Path as described in the prerequisites.
Installing Visual Studio Code
Download and install Visual Studio Code from
Installing the C/C++ and Debugger Extensions
You need to install two extensions:
1. The C/C++ extension from Microsoft. This extension provides language
support such as symbol searching, signatuare help, go to definition,
and go to declaration.
2. The Native Debug extension from webfreak. This extension provides GDB
To install the C/C++ extension:
1. Press ``Ctrl-P`` to open the search box.
2. Type ``ext install cpptools`` in the search box and press Enter. You
should see the extension at the top of the list.
3. Click ``Install`` to install the extension.
To install the Native Debugger:
1. Press ``Ctrl-P`` to open the search box.
2. Type ``ext install webfreak.debug`` in the search box and press
Enter. You should see the Native Debug extension at the top of the
3. Click ``Install`` to install the extension.
Defining Tasks for Mynewt Projects
Two main concepts in Visual Studio Code are workspaces and tasks. A
workspace represents a folder that is open. You can open multiple
workspaces and switch between workspaces.
Tasks allow you to integrate the external tools and operations that are
used to build or test your project into Visual Studio Code. Tasks are
run from and the task results can be analyzed in Visual Studio Code.
Tasks are defined within the scope of a workspace. This means that the
tasks you define for a workspace only apply to the given workspace.
Associating a Mynewt Project to a Workspace
For your Mynewt
project, your Visual Studio Code workspace is the Mynewt project base
directory. For example, if you create a project named ``myproj`` under
the ``~/dev`` directory, then you open the ``~/dev/myproj`` folder for
your workspace.
Select **File** > **Open Folder**, and select the ``myproj`` folder from
the ``Select Folder`` dialog box to open the folder.
Defining Visual Studio Code Tasks to Build and Debug Mynewt Applications
You define Visual Studio Code tasks to build and debug your Mynewt
targets in Visual Studio Code. We use the Blinky application for the
Arduino Zero board from the :doc:`Blinky On Arduino Zero
Tutorial <../tutorials/blinky/arduino_zero>` to illustrate how to define
the tasks to build and debug the Arduino blinky bootloader and
application targets.
Perform the following steps to create the tasks to build and debug the
Arduino blinky bootloader and appliction targets:
Step 1: Press ``Ctrl-Shift-P``, type ``task``, and select
**Tasks:Configure Task Runner** from the search results.
Step 2: Select **Others** (scroll down to the bottom of the list) to
create a task runner for external commands.
.. figure:: pics/task_runner_small.png
Tasks are defined in the ``tasks.json`` file. You should see the
``.vscode`` folder created in the ``MYPROJ`` folder and a ``tasks.json``
file created in the ``.vscode`` folder. The ``tasks.json`` file has the
following default values.
.. figure:: pics/task_json_small.png
The sample ``tasks.json`` file defines a simple task that runs the echo
command with "Hello World" as the argument.
Step 3: Delete the content from the ``tasks.json`` file, add the
following definitions, and press ``Ctrl-S`` to save the file.
.. code-block:: JSON
"version": "0.1.0",
"command": "newt",
"echoCommand": true,
"isShellCommand": true,
"taskName": "build_arduino_boot",
"args": ["build", "arduino_boot"],
"suppressTaskName": true
"taskName": "build_arduino_blinky",
"args": ["build", "arduino_blinky"],
"isBuildCommand": true,
"suppressTaskName": true
"taskName": "create_arduino_blinky",
"args": ["create-image", "arduino_blinky", "1.0.0"],
"taskName": "debug_arduino_blinky",
"args": ["debug", "arduino_blinky", "-n"],
"suppressTaskName": true
The ``tasks.json`` file specifies the tasks that are run to build and
debug the Arduino blinky targets. Each task runs a ``newt`` command. The
``newt`` command to run and the arguments for the ``newt`` command are
passed in the ``args`` property for each task.
The following tasks are defined in this example:
1. **build_arduino_boot**: Runs the ``newt build arduino_boot``
command to build the arduino_boot target.
2. **build_arduino_blinky**: Runs the ``newt build arduino_blinky``
command to build the arduino_blinky target.
**Note:** This task sets the ``isBuildCommand`` property to ``true``.
This is an optional property that, when set to true, allows you to
run the **Tasks: Run Build Task**\ (``Ctrl-Shift-B``) command to
start the task.
3. **create_arduino_blinky**: Runs the
``newt create-image arduino_blinky`` command to create the image
4. **debug_arduino_blinky**: Runs the ``newt build arduino_blinky -n``
command to debug the arduino_blinky target. The ``-n`` flag is
specified to start only the GDB server and not the GDB client. We
will launch the GDB client from Visual Studio Code.
For more information on tasks and all supported properties, see the
`Visual Studio Code Task
documentation <>`__.
Running a Task
To run a task, press ``Ctrl-Shift-P``, type ``task`` on the search box,
and select **Tasks: Run Task**. The tasks that you define in the
``tasks.json`` file are listed. Select the task to run.
The following is an example of running the ``build_arduino_boot`` task:
.. figure:: pics/task_select_small.png
.. figure:: pics/task_start_small.png
**Note**: To run the ``build_arduino_blinky`` task, you can use the
keyboard shortcut ``Ctrl-Shift-B`` because the task has the property
``isBuildCommand`` set to true.
Defining Tasks for Other Newt Commands
Other newt commands, such as the ``newt load`` command, do not need to
run from within Visual Studio Code. You can define a task for each
command as a convenience and run the command as a task, or you can run
the newt command on the command line from the Visual Studio Code
integrated terminal or an external terminal.
To create the tasks for the ``newt load arduino_boot`` and
``newt load arduino_blinky`` commands, add the following definitions to
the ``tasks.json`` file:
.. code-block:: JSON
"taskName": "load_arduino_boot",
"args": ["load", "arduino_boot"],
"taskName": "load_arduino_blinky",
"args": ["load", "arduino_blinky"],
To run a command from the Visual Studio integrated terminal, instead of
starting a task, press ``Ctrl-``` to launch the integrated terminal and
enter the command on the prompt:
.. figure:: pics/integrated_terminal_small.png
Defining Debugger Configurations
You need to define a debugger
configuration to launch the GDB debugger from within Visual Studio Code:
Step 1: Select **Debug** > **Open Configuration**, and select the
**GDB** environment.
.. figure:: pics/debug_new_config_small.png
You should see a default ``launch.json`` file created in the ``.vscode``
.. figure:: pics/launch_small.png
Step 2: Delete the content from the ``launch.json`` file, add the
following definitions, and press 'Ctrl-S' to save the file.
.. code-block:: json
"version": "0.2.0",
"configurations": [
"name": "gdb_arduino_blinky",
"type": "gdb",
"request": "attach",
"executable": "${workspaceRoot}\\bin\\targets\\arduino_blinky\\app\\apps\\blinky\\blinky.elf",
"target": ":3333",
"cwd": "${workspaceRoot}",
"gdbpath": "C:\\Program Files (x86)\\GNU Tools ARM Embedded\\4.9 2015q2\\bin\\arm-none-eabi-gdb.exe",
"remote": true
This defines a ``gdb_arduino_blinky`` debugger configuration. It
- The debugger is type **gdb**.
- To use the ``blinky.elf`` file for the executable.
- To use port 3333 to connect with the remote target.
- To use arm-none-eabi-gdb for the GDB program.
Debugging Your Application
To debug your application, start the GDB server and
launch the GDB session from Visual Studio Code. For the the arduino
blinky example, perform the following:
Step 1: Run the debug_arduino_blinky task to start the GDB server.
Perform the following:
1. Press ``Ctrl-Shift-P`` and type ``task`` in the search box.
2. Select **Tasks:Run Task** > **debug_arduinoblinky**.
3. Press ``Ctrl-Shift-U`` to open the Output Panel and see the OpenOCD
GDB Server output.
.. figure:: pics/gdb_server_small.png
Step 2: Start the GDB session. Perform the following:
1. Press ``Ctrl-Shift-Y`` to view the Debug Console.
2. Press the Debugging icon on the activity bar (Ctrl-Shift-D) to bring
up the Debug Side Bar.
3. Select ``gdb_arduino_blinky`` from the DEBUG drop down menu.
4. Press the green play button to start the gdb session.
.. figure:: pics/gdb_small.png
Step 3: Debug your application. You should see a debug session similar
to the one shown below:
.. figure:: pics/gdb_debug_small.png
For more information on how to use the Visual Studio Code Debugger, see
the `Visual Studio Code debugging
documentation <>`__.
Working with Multiple Mynewt Applications
As mentioned previously, each mynewt project corresponds to a Visual
Studio Code workspace. If you have multiple Mynewt application targets
defined in same project, you will need to define build and debug tasks
for each target in the ``tasks.json`` file and debugger configurations
for the targets in the ``launch.json`` file for the workspace. If you
have a different Mynewt project for each mynewt application, you will
need to define build and debug tasks in the ``tasks.json`` file and the
debugger configuration in the ``launch.json`` file for each workspace.