You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@mynewt.apache.org by ad...@apache.org on 2017/05/22 16:45:24 UTC
[6/7] incubator-mynewt-site git commit: Documentation on how to use
Visual Studio Code to develop Mynewt Applications.
Documentation on how to use Visual Studio Code to develop Mynewt Applications.
Project: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/commit/83e95ecc
Tree: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/tree/83e95ecc
Diff: http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/diff/83e95ecc
Branch: refs/heads/develop
Commit: 83e95ecc65c5d9de254cd1889b1ea9af29eb3493
Parents: 80bbb50
Author: cwanda <wa...@happycity.com>
Authored: Fri May 19 23:53:32 2017 -0700
Committer: cwanda <wa...@happycity.com>
Committed: Sat May 20 20:34:45 2017 -0700
----------------------------------------------------------------------
docs/faq/ide.md | 243 +++++++++++++++++++++++
docs/faq/pics/debug_new_config_small.png | Bin 0 -> 71855 bytes
docs/faq/pics/gdb_debug_small.png | Bin 0 -> 134895 bytes
docs/faq/pics/gdb_server_small.png | Bin 0 -> 99128 bytes
docs/faq/pics/gdb_small.png | Bin 0 -> 59655 bytes
docs/faq/pics/integrated_terminal_small.png | Bin 0 -> 51077 bytes
docs/faq/pics/launch_small.png | Bin 0 -> 92234 bytes
docs/faq/pics/task_json_small.png | Bin 0 -> 93487 bytes
docs/faq/pics/task_runner_small.png | Bin 0 -> 92407 bytes
docs/faq/pics/task_select_small.png | Bin 0 -> 66049 bytes
docs/faq/pics/task_start_small.png | Bin 0 -> 99242 bytes
mkdocs.yml | 1 +
12 files changed, 244 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/ide.md
----------------------------------------------------------------------
diff --git a/docs/faq/ide.md b/docs/faq/ide.md
new file mode 100644
index 0000000..2f5307d
--- /dev/null
+++ b/docs/faq/ide.md
@@ -0,0 +1,243 @@
+## 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.
+
+Prerequisites:
+
+* Have Internet connectivity to fetch remote Mynewt components.
+* Have a computer to build a Mynewt application.
+* Perform [native installation](/os/get_started/native_install_intro.md) for the Mynewt tools and toolchains.
+* 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 [Blinky Tutorials](/os/tutorials/blinky.md).
+
+**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 [https://www.codecoup.pl/blog/hacking-mynewt-in-eclipse](https://www.codecoup.pl/blog/hacking-mynewt-in-eclipse) for more details.
+
+###Installing Visual Studio Code
+Download and install Visual Studio Code from [https://code.visualstudio.com/](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.
+
+<br>
+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.
+<br>
+
+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.
+<br>
+###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.
+
+<br>
+####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.
+
+<br>
+####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 [Blinky On Arduino Zero Tutorial](/os/tutorials/arduino_zero.md) 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` in the search box, 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.
+<br>
+<p align="center"><img src="/faq/pics/task_runner_small.png"></p>
+<br>
+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.
+
+<br>
+<p align="center"><img src="/faq/pics/task_json_small.png"></p>
+<br>
+
+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.
+
+```no-highlight
+{
+ "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
+ }
+ ]
+}
+```
+<br>
+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).
+
+<br>
+####Running a Task
+
+To run a task, select `Ctrl-Shift-P`, type `task`, 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:
+<br>
+<p align="center"><img src="/faq/pics/task_select_small.png"></p>
+<br>
+<br>
+<p align="center"><img src="/faq/pics/task_start_small.png"></p>
+
+<br>
+####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 tasks for them as a convenience or run them 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 laod arduino_blinky` commands, add the following definitions to the `tasks.json` file:
+
+```no-highlight
+ {
+ "taskName": "load_arduino_boot",
+ "args": ["load", "arduino_boot"],
+ "suppressTaskName":true
+ },
+ {
+ "taskName": "load_arduino_blinky",
+ "args": ["load", "arduino_blinky"],
+ "suppressTaskName":true
+ },
+
+```
+<br>
+To run the commands from the Visual Studio integrated terminal, press ``Ctrl-` `` to launch the integrated terminal and enter the command as shown:
+<br>
+<p align="center"><img src="/faq/pics/integrated_terminal_small.png"></p>
+<br>
+###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.
+
+<br>
+<p align="center"><img src="/faq/pics/debug_new_config_small.png"></p>
+<br>
+
+You should see a default `launch.json` file created in the `.vscode` folder.
+<br>
+<p align="center"><img src="/faq/pics/launch_small.png"></p>
+<br>
+
+<br>
+Step 2: Delete the content from the `launch.json` file, add the following definitions, and press 'Ctrl-S' to save the file.
+
+```no-highlight
+{
+ "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": "arm-none-eabi-gdb.exe",
+ "remote": true
+
+ }
+ ]
+}
+
+```
+<br>
+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.
+<br>
+###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_arduino_blinky**.
+3. Press `Ctrl-Shift-U` to open the Output Panel and see the OpenOCD GDB Server output.
+<br>
+<p align="center"><img src="/faq/pics/gdb_server_small.png"></p>
+<br>
+
+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.
+
+<p align="center"><img src="/faq/pics/gdb_small.png"></p>
+<br>
+Step 3: Debug your application. You should see a debug session similar to the one shown below:
+<p align="center"><img src="/faq/pics/gdb_debug_small.png"></p>
+<br>
+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.
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/debug_new_config_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/debug_new_config_small.png b/docs/faq/pics/debug_new_config_small.png
new file mode 100755
index 0000000..5d2e287
Binary files /dev/null and b/docs/faq/pics/debug_new_config_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/gdb_debug_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/gdb_debug_small.png b/docs/faq/pics/gdb_debug_small.png
new file mode 100755
index 0000000..5ebfb11
Binary files /dev/null and b/docs/faq/pics/gdb_debug_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/gdb_server_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/gdb_server_small.png b/docs/faq/pics/gdb_server_small.png
new file mode 100755
index 0000000..e6a42d7
Binary files /dev/null and b/docs/faq/pics/gdb_server_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/gdb_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/gdb_small.png b/docs/faq/pics/gdb_small.png
new file mode 100755
index 0000000..f6c35d2
Binary files /dev/null and b/docs/faq/pics/gdb_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/integrated_terminal_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/integrated_terminal_small.png b/docs/faq/pics/integrated_terminal_small.png
new file mode 100755
index 0000000..11414c8
Binary files /dev/null and b/docs/faq/pics/integrated_terminal_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/launch_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/launch_small.png b/docs/faq/pics/launch_small.png
new file mode 100755
index 0000000..5c13dcf
Binary files /dev/null and b/docs/faq/pics/launch_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/task_json_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/task_json_small.png b/docs/faq/pics/task_json_small.png
new file mode 100755
index 0000000..5047f61
Binary files /dev/null and b/docs/faq/pics/task_json_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/task_runner_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/task_runner_small.png b/docs/faq/pics/task_runner_small.png
new file mode 100755
index 0000000..25a70fa
Binary files /dev/null and b/docs/faq/pics/task_runner_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/task_select_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/task_select_small.png b/docs/faq/pics/task_select_small.png
new file mode 100755
index 0000000..35bc304
Binary files /dev/null and b/docs/faq/pics/task_select_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/docs/faq/pics/task_start_small.png
----------------------------------------------------------------------
diff --git a/docs/faq/pics/task_start_small.png b/docs/faq/pics/task_start_small.png
new file mode 100755
index 0000000..f84cd26
Binary files /dev/null and b/docs/faq/pics/task_start_small.png differ
http://git-wip-us.apache.org/repos/asf/incubator-mynewt-site/blob/83e95ecc/mkdocs.yml
----------------------------------------------------------------------
diff --git a/mkdocs.yml b/mkdocs.yml
index 8ce61fe..ff41844 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -551,6 +551,7 @@ pages:
- 'Install Newtmgr On Windows': 'newtmgr/install_windows.md'
- Appendix:
- 'Setting Up Go to Contribute to Newt and Newtmgr Tools': 'faq/go_env.md'
+ - 'Using an IDE to Develop Mynewt Applications': 'faq/ide.md'
- 'Edit Docs': 'faq/how_to_edit_docs.md'
- 'FAQ': 'faq/answers.md'