Leverage the output path config to speedup upload/verify (#378)

* Make Upload aware output config & add warning for missing output config

* Add document about arduino.json in README

* Improve README

Author: codeworm96

README.md

@@ -50,7 +50,7 @@ This extension provides several commands in the Command Palette (`F1` or `Ctrl +
 - **Arduino: Verify**: Build sketch.
 
 ## Options
-The following Visual Studio Code settings are available for the Arduino extension. These can user preferences `Ctrl + ,` or workspace settings (.vscode/settings.json). The later overrides the former.
+The following Visual Studio Code settings are available for the Arduino extension. These can be set in global user preferences `Ctrl + ,` or workspace settings (.vscode/settings.json). The later overrides the former.
 
 ```json
 {
@@ -63,6 +63,24 @@ The following Visual Studio Code settings are available for the Arduino extensio
 - `arduino.additionalUrls` - Additional URLs for 3rd party packages. You can have multiple URLs in one string with comma(,) as separator, or have a string array. The default value is empty.
 - `arduino.logLevel` - CLI output log level. Could be info or verbose. The default value is `"info"`.
 
+The following settings are per sketch settings of the Arduino extension. You can find them in
+`.vscode/arduino.json` under the workspace.
+
+```json
+{
+    "sketch": "example.ino",
+    "port": "COM5",
+    "board": "adafruit:samd:adafruit_feather_m0",
+    "output": "../build",
+    "debugger": "jlink"
+}
+```
+- `sketch` - The main sketch file name of Arduino.
+- `port` - Name of the serial port connected to the device. Can be set by the `Arduino: Select Serial Port` command.
+- `board` - Current selected Arduino board alias. Can be set by the `Arduino: Change Board Type` command. Also, you can find the board list there.
+- `output` - Arduino build output path. If not set, Arduino will create a new temporary output folder each time, which means it cannot reuse the intermediate result of the previous build, leading to long verify/upload time. So it is recommended to set the field. Arduino requires that the output path should not be the workspace itself or subfolder of the workspace, otherwise, it may not work correctly. By default, this option is not set.
+- `debugger` - The short name of the debugger that will be used when the board itself does not have any debugger and there are more than one debugger available. You can find the list of debuggers [here](https://github.com/Microsoft/vscode-arduino/blob/master/misc/debuggerUsbMapping.json). By default, this option is not set.
+
 ## Debugging Arduino Code <sup>preview</sup>
 Before you start debug your Arduino code, read [this doc](https://code.visualstudio.com/docs/editor/debugging) and get to know the basic mechanism about debugging in Visual Studio Code. Also see [debugging for C++ in VSCode](https://code.visualstudio.com/docs/languages/cpp#_debugging) for your reference.
 

src/arduino/arduino.ts

@@ -123,6 +123,13 @@ export class ArduinoApp {
         if (VscodeSettings.getInstance().logLevel === "verbose") {
             args.push("--verbose");
         }
+        if (dc.output) {
+            const outputPath = path.join(vscode.workspace.rootPath, dc.output);
+            args.push("--pref", `build.path=${outputPath}`);
+        } else {
+            const msg = "Output path is not specified. Unable to reuse previously compiled files. Upload could be slow. See README.";
+            vscode.window.showWarningMessage(msg);
+        }
         await util.spawn(this._settings.commandPath, arduinoChannel.channel, args).then(async () => {
             UsbDetector.getInstance().resumeListening();
             if (needRestore) {
@@ -161,6 +168,9 @@ export class ArduinoApp {
         if (output || dc.output) {
             const outputPath = path.join(vscode.workspace.rootPath, output || dc.output);
             args.push("--pref", `build.path=${outputPath}`);
+        } else {
+            const msg = "Output path is not specified. Unable to reuse previously compiled files. Verify could be slow. See README.";
+            vscode.window.showWarningMessage(msg);
         }
 
         arduinoChannel.show();