Merge branch 'topic/walkthrough' into 'master'

eliericha · eliericha · commit 3b9fde717678 · 2024-08-28T08:51:19.000Z
Revamp the VS Code walkthrough

Closes #1406

See merge request eng/ide/ada_language_server!1664
diff --git a/integration/vscode/ada/media/build.md b/integration/vscode/ada/media/build.md
@@ -0,0 +1,8 @@
+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.
+
+The [Alire](https://alire.ada.dev/) package manager for Ada and SPARK is also supported seamlessly. If it is available in the environment and if your project is an Alire crate, then all tasks will automatically use Alire.
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).`