Revamp the VS Code walkthrough

eliericha · eliericha · commit 6489ccf91af3 · 2024-08-27T09:06:56.000Z
Closes eng/ide/ada_language_server#1406
diff --git a/integration/vscode/ada/media/build.md b/integration/vscode/ada/media/build.md
@@ -0,0 +1,6 @@
+Several VS Code tasks are provided to work with Ada & SPARK projects.
+You can find them by using the [`Tasks: Run Task`](command:workbench.action.tasks.runTask) command and selecting the `ada` or `spark` task groups.
+
+Use the [`ada: Build current project`](command:workbench.action.tasks.runTask?%22ada%3A%20Build%20current%20project%22) task to build your project.
+
+If you would like to customize a task, for example by providing additional command line arguments, you can use the gear icon on the right-hand side of a task and edit it in your workspace's `tasks.json` file.
diff --git a/integration/vscode/ada/media/edit.md b/integration/vscode/ada/media/edit.md
@@ -0,0 +1,13 @@
+When writing Ada or SPARK in VS Code you can benefit from the following features:
+
+- Syntax highlighting
+- Outline
+- Pop-up documentation when hovering on symbols
+- Code completion proposals
+- Navigation to definitions
+- Find all references to an entity
+- Find all calls to a subprogram
+- Call hierarchy
+- Refactoring
+
+and [more](https://github.com/AdaCore/ada_language_server?tab=readme-ov-file#vs-code-extension)...
diff --git a/integration/vscode/ada/media/empty.md b/integration/vscode/ada/media/empty.md
diff --git a/integration/vscode/ada/media/launch-debug.md b/integration/vscode/ada/media/launch-debug.md
@@ -1,27 +1,18 @@
-# 🔨 Build a project
+If your project defines a `Main` entry point, you can launch or debug it as follows.
 
-Use "auto-detected tasks" (i.e: `gnat` tasks in the `Run Task` dialog) to
- * ⚙ Build the whole project
- * ✅ Check errors in the current file
- * 🔎 Launch `gnatprove` to verify your SPARK code, if any (you can find the tool [here](https://github.com/alire-project/GNAT-FSF-builds/releases))
+# 🚀 Launch
 
-## 🚀 Launch
+- The [`Tasks: Run Task`](command:toSide:workbench.action.tasks.runTask) command offers tasks called `ada: Run main - ...` and `ada: Build and run main - ...`. The former run the main executable while the latter conveniently builds the project and runs the executable at once.
+- A Run button is displayed right above the declaration of the main subprogram. It's a shortcut to the `ada: Build and run main - ...` task.
 
-Open a new terminal to launch your executable once it has been built.
+To provide command line argument to your executable, use the gear icon at the right-hand side of the task to customize arguments in the `tasks.json` file.
 
-## 🐞 Debug
+Alternatively, open a new terminal and launch the executable manually with the desired command line arguments.
 
-The [ms-vscode.cpptools](https://github.com/microsoft/vscode-cpptools) extension
-is automatically installed along with this extension, allowing to use its
-integration for GDB to debug Ada code.
+# 🐞 Debug
 
-The extension provides default debug configurations for all the mains of your
-project. You can debug the executable of your choice by opening the
-`Run and Debug` panel and then by clicking on the `Run and Debug` button.
-You can also run directly the `Debug: Start Debugging` command instead of using the UI. In some circumstances the UI may offer a selection of languages, in which case select `Ada`.
-The extension will then propose you to select the main you want to debug if your project contains several mains.
+Ada debugging leverages the integration of GDB through the [Microsoft C/C++](command:toSide:extension.open?%22ms-vscode.cpptools%22) VS Code extension.
 
-If you want to customize GDB's behavior or if you need to add custom arguments, you
-will have to create a `launch.json` file: this can be done through the
-`create a launch.json file` link button in the `Run and Debug` panel or directly via
-the `Debug: Add Configuration` command.
+You can start debugging by running the [`Debug: Start Debugging`](command:toSide:ada.walkthroughStartDebugging) command and selecting `Ada` if multiple languages are offered.
+
+If you would like to provide command line arguments to the debugged program or customize GDB's behavior, use the [`Debug: Add Configuration`](command:toSide:debug.addConfiguration) command to create a `launch.json` where you can customize these aspects.
diff --git a/integration/vscode/ada/media/more-resources.md b/integration/vscode/ada/media/more-resources.md
@@ -1,13 +1,7 @@
-# ☀ Welcome to Ada!
+📖 Take a look at the following tutorials and demos from our [wiki](https://github.com/AdaCore/ada_language_server/wiki) to learn more about Ada & SPARK development in VS Code:
 
-Take a few minutes to learn about the features provided by the Ada extension.
-
-Use this extension to develop in Ada/SPARK in VS Code.
-
-📖 Take a look at our [WiKi site](https://github.com/AdaCore/ada_language_server/wiki) with tutorials and demos:
 * [Tutorial: Using Ada in VS Code](https://github.com/AdaCore/ada_language_server/wiki/Getting-Started)
 * [Auto detection Tasks video](https://github.com/AdaCore/ada_language_server/wiki/auto_detected_tasks.mp4)
 * [Custom colors in VS Code](https://github.com/AdaCore/ada_language_server/wiki/Custom-colors-in-VS-Code)
 * [Working in a Docker container](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/Code%20Samples/docker)
 * [Working on a remote machine](https://github.com/AdaCore/ada_language_server/wiki/Working-on-a-remote-machine)
-
diff --git a/integration/vscode/ada/media/project.md b/integration/vscode/ada/media/project.md
@@ -0,0 +1,8 @@
+A GPR project file allows you to specify the directories containing your source files, the compilation options used to build your project and many more aspects of your project's lifecycle.
+
+If you don't already have a project file, click the button on the left to get started with a Hello World example!
+
+If you only have one `.gpr` file at the root of your workspace, the Ada & SPARK extension will automatically use it.
+However we recommend configuring the main project file explicitly in the workspace setting [ada.projectFile](command:toSide:workbench.action.openWorkspaceSettings?%22ada.projectFile%22).
+
+📖 Learn more about project files in the [GPRbuild and GPR Companion Tools User’s Guide](https://docs.adacore.com/live/wave/gprbuild/html/gprbuild_ug/gprbuild_ug.html).
diff --git a/integration/vscode/ada/media/settings.md b/integration/vscode/ada/media/settings.md
@@ -1,16 +1,5 @@
-# Configure the extension
+You can customize the Ada & SPARK experience to your liking in the [settings](command:toSide:workbench.action.openWorkspaceSettings?%22%40ext%3Aadacore.ada%22).
 
-☝ Make sure to configure the active `*.gpr` project file, otherwise
-the extension will use the first project file found in the root project
-folder.
+📖 More information about the available settings is available [here](https://github.com/AdaCore/ada_language_server/blob/master/doc/settings.md).
 
-⚙ You can change settings per workspace or per user: generally we recommend to
-change the project file settings in the desired workspace, since project files
-are usually workspace-specific.
-
-📋 [List of Ada settings](https://github.com/AdaCore/ada_language_server/blob/master/doc/settings.md)
-
-## ⌨ Find or change key shortcuts
-
-* `alt+O` to go from `.ads` to `.adb` and back
-* `alt+shift+B` to paste a "subprogram box"
+A number of [keyboard shortcuts](command:toSide:workbench.action.openGlobalKeybindings?%22%40source%3Aextension%20Ada%20%26%20SPARK%22) are also provided for quick actions.
diff --git a/integration/vscode/ada/media/toolchain.md b/integration/vscode/ada/media/toolchain.md
@@ -0,0 +1,3 @@
+Ada and SPARK are compiled languages which means that a compiler is needed to translate the source code into a program that can be executed.
+
+We recommend installing the GNAT compiler for Ada from [these channels](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/ada#getting-additional-tools) and [configuring it in your environment](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/ada#environment-setup).
diff --git a/integration/vscode/ada/package.json b/integration/vscode/ada/package.json
@@ -840,44 +840,58 @@
         },
         "walkthroughs": [
             {
-                "id": "als-get-stated",
-                "title": "Ada in VS Code",
-                "description": "Introduction to Ada in VS Code support",
+                "id": "als-get-started",
+                "title": "Get Started with Ada & SPARK",
+                "description": "A brief introduction of Ada & SPARK support in VS Code",
                 "steps": [
                     {
-                        "id": "als-get-stated-welcome",
-                        "title": "Welcome to Ada extension!",
-                        "description": "This short walkthrough introduces the Ada extension.",
+                        "id": "als-get-started-install-toolchain",
+                        "title": "Install development tools",
+                        "description": "Install an Ada compiler to execute your source code.\n[Install a Compiler](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/ada#getting-additional-tools)",
                         "media": {
-                            "markdown": "media/welcome.md"
+                            "markdown": "media/toolchain.md"
                         }
                     },
                     {
-                        "id": "als-get-stated-setting",
-                        "title": "Set a project file",
-                        "description": "Set the active project file in the ``ada.projectFile`` setting.\n [Open Settings](command:workbench.action.openSettings)",
+                        "id": "als-get-started-open-workspace",
+                        "title": "Open a VS Code workspace",
+                        "description": "Create a new folder or use an existing one, and open it with VS Code.\n[Open Folder](command:vscode.openFolder)",
                         "media": {
-                            "markdown": "media/settings.md"
+                            "markdown": "media/empty.md"
                         },
-                        "completionEvents": [
-                            "onSettingChanged:ada.projectFile"
-                        ]
+                        "when": "workspaceFolderCount == 0"
                     },
                     {
-                        "id": "als-open-project-file",
-                        "title": "GPR project file support",
-                        "description": "Open the GPR project file you have specified in the ``ada.projectFile`` setting. Open the ``Outline`` view to see all the entities (packages, switches...) of your GPR file.",
+                        "id": "als-get-started-create-project",
+                        "title": "Create a project",
+                        "description": "If you don't already have a GPR project, create one!\n[Create a Hello World Project](command:toSide:ada.createHelloWorldProject)",
                         "media": {
-                            "markdown": "media/settings.md"
+                            "markdown": "media/project.md"
+                        }
+                    },
+                    {
+                        "id": "als-get-started-edit",
+                        "title": "Navigate and edit your code",
+                        "description": "Open an Ada source file to explore features.\n[Open an Ada Source File](command:workbench.action.quickOpen?%22.ad%22)",
+                        "media": {
+                            "markdown": "media/edit.md"
+                        }
+                    },
+                    {
+                        "id": "als-get-started-build",
+                        "title": "Build your project",
+                        "description": "Use automatically provided `ada` tasks to build your project.\n[Build Project](command:workbench.action.tasks.runTask)",
+                        "media": {
+                            "markdown": "media/build.md"
                         },
                         "completionEvents": [
-                            "onLanguage:gpr"
+                            "onCommand:workbench.action.tasks.runTask"
                         ]
                     },
                     {
-                        "id": "als-get-stated-debug",
-                        "title": "Launch and debug",
-                        "description": "Use the pre-installed **C/C++** extension to debug Ada code.",
+                        "id": "als-get-started-debug",
+                        "title": "Launch and debug your application",
+                        "description": "Use automatically provided debug configurations.\n[Start Debugging](command:toSide:ada.walkthroughStartDebugging)",
                         "media": {
                             "markdown": "media/launch-debug.md"
                         },
@@ -886,9 +900,25 @@
                         ]
                     },
                     {
-                        "id": "als-get-stated-github",
-                        "title": "Report issues or contribute to the extension",
-                        "description": "This extension is an open source software. Feel free to [open an issue](https://github.com/AdaCore/ada_language_server/issues) or [contribute on GitHub](https://github.com/AdaCore/ada_language_server/pulls)!",
+                        "id": "als-get-started-settings",
+                        "title": "Configure settings",
+                        "description": "Configure your Ada development environment.\n[Open Ada & SPARK Settings](command:toSide:workbench.action.openWorkspaceSettings?%22%40ext%3Aadacore.ada%22)\n[Open Ada & SPARK Keyboard Shortcuts](command:toSide:workbench.action.openGlobalKeybindings?%22%40source%3Aextension%20Ada%20%26%20SPARK%22)",
+                        "media": {
+                            "markdown": "media/settings.md"
+                        }
+                    },
+                    {
+                        "id": "als-get-started-more-resources",
+                        "title": "Tutorials and Demos",
+                        "description": "",
+                        "media": {
+                            "markdown": "media/more-resources.md"
+                        }
+                    },
+                    {
+                        "id": "als-get-started-github",
+                        "title": "Report issues or make contributions",
+                        "description": "This extension is open source software. Feel free to [open an issue](https://github.com/AdaCore/ada_language_server/issues) or [contribute on GitHub](https://github.com/AdaCore/ada_language_server/pulls)!",
                         "media": {
                             "image": "media/github.jpg",
                             "altText": "Github snapshot"
diff --git a/integration/vscode/ada/src/commands.ts b/integration/vscode/ada/src/commands.ts
@@ -19,6 +19,7 @@ import {
     isFromWorkspace,
     workspaceTasksFirst,
 } from './taskProviders';
+import { createHelloWorldProject, walkthroughStartDebugging } from './walkthrough';
 
 /**
  * Identifier for a hidden command used for building and running a project main.
@@ -57,6 +58,12 @@ export const CMD_SPARK_LIMIT_REGION_ARG = 'ada.spark.limitRegionArg';
 export const CMD_SPARK_PROVE_SUBP = 'ada.spark.proveSubprogram';
 
 export function registerCommands(context: vscode.ExtensionContext, clients: ExtensionState) {
+    context.subscriptions.push(
+        vscode.commands.registerCommand('ada.createHelloWorldProject', createHelloWorldProject)
+    );
+    context.subscriptions.push(
+        vscode.commands.registerCommand('ada.walkthroughStartDebugging', walkthroughStartDebugging)
+    );
     context.subscriptions.push(vscode.commands.registerCommand('ada.otherFile', otherFileHandler));
     context.subscriptions.push(
         vscode.commands.registerCommand('ada.subprogramBox', addSubprogramBoxCommand)
diff --git a/integration/vscode/ada/src/walkthrough.ts b/integration/vscode/ada/src/walkthrough.ts
@@ -0,0 +1,137 @@
+import { existsSync } from 'fs';
+import * as vscode from 'vscode';
+
+/**
+ * This function creates a hello world project in the current workspace. It is
+ * called from the walkthrough of the extension.
+ */
+export async function createHelloWorldProject() {
+    if (vscode.workspace.workspaceFolders) {
+        const wsFolder = vscode.workspace.workspaceFolders[0];
+        const fs = vscode.workspace.fs;
+        const prjUri = vscode.Uri.joinPath(wsFolder.uri, 'hello_world.gpr');
+        const srcUri = vscode.Uri.joinPath(wsFolder.uri, 'src');
+        const objUri = vscode.Uri.joinPath(wsFolder.uri, 'obj');
+        const mainUri = getHelloWorldMainUri(wsFolder);
+
+        await fs.createDirectory(srcUri);
+        // Create obj/ directory to avoid GPR warning
+        await fs.createDirectory(objUri);
+        await createFile(
+            prjUri,
+            `project Hello_World is
+   for Source_Dirs use ("src");
+   for Object_Dir use "obj";
+   for Main use ("hello_world.adb");
+
+   package Compiler is
+      for Switches ("Ada") use ("-g", "-O0");
+   end Compiler;
+end Hello_World;
+`
+        );
+        await createFile(
+            mainUri,
+            `with Ada.Text_IO;
+
+procedure Hello_World is
+    Msg : constant String := "Hello World!";
+begin
+    Ada.Text_IO.Put_Line (Msg);
+end Hello_World;
+`
+        );
+
+        /**
+         * Set ada.projectFile explicitly since that's recommended.
+         */
+        await vscode.workspace
+            .getConfiguration()
+            .update('ada.projectFile', vscode.workspace.asRelativePath(prjUri));
+
+        /**
+         * Show the created files for convenience.
+         */
+        await vscode.window.showTextDocument(prjUri, { preserveFocus: true, preview: false });
+        await vscode.window.showTextDocument(mainUri, { preserveFocus: true, preview: false });
+    } else {
+        void vscode.window.showErrorMessage(
+            'You must open a workspace folder before creating the Ada Hello World project'
+        );
+    }
+}
+
+async function createFile(uri: vscode.Uri, content: string) {
+    const fs = vscode.workspace.fs;
+    try {
+        // First we check that the file doesn't exist.
+        await fs.stat(uri);
+        const msg = `The file ${vscode.workspace.asRelativePath(
+            uri
+        )} already exists. Retry in an empty workspace.`;
+        void vscode.window.showErrorMessage(msg);
+        throw Error(msg);
+    } catch (error) {
+        if (
+            error instanceof vscode.FileSystemError &&
+            error.code == vscode.FileSystemError.FileNotFound.name
+        ) {
+            // The file doesn't exist. We can proceed.
+        } else {
+            // Unexpected error, throw it.
+            throw error;
+        }
+    }
+
+    await fs.writeFile(uri, Buffer.from(content, 'utf-8'));
+}
+
+/**
+ * This function is called from the walkthrough to start a debugging session.
+ *
+ * If the hello world source file exists, it opens it and sets sets a
+ * breakpoint. Otherwise no breakpoint is set.
+ *
+ * Finally the workbench.action.debug.start command is called to start the
+ * debug session.
+ */
+export async function walkthroughStartDebugging() {
+    if (vscode.workspace.workspaceFolders) {
+        const wsFolder = vscode.workspace.workspaceFolders[0];
+        const mainUri = getHelloWorldMainUri(wsFolder);
+
+        if (existsSync(mainUri.fsPath)) {
+            await vscode.window.showTextDocument(mainUri, {
+                preserveFocus: false,
+                selection: new vscode.Range(5, 0, 5, 0),
+            });
+
+            /**
+             * Since there's only a command to toggle breakpoints, we must
+             * clear all breakpoints first to make sure we are enabling the
+             * desired breakpoint.
+             */
+            await vscode.commands.executeCommand(
+                'workbench.debug.viewlet.action.removeAllBreakpoints'
+            );
+            await vscode.commands.executeCommand('editor.debug.action.toggleBreakpoint');
+        }
+
+        await vscode.commands.executeCommand('workbench.action.debug.start');
+    } else {
+        void vscode.window.showInformationMessage(
+            'You must open a workspace folder before using this command'
+        );
+    }
+}
+
+/**
+ * This function is defined to share the main source file location between the
+ * creation of the hello world project, and the starting of the debug session.
+ *
+ * @param wsFolder - the root WorkspaceFolder
+ * @returns the path to the hello world main source file.
+ */
+function getHelloWorldMainUri(wsFolder: vscode.WorkspaceFolder) {
+    return vscode.Uri.joinPath(wsFolder.uri, 'src', 'hello_world.adb');
+}

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+Ada and SPARK are compiled languages which means that a compiler is needed to translate the source code into a program that can be executed.`
	`2`	`+`
	`3`	`+We recommend installing the GNAT compiler for Ada from [these channels](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/ada#getting-additional-tools) and [configuring it in your environment](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/ada#environment-setup).`