Merge pull request #443 from ARMmbed/f/mbed-studio-docs-enhancements

F/mbed studio docs enhancements

Author: Amanda Butler

docs/images/Mbed-Studio-Build-Button.png

@@ -1,6 +1,6 @@
-<h2 id="mbed-studio">Arm Mbed Studio</h2>
+<h2 id="mbed-studio">Arm Mbed Studio alpha</h2>
 
-Arm Mbed Studio is a local development environment for Mbed OS projects. This document helps Mbed OS developers use Mbed Studio to code, run, debug and deploy Mbed OS programs to Mbed Enabled devices. The Mbed Studio project is based on the Eclipse framework and extends Eclipse’s IDE capability to provide a more focused experience for developing with Mbed OS. In particular, it allows users to develop and deploy code offline. It also provides access to existing online resources.
+Arm Mbed Studio is a local development environment for Mbed OS projects. This document helps Mbed OS developers use Mbed Studio to code, run, and debug Mbed OS programs to supported Mbed Enabled devices. The Mbed Studio project is based on the Eclipse framework and extends Eclipse’s IDE capability to provide a more focused experience for developing with Mbed OS. In particular, it allows users to develop and run code offline. It also provides access to existing online resources.
 
 ### Current status and downloads
 
@@ -22,9 +22,9 @@ When you launch Mbed Studio, you see a login screen (unless you're using an inte
 
 When you arrive in your workspace, it's empty - clean, white and lacking in programs. It's time to start populating it.
 
-The first step is to create a project based on the included `mbed-os-example-blinky` example. You can do this using the Mbed Studio menu or using the context menu in the C++ Projects view of Mbed Studio.
+The first step is to create a project based on the included `mbed-os-example-blinky` example. You can do this using the Mbed Studio menu or using the context menu in the Mbed Projects view of Mbed Studio.
 
-To use the context menu, right-click (Ctrl-click) inside the Mbed Projects or C++ Projects view, and then select `New > Mbed OS Application`. To do the same through the menu, click `File > New > Mbed OS Application` to activate the New Project wizard.
+To use the context menu, right-click (Ctrl-click) inside the Mbed Projects or Mbed Projects view, and then select `New > Mbed OS Application`. To do the same through the menu, click `File > New > Mbed OS Application` to activate the New Project wizard.
 
 <span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Mbed-Studio-New-Application.png)<span>Create a new Mbed OS application.</span></span>
 
@@ -54,7 +54,21 @@ Double-click on the `main.cpp` file to open it in Mbed Studio’s editor. This f
 
 <span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Mbed-Studio-Blinky-Main-CPP.png)<span>Explore your new project.</span></span>
 
-##### Connecting a board
+#### Adding libraries to a project
+
+Mbed Studio supports importing libraries from GitHub. To import a library, right-click on the `Mbed Projects` view, and select `Import`. Now click `Mbed > Import Mbed library into existing project`. Choose the program that you want to add the library to.
+
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Mbed-Studio-Import-Library.png)<span>Import an Mbed library.</span></span>
+
+Next, choose a library and copy the URL for the GitHub repository.
+
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Mbed-Studio-GitHub-Library-URL.png)<span>Choose a library from GitHub.</span></span>
+
+Click `Finish`, and Mbed Studio adds the library to your program of choice.
+
+<span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Mbed-Studio-ESP8266-Library.png)<span>The imported library in the workspace.</span></span>
+
+### Connecting a board
 
 Connect an [Mbed Enabled development board](https://os.mbed.com/platforms/) to your machine, or select a target development board from the target dropdown. Mbed Studio detects the board, and a dialog asks to switch targets. Accept this, and you are ready to build and run the example.
 
@@ -64,35 +78,35 @@ Connect an [Mbed Enabled development board](https://os.mbed.com/platforms/) to y
 
 #### Running the project
 
-This section covers the necessary steps of building and running the project, so the program deploys and runs a connected board. Mbed Studio must recognize the board for the instructions in the Run section to work.
+This section covers the necessary steps of building and running the project on a connected board. Mbed Studio must recognize the board for the instructions in the Run section to work.
 
-##### Build
+### Build
 
 Before you can run the program, Mbed Studio needs to build a binary using a compiler. For the alpha version of Mbed Studio this compiler is GCC. There are multiple ways to start a build, but the easiest is to click the build icon.
 
 <span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Mbed-Studio-Build-Button.png)<span>Build your project.</span></span>
 
-Alternatively, you can right-click (Ctrl-click) on the project in the `Mbed Projects` view and then select `Build Project`. You can also use the menu by choosing `Project > Build Project`. Both build a binary that you can deploy.
+Alternatively, you can right-click (Ctrl-click) on the project in the `Mbed Projects` view and then select `Build Project`. You can also use the menu by choosing `Project > Build Project`. Both build a binary that you can run on your board.
 
-Alternatively, you can choose to build the project automatically through the menu by choosing `Project > Build Automatically`. This tells Mbed Studio to build the projects in the workspace whenever needed. After the build, an `mbed-os-example-blinky.bin` (or `<project name>.bin`) file is ready to deploy.
+Alternatively, you can choose to build the project automatically through the menu by choosing `Project > Build Automatically`. This tells Mbed Studio to build the projects in the workspace whenever needed. After the build, an `mbed-os-example-blinky.bin` (or `<project name>.bin`) file is ready to run.
 
 Once the build completes, the build artifacts, such as the .bin and .elf binaries, are in the `BUILD` folder under the active project. 
 
-##### Further exploration
+#### Further exploration
 
 Once you have built a project for a given target board, Eclipse can also index the `mbed-os-example-blinky` project, which means that it creates the appropriate mappings for the selected target. You can refresh this index by right-clicking on the project and selecting `Index > Freshen all files`. After Eclipse completes the indexing process, you can use the `Open declaration` function, or `F3` as a shortcut while hovering over a pin name, such as `led1`. This allows you to look through the dependency tree of the application and explore the underlying Mbed OS library.
 
 <span class="images">![](https://s3-us-west-2.amazonaws.com/mbed-os-docs-images/Mbed-Studio-Pin-Mapping.gif)<span>Press F3 to open a declaration, such as an IO pin name.</span></span> 
 
-##### Building automatically
+#### Building automatically
 
 Mbed Studio uses the tools built into Mbed OS to determine what builds and where the output of a build goes. The build tools build on request or (if the `Project > Build Automatically` option is checked) when you change and save a source file. The build operation only builds components that have changed and does nothing if nothing changed. Mbed Studio regards all projects in the workspace as part of the same system, so it initially builds all projects. Pressing the build button also ensures that all workspace projects build (if required).
 
 The aim is to maintain a system that is always in a built state, providing rapid error feedback to developers as they make changes.
 
 Under some circumstances (in particularly large projects, or when the target device changes frequently), you may wish to turn off automatic builds and build individual projects on request. To do this, select Build from the project right-click menu.
 
-##### Run
+### Run
 
 Now that you have built the `mbed-os-example-blinky project`, you can run it on your target board. Running a project consists of several phases, which you can abstract if you click the green run icon.
 
@@ -101,30 +115,24 @@ Now that you have built the `mbed-os-example-blinky project`, you can run it on
 The Mbed Studio run phases are:
 
 - Locate or create a suitable binary.
-- Deploy the binary to the target.
-- Reset target, causing the deployed program to run.
+- Flash the binary to the target.
+- Reset target, causing the new program to run.
 
 Although you manually built the project in the previous section and learned how to build a project in Mbed Studio, it wasn’t necessary before running. That’s because Mbed Studio checks that there is a binary for the currently selected target. If there isn’t one, Mbed Studio begins a compilation to create the binary. If there is a binary and there are no recent changes (build automatically option is on), Mbed Studio uses the existing binary to run the project.
 
-Once Mbed Studio has a binary of the Mbed OS program, it deploys that binary to the currently selected target and resets the target, so the program begins to run.
+Once Mbed Studio has a binary of the Mbed OS program, it flashes that binary to the currently selected development board and resets the board, so the program begins to run.
 
 To make it happen, click the green run icon to launch the default run configuration for your connected development board.
 
-Alternatively, open the context menu (right-click, ctrl-click) on the `mbed-os-example-blinky` project and select `Run As > Run Configurations...` from the menu. You can also use the menu by selecting `Run > Run Configurations`.
-
-In the `Run Configurations` window, right-click on `Mbed Deploy`, and select `New` to create an `Mbed Deploy` run configuration. This creates the run configuration you need to populate with details of your project and target. For project (if everything isn’t already populated), click `Choose`, and select the `mbed-os-example-blinky` project. The binary Mbed Studio builds fills in automatically. If you used a different project name, the binary name reflects that. Finally, click the Refresh button to ensure that the current target board’s ID updates if it hasn’t already.
-
-After you have configured everything, click on the Apply button and then on the Run button.
-
 Watch the primary LED on your connected target begin to blink!
 
-#### Debugging
+### Debug
 
 Now that you have learned the basics of Mbed Studio, it is time to learn how to debug projects within the IDE. There is a debug configuration specifically for debugging Mbed OS projects, which generates automatically. To launch a debug session on your development board, click the debug icon.
 
 There are also additional configurations for more advanced debugging. This section covers the Mbed OS debug configuration, as well as the advanced PyOCD GDB debug configuration.
 
-##### Simple debugging
+#### Simple debugging
 
 To begin debugging, click the bug icon, which launches the default debug configuration. A prompt asks you to switch to the debug perspective. Click `Yes` to switch. The debug perspective opens additional views, including a Debugger console, Debug view (which shows active threads and where the debugger stops), Variables, Memory and your code editor, which stops on a breakpoint by default.
 
@@ -138,7 +146,7 @@ Click `Choose...` next to the project textbox, and select the project you wish t
 
 Mbed Studio automatically switches into the Mbed Debug perspective when debugging with the Mbed Debug launch configuration. The project also brakes on a default break point.
 
-##### Advanced debugging
+#### Advanced debugging
 
 If you want more control over the options regarding debugging, this section is for you. This section describes how to create a PyOCD GDB debug configuration. This configuration allows you to change more settings, such as ports and executable locations for the GDB client and server.
 
@@ -178,11 +186,11 @@ Mbed Studio automatically sets up the workspace. Use it to keep track of setting
 
 ##### Project
 
-A project is a group of associated files, directories and settings. The `C++ Projects` view lists these projects. In Mbed Studio, each project represents an Mbed OS program or an Mbed OS library. An Mbed Studio project can also represent a program that includes libraries, as well.
+A project is a group of associated files, directories and settings. The `Mbed Projects` view lists these projects. In Mbed Studio, each project represents an Mbed OS program or an Mbed OS library. An Mbed Studio project can also represent a program that includes libraries, as well.
 
 ##### View
 
-In Mbed Studio, a view is a window that has a label, and sometimes options, specific to that window. Examples are the editor, C++ Projects, Console and Outline.
+In Mbed Studio, a view is a window that has a label, and sometimes options, specific to that window. Examples are the editor, Mbed Projects, Console and Outline.
 
 ##### Perspective
 
@@ -220,8 +228,8 @@ Workaround: None
 
 #### Windows
 
-Using the product update functionality in Eclipse returns a timestamp error.
-Workaround: This error does not prevent the product from successfully updating.
+GCC builds are slower in Windows than Mac or Linux.
+Workaround: None, this is also the case when using GCC from the command-line.
 
 ### FAQ