Add handling for now included GDB redistributable (#388)

* handle list of tools
* added customResetCommands to gdbtarget interface
* handle builtin gdb path in gdbtarget config resolver
* customResetCommands in debug config factory
* 'all' script
* warning notification if built-in tools not found
* update vscode mocks
* use file type instead of platform for download script
* reviewed .vscodeignore
* fix built-in gdb path and resolve only once
* add lzma-native, peer dependency of fast-extract for 'xz' format
* make sure we pass 'tar.xz' to fast-extract for proper chaining of tar and xz,
leave in 'file-type' for later refinement

---------

Signed-off-by: Jens Reinecke <jens.reinecke@arm.com>

Author: jreineckearm

.vscodeignore

@@ -1,19 +1,22 @@
+__mocks__/**/*
 .github
-.gitignore
+.qlty
 .vscode
-.vscodeignore
 *.vsix
-DEVELOPMENT.md
-__mocks__/**/*
+coverage
 dist/**/*.js.map
+images/*.pptx
 node_modules
+scripts
 src
+test-data
 test-workspace
+.gitignore
+.vscodeignore
+DEVELOPMENT.md
+test-report.html
 tsconfig.json
-scripts
-tools/**/version.txt
 tools/**/target.txt
 tools/**/sha256.txt
-coverage
 *.config.{mjs,js,mts,ts}
 *.setup.{mjs,js,mts,ts}

DEVELOPMENT.md

@@ -75,6 +75,15 @@ Supported `<target>`s are:
 
     **Note**: At this point, no tests have been added to this repository.
 
+## 'all' script
+
+To simplify setup of you environment, an `all` script exists which runs build, tool download,
+and unit tests. Run:
+
+```sh
+> yarn all
+```
+
 ## Updating tool dependencies
 
 Tool dependencies are recorded in `package.json`:

__mocks__/vscode.js

@@ -47,6 +47,7 @@ module.exports = {
             warn: jest.fn(),
             error: jest.fn(),
         })),
+        showWarningMessage: jest.fn(),
     },
     workspace: {
         getConfiguration: jest.fn(() => ({

package.json

@@ -92,6 +92,7 @@
     "watch": "webpack -w",
     "lint": "eslint .",
     "test": "jest --reporters=default --reporters=./node_modules/jest-html-reporter",
+    "all": "yarn && yarn download-tools && yarn test",
     "package": "vsce package --yarn",
     "tpip:report": "ts-node scripts/tpip-reporter --header docs/tpip-header.md docs/third-party-licenses.json TPIP.md",
     "lint:md": "markdownlint **/*.md -c ./.github/markdownlint.jsonc -i ./node_modules ./dist ./coverage ./tools",
@@ -123,6 +124,7 @@
     "globby": "^14.1.0",
     "jest": "^30.0.4",
     "jest-html-reporter": "^4.3.0",
+    "lzma-native": "8.0.6",
     "markdown-link-check": "^3.13.7",
     "markdownlint-cli": "^0.45.0",
     "node-fetch": "^3.3.2",

scripts/download-tools.ts

@@ -263,16 +263,12 @@ async function downloadGDB(target: VsceTarget, dest: string, options?: ToolOptio
     console.debug(`Extracting ${downloadFilePath} to ${destPath} ...`);
     mkdirSync(dest, { recursive: true });
 
-    const {fileTypeFromFile} = await import('file-type');
-
-    const fileType  = await fileTypeFromFile(downloadFilePath);
-
-    if (nodeOs.platform() === 'win32') {
+    if (ext === 'zip') {
         await extractZip(downloadFilePath, { dir: destPath }).catch(error => {
             throw new Error(`Failed to extract ${url}`, { cause: error });
         });
     } else {
-        await fastExtract(downloadFilePath, destPath, { strip: 1, type: fileType?.ext }).catch(error => {
+        await fastExtract(downloadFilePath, destPath, { strip: 1, type: ext }).catch(error => {
             throw new Error(`Failed to extract ${downloadFilePath}`, { cause: error });
         });
     }

src/debug-configuration/debug-configuration.factory.ts

@@ -53,6 +53,7 @@ export const gdbTargetConfiguration = makeFactory<GDBTargetConfiguration>({
     logFile: () => undefined,
     openGdbConsole: () => undefined,
     initCommands: () => undefined,
+    customResetCommands: () => undefined,
     preRunCommands: () => undefined,
     imageAndSymbols: () => undefined,
     target: () => undefined,

src/debug-configuration/gdbtarget-configuration-provider.test.ts

@@ -14,11 +14,17 @@
  * limitations under the License.
  */
 
-import { GDBTargetConfigurationProvider } from './gdbtarget-configuration-provider';
+import { GDBTargetConfiguration, GDBTargetConfigurationProvider } from '.'; // use index.ts to cover it in one test
 import { extensionContextFactory } from '../__test__/vscode.factory';
 
 import * as vscode from 'vscode';
+import { URI } from 'vscode-uri';
 import { debugConfigurationFactory } from './debug-configuration.factory';
+import { BuiltinToolPath } from '../desktop/builtin-tool-path';
+import { isWindows } from '../utils';
+
+jest.mock('../desktop/builtin-tool-path');
+const BuiltinToolPathMock = BuiltinToolPath as jest.MockedClass<typeof BuiltinToolPath>;
 
 describe('GDBTargetConfigurationProvider', () => {
 
@@ -49,4 +55,46 @@ describe('GDBTargetConfigurationProvider', () => {
 
         expect(resolvedDebugConfig).toBeDefined();
     });
+
+    it('resolves debug configuration and keeps gdb path if other than \'arm-none-eabi-gdb\'', async () => {
+        const absoluteGdbPath = '/absolute/path/to/gdb/arm-none-eabi-gdb';
+        const debugConfig = debugConfigurationFactory({
+            gdb: absoluteGdbPath
+        });
+
+        const getAbsolutePathSpy = jest.spyOn(BuiltinToolPath.prototype, 'getAbsolutePath');
+
+        const configProvider = new GDBTargetConfigurationProvider([]);
+        const resolvedDebugConfig = await configProvider.resolveDebugConfigurationWithSubstitutedVariables(
+            undefined,
+            debugConfig,
+            undefined) as GDBTargetConfiguration;
+
+        expect(resolvedDebugConfig).toBeDefined();
+        expect(resolvedDebugConfig.gdb).toEqual(absoluteGdbPath);
+        expect(getAbsolutePathSpy).not.toHaveBeenCalled();
+    });
+
+    it('resolves debug configuration and replaces \'arm-none-eabi-gdb\' with built-in tool path', async () => {
+        const absoluteGdbPath = '/absolute/path/to/gdb/arm-none-eabi-gdb';
+        const expectedGdbPath = isWindows ? absoluteGdbPath.replaceAll('/', '\\') : absoluteGdbPath;
+        const gdbUri = URI.parse(absoluteGdbPath);
+        const debugConfig = debugConfigurationFactory({
+            gdb: 'arm-none-eabi-gdb'
+        });
+
+        const builtinToolMockInstance = {
+            getAbsolutePath: jest.fn().mockReturnValue(gdbUri),
+        } as unknown as BuiltinToolPath;
+        BuiltinToolPathMock.mockImplementation(() => builtinToolMockInstance);
+
+        const configProvider = new GDBTargetConfigurationProvider([]);
+        const resolvedDebugConfig = await configProvider.resolveDebugConfigurationWithSubstitutedVariables(
+            undefined,
+            debugConfig,
+            undefined) as GDBTargetConfiguration;
+
+        expect(resolvedDebugConfig).toBeDefined();
+        expect(resolvedDebugConfig.gdb).toEqual(expectedGdbPath);
+    });
 });

src/debug-configuration/gdbtarget-configuration-provider.ts

@@ -23,8 +23,12 @@ import {
     JLINK_SERVER_TYPE_REGEXP,
     JlinkConfigurationProvider
 } from './subproviders';
+import { BuiltinToolPath } from '../desktop/builtin-tool-path';
 
 const GDB_TARGET_DEBUGGER_TYPE = 'gdbtarget';
+const ARM_NONE_EABI_GDB_NAME = 'arm-none-eabi-gdb';
+const ARM_NONE_EABI_GDB_BUILTIN_PATH = 'tools/gdb/bin/arm-none-eabi-gdb';
+const ARM_NONE_EABI_GDB_EXECUTABLE_ONLY_REGEXP = /^\s*arm-none-eabi-gdb(|.exe)\s*$/i;
 
 export interface GDBTargetConfigurationSubProvider {
     serverRegExp: RegExp;
@@ -40,6 +44,7 @@ const SUPPORTED_SUBPROVIDERS: GDBTargetConfigurationSubProvider[] = [
 
 
 export class GDBTargetConfigurationProvider implements vscode.DebugConfigurationProvider {
+    protected builtinArmNoneEabiGdb = new BuiltinToolPath(ARM_NONE_EABI_GDB_BUILTIN_PATH);
 
     public constructor(
         protected subProviders: GDBTargetConfigurationSubProvider[] = SUPPORTED_SUBPROVIDERS
@@ -132,6 +137,21 @@ export class GDBTargetConfigurationProvider implements vscode.DebugConfiguration
         debugConfiguration: vscode.DebugConfiguration,
         token?: vscode.CancellationToken
     ): Promise<vscode.DebugConfiguration | null | undefined> {
+        // Only resolve GDB path once, otherwise regexp check will fail
+        logger.debug('resolveDebugConfigurationWithSubstitutedVariables: Resolve GDB path');
+        this.resolveGdbPath(debugConfiguration);
         return this.resolveDebugConfigurationByResolverType('resolveDebugConfigurationWithSubstitutedVariables', folder, debugConfiguration, token);
     }
+
+    protected resolveGdbPath(config: GDBTargetConfiguration): void {
+        const gdb = config.gdb;
+        const useBuiltin = !gdb || ARM_NONE_EABI_GDB_EXECUTABLE_ONLY_REGEXP.test(gdb);
+        const updateUri = useBuiltin ? this.builtinArmNoneEabiGdb.getAbsolutePath() : undefined;
+        if (updateUri) {
+            config.gdb = updateUri.fsPath;
+        } else {
+            vscode.window.showWarningMessage(`Cannot find ${ARM_NONE_EABI_GDB_BUILTIN_PATH} in CMSIS Debugger installation.\nUsing ${ARM_NONE_EABI_GDB_NAME} from PATH instead.`);
+        }
+    }
+
 }

src/debug-configuration/gdbtarget-configuration.ts

@@ -69,6 +69,7 @@ export interface GDBTargetConfiguration extends vscode.DebugConfiguration {
     logFile?: string;
     openGdbConsole?: boolean;
     initCommands?: string[];
+    customResetCommands?: string[];
     preRunCommands?: string[];
     imageAndSymbols?: ImageAndSymbolsConfiguration;
     target?: TargetConfiguration;

src/debug-configuration/subproviders/pyocd-configuration-provider.ts

@@ -14,12 +14,14 @@
  * limitations under the License.
  */
 
+import * as vscode from 'vscode';
 import { BaseConfigurationProvider } from './base-configuration-provider';
 import { GDBTargetConfiguration, TargetConfiguration } from '../gdbtarget-configuration';
 import { BuiltinToolPath } from '../../desktop/builtin-tool-path';
 import { getCmsisPackRootPath } from '../../utils';
 import { logger } from '../../logger';
 
+const PYOCD_NAME = 'pyocd';
 const PYOCD_BUILTIN_PATH = 'tools/pyocd/pyocd';
 const PYOCD_EXECUTABLE_ONLY_REGEXP = /^\s*pyocd(|.exe)\s*$/i;
 export const PYOCD_SERVER_TYPE_REGEXP = /.*pyocd(|.exe)\s*$/i;
@@ -37,6 +39,8 @@ export class PyocdConfigurationProvider extends BaseConfigurationProvider {
         const updateUri = useBuiltin ? this.builtinPyocd.getAbsolutePath() : undefined;
         if (updateUri) {
             target.server = updateUri.fsPath;
+        } else {
+            vscode.window.showWarningMessage(`Cannot find ${PYOCD_BUILTIN_PATH} in CMSIS Debugger installation.\nUsing ${PYOCD_NAME} from PATH instead.`);
         }
     }