Added IntelliSense setup auto-generation project (sketch-context) configuration flag which can override the global flag

Author: elektronikworkshop

BRANCHNOTES.md

@@ -18,6 +18,8 @@ Provide a configuration flag which allows the user to turn this feature off - th
 ### Status
 **2020-02-05** Currently I'm able to generate error free IntelliSense setups for AVR and ESP32 using the preliminary implementation. For ESP32 I just had to add the intrinsic compiler paths manually. A solution has to be found for these ... which there is, see [here](https://stackoverflow.com/a/6666338)
 **2020-02-06** Got it fully working (with built-in include directories) for AVR, ESP32, ESP8266. Rewrote the backend to facilitate writing of further parser engines in the future.
+**2020-02-07** Wrote compiler command parser npm package [cocopa](https://www.npmjs.com/package/cocopa) and began writing a test framework for it. Added a global configuration switch which allows the IntelliSense configuration generation to be turned off.
+**2020-02-08** Integrated `cocopa` into vscode-arduino. Added project configuration flag which can override the global flag in both ways (forced off, forced on). Made code tslint compliant. Began some documentation in [README.md](README.md)
 
 |      | Tasks   |
 |-----:|:--------|
@@ -35,17 +37,17 @@ Provide a configuration flag which allows the user to turn this feature off - th
 |                                       | :white_check_mark: Write configuration on change only |
 |                                       | :white_check_mark: Option to backup old configurations? |
 | **Configuration flags**               | :heavy_check_mark: Provide global disable flag for IntelliSense auto-config |
-|                                       | :white_check_mark: Provide project specific override for the global flag - most users will likely use the default setup and disable auto-generation for very specific projects |
+|                                       | :heavy_check_mark: Provide project specific override for the global flag - most users will likely use the default setup and disable auto-generation for very specific projects |
 | **Unit tests**                        | :heavy_check_mark: Basic parser (known boards, match/no match)|
 |                                       | :heavy_check_mark: Querying of compiler built-in includes (Note: to be changed to generic compiler such that Arduino is not necessary for unit testing) |
 |                                       | :white_check_mark: Throwing arbitrary data at parser engines |
 |                                       | :white_check_mark: JSON input |
 |                                       | :white_check_mark: JSON output |
 |                                       | :white_check_mark: Configuration merging |
 | **General**                           | :white_check_mark: Review and remove previous attempts messing with `c_cpp_properties.json` or IntelliSense. (Partially done - documented in the [General Tasks](#General-Tasks) section |
-|                                       | :white_check_mark: Auto-run verify after setting a board to generate a valid `c_cpp_properties.json`, identify other occasions where this applies (usually when adding new libraries), hint the user to run *verify*? -> Good moment would be after the workbench initialization -> message in arduino channel |
-|                                       | :white_check_mark: Document configuration settings in [README.md](README.md) |
-|                                       | :white_check_mark: Document features in [README.md](README.md) |
+|                                       | :white_check_mark: Auto-run verify after a) *setting a board* b) *changing the sketch*. We have to generate a valid `c_cpp_properties.json` to keep IntelliSense working in such situations. Identify other occasions where this applies (usually when adding new libraries), hint the user to run *verify*? -> Good moment would be after the workbench initialization -> message in arduino channel |
+|                                       | :heavy_check_mark: Document configuration settings in [README.md](README.md) |
+|                                       | :white_check_mark: Document features in [README.md](README.md) (partially done) |
 |                                       | :white_check_mark: How to handle compilation failure? Only set if more comprehensive |
 |                                       | :heavy_check_mark: Extract compiler command parser from vscode-arduino and [publish](https://itnext.io/step-by-step-building-and-publishing-an-npm-typescript-package-44fe7164964c) it as a separate package which will allow reusage and easy testing without heavy vscode-arduino rucksack. Done, see [cocopa](https://www.npmjs.com/package/cocopa) |
 |                                       | :white_check_mark: Finally: go through my code and look for TODOs |
@@ -67,7 +69,7 @@ I will list every supporter here, thanks!
 
 ### Supporters
 5$ -> 1 :beer:
-1h coding -> 20$ -> 4 :beers:
+1h coding -> 20$ -> 4 :beers: (very moderate wage though)
 2020-02-04 Elektronik Workshop: 32 :beers: (8h coding)
 2020-02-05 Elektronik Workshop: 40 :beers: (10h coding)
 2020-02-06 Elektronik Workshop: 36 :beers: (9h coding)
@@ -194,3 +196,8 @@ Remove these as they are helpless attempts to get IntelliSense working:
 ```
 Remove this as this messes in an unpredictable and helpless way with Intellisense
 [src/langService/completionProvider.ts](src/langService/completionProvider.ts)
+
+Remove this folder as this is not necessary when Intellisense works properly:
+```
+syntaxes/
+```

README.md

@@ -67,6 +67,7 @@ This extension provides several commands in the Command Palette (<kbd>F1</kbd> o
 | `arduino.disableTestingOpen` | Enable/disable automatic sending of a test message to the serial port for checking the open status. The default value is `false` (a test message will be sent). |
 | `arduino.skipHeaderProvider` | Enable/disable the extension providing completion items for headers. This functionality is included in newer versions of the C++ extension. The default value is `false`.|
 | `arduino.defaultBaudRate` | Default baud rate for the serial port monitor. The default value is 115200. Supported values are 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230400 and 250000 |
+| `arduino.disableIntelliSenseAutoGen` | When `true` vscode-arduino will not auto-generate an IntelliSense configuration (i.e. `.vscode/c_cpp_properties.json`) by analyzing Arduino's compiler output. |
 
 The following Visual Studio Code settings are available for the Arduino extension. These can be set in global user preferences <kbd>Ctrl</kbd> + <kbd>,</kbd> or workspace settings (`.vscode/settings.json`). The latter overrides the former.
 
@@ -98,7 +99,8 @@ The following settings are as per sketch settings of the Arduino extension. You
     "board": "adafruit:samd:adafruit_feather_m0",
     "output": "../build",
     "debugger": "jlink",
-    "prebuild": "bash prebuild.sh"
+    "prebuild": "bash prebuild.sh",
+    "disableIntelliSenseAutoGen": "global"
 }
 ```
 - `sketch` - The main sketch file name of Arduino.
@@ -107,6 +109,14 @@ The following settings are as per sketch settings of the Arduino extension. You
 - `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 in a subfolder of the workspace, otherwise, it may not work correctly. By default, this option is not set. It's worth noting that the contents of this file could be deleted during the build process, so pick (or create) a directory that will not store files you want to keep.
 - `debugger` - The short name of the debugger that will be used when the board itself does not have a debugger and there is 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.
 - `prebuild` - External command before building the sketch file. You should only set one `prebuild` command. `command1 && command2` does not work. If you need to run multiple commands before the build, then create a script.
+- `disableIntelliSenseAutoGen` - Override the global auto-generation of the IntelliSense configuration (i.e. `.vscode/c_cpp_properties.json`). Three options are available:
+  - `"global"`: Use the global settings (default)
+  - `"disable"`: Disable the auto-generation even if globally enabled
+  - `"enable"`: Enable the auto-generation even if globally disabled
+
+## IntelliSense
+vscode-arduino auto-configures IntelliSense by default. vscode-arduino analyzes Arduino's compiler output during verify and generates the corresponding configuration file at `.vscode/c_cpp_properties.json` and tries as hard as possible to keep things up to date, e.g. running verify when switching the board or the sketch.
+It doesn't makes sense though to run verify repeatedly. Therefore if the workspace reports problems (for instance after adding new includes to a new library) run *verify* such that IntelliSense knows of the new include directories (since the Arduino-backend performs the library resolution externally).
 
 ## Debugging Arduino Code <sup>preview</sup>
 Before you start to debug your Arduino code, please read [this document](https://code.visualstudio.com/docs/editor/debugging) to learn about the basic mechanisms of debugging in Visual Studio Code. Also see [debugging for C++ in VSCode](https://code.visualstudio.com/docs/languages/cpp#_debugging) for further reference.

misc/arduinoValidator.json

@@ -32,6 +32,16 @@
             "description": "Arduino Debugger Settings",
             "type": "string",
             "minLength": 1
+        },
+        "disableIntelliSenseAutoGen": {
+            "description": "Disable/enable the automatic generation of the IntelliSense configuration file (c_cpp_properties.json) for this project (overrides the global setting). When set to \"global\" the global extension settings will be used.",
+            "type": "string",
+            "default": "global",
+            "enum": [
+                "global",
+                "disable",
+                "enable"
+            ]
         }
     }
-}
+}

src/arduino/arduino.ts

@@ -805,7 +805,12 @@ export class ArduinoApp {
      */
     private makeCompilerParserContext(dc: DeviceContext)
         : { callback: (s: string) => void; conclude: () => void; } {
-        if (!VscodeSettings.getInstance().disableIntelliSenseAutoGen) {
+
+        const globalDisable = VscodeSettings.getInstance().disableIntelliSenseAutoGen;
+        const project = dc.disableIntelliSenseAutoGen;
+
+        if (project !== "disable" && !globalDisable ||
+            project === "enable") {
 
             // setup the parser with its engines
             const gccParserEngine = new ccp.ParserGcc(dc.sketch);

src/deviceContext.ts

@@ -57,6 +57,11 @@ export interface IDeviceContext {
      */
     configuration: string;
 
+    /**
+     * IntelliSense configuration auto-generation project override.
+     */
+    disableIntelliSenseAutoGen: string;
+
     onDidChange: vscode.Event<void>;
 
     initialize(): void;
@@ -82,6 +87,8 @@ export class DeviceContext implements IDeviceContext, vscode.Disposable {
 
     private _debugger: string;
 
+    private _disableIntelliSenseAutoGen: string;
+
     private _configuration: string;
 
     private _extensionPath: string;
@@ -151,6 +158,7 @@ export class DeviceContext implements IDeviceContext, vscode.Disposable {
                         this._configuration = deviceConfigJson.configuration;
                         this._output = deviceConfigJson.output;
                         this._debugger = deviceConfigJson["debugger"];
+                        this._disableIntelliSenseAutoGen = deviceConfigJson.disableIntelliSenseAutoGen;
                         this._prebuild = deviceConfigJson.prebuild;
                         this._programmer = deviceConfigJson.programmer;
                         this._onDidChange.fire();
@@ -164,6 +172,7 @@ export class DeviceContext implements IDeviceContext, vscode.Disposable {
                     this._configuration = null;
                     this._output = null;
                     this._debugger = null;
+                    this._disableIntelliSenseAutoGen = null;
                     this._prebuild = null;
                     this._programmer = null;
                     this._onDidChange.fire();
@@ -182,6 +191,7 @@ export class DeviceContext implements IDeviceContext, vscode.Disposable {
                 this._configuration = null;
                 this._output = null;
                 this._debugger = null;
+                this._disableIntelliSenseAutoGen = null;
                 this._prebuild = null;
                 this._programmer = null;
                 this._onDidChange.fire();
@@ -217,6 +227,7 @@ export class DeviceContext implements IDeviceContext, vscode.Disposable {
         deviceConfigJson.board = this.board;
         deviceConfigJson.output = this.output;
         deviceConfigJson["debugger"] = this.debugger_;
+        deviceConfigJson.disableIntelliSenseAutoGen = this.disableIntelliSenseAutoGen;
         deviceConfigJson.configuration = this.configuration;
         deviceConfigJson.programmer = this.programmer;
 
@@ -282,6 +293,15 @@ export class DeviceContext implements IDeviceContext, vscode.Disposable {
         this.saveContext();
     }
 
+    public get disableIntelliSenseAutoGen() {
+        return this._disableIntelliSenseAutoGen;
+    }
+
+    public set disableIntelliSenseAutoGen(value: string) {
+        this._disableIntelliSenseAutoGen = value;
+        this.saveContext();
+    }
+
     public get configuration() {
         return this._configuration;
     }