| |
| |
| 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:: |
| :local: |
| :depth: 2 |
| |
| Prerequisites: |
| |
| - 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>`. |
| |
| **Notes:** |
| |
| - 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 <https://code.visualstudio.com/docs>`__ 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 <https://www.codecoup.pl/blog/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 https://code.visualstudio.com/. |
| |
| 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 |
| support. |
| |
| 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 |
| list. |
| 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, |
| |
| "tasks":[ |
| { |
| "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"], |
| "suppressTaskName":true |
| }, |
| { |
| "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 |
| file. |
| 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 <https://code.visualstudio.com/docs/editor/tasks>`__. |
| |
| 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"], |
| "suppressTaskName":true |
| }, |
| { |
| "taskName": "load_arduino_blinky", |
| "args": ["load", "arduino_blinky"], |
| "suppressTaskName":true |
| }, |
| ] |
| |
| 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`` |
| folder. |
| |
| .. 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 |
| specifies: |
| |
| - 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 <https://code.visualstudio.com/docs/editor/debugging>`__. |
| |
| 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. |