Skip to content

Commit 37c76ea

Browse files
elierichaeliericha
committed
Merge branch 'topic/vscode-doc' into 'master'
Update the VS Code Ada extension landing page Closes #1207 See merge request eng/ide/ada_language_server!1438
2 parents 5a7bb69 + 760c943 commit 37c76ea

File tree

4 files changed

+188
-119
lines changed

4 files changed

+188
-119
lines changed

‎.vscode/extensions.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
"editorconfig.editorconfig",
77
"dbaeumer.vscode-eslint",
88
"esbenp.prettier-vscode",
9-
"gruntfuggly.triggertaskonsave"
9+
"gruntfuggly.triggertaskonsave",
10+
"davidanson.vscode-markdownlint"
1011
]
1112
}

‎README.md

Lines changed: 86 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -33,14 +33,19 @@ extension at
3333
- [Dependencies](#dependencies)
3434
- [Usage](#usage)
3535
- [Supported LSP Server Requests](#supported-lsp-server-requests)
36-
- [Protocol extensions](#protocol-extensions)
37-
- [How to use the VScode extension](#how-to-use-the-vscode-extension)
38-
- [Getting started](#getting-started)
39-
- [Auto-detected tasks](#auto-detected-tasks)
40-
- [Short demo](#short-demo)
41-
- [Commands and shortcuts](#commands-and-shortcuts)
42-
- [Launch the extension to debug it](#launch-the-extension-to-debug-it)
36+
- [Protocol Extensions](#protocol-extensions)
37+
- [VS Code Extension](#vs-code-extension)
38+
- [Getting Started](#getting-started)
4339
- [Configuration](#configuration)
40+
- [Refactoring](#refactoring)
41+
- [Tasks](#tasks)
42+
- [Task Customization](#task-customization)
43+
- [Commands and Shortcuts](#commands-and-shortcuts)
44+
- [Ada: Go to other file](#ada-go-to-other-file)
45+
- [Ada: Add subprogram box](#ada-add-subprogram-box)
46+
- [Ada: Reload project](#ada-reload-project)
47+
- [Bug Reporting](#bug-reporting)
48+
- [Limitations and Differences with GNAT Studio](#limitations-and-differences-with-gnat-studio)
4449
- [Integration with other editors and IDEs](#integration-with-other-editors-and-ides)
4550
- [Integration with Coc.NVim](#integration-with-cocnvim)
4651
- [Integration with vim-lsp](#integration-with-vim-lsp)
@@ -49,10 +54,11 @@ extension at
4954
- [Integration with emacs lsp-mode](#integration-with-emacs-lsp-mode)
5055
- [Integration with QtCreator](#integration-with-qtcreator)
5156
- [Refactoring Tools](#refactoring-tools)
52-
- [Authors & Contributors](#authors--contributors)
57+
- [Authors \& Contributors](#authors--contributors)
5358
- [Contribute](#contribute)
5459
- [License](#license)
5560

61+
5662
## Install
5763

5864
You can build language server from sources.
@@ -114,64 +120,62 @@ instead of specifying it via the requests listed just above.
114120
See [WiKi page](https://github.com/AdaCore/ada_language_server/wiki/Supported-LSP-requests)
115121
for the list of supported requests.
116122

117-
### Protocol extensions
123+
### Protocol Extensions
118124

119125
The Ada Language Server supports some features that are not in the official
120126
[Language Server Protocol](https://microsoft.github.io/language-server-protocol)
121127
specification. See [corresponding document](doc/README.md).
122128

123-
## How to use the VScode extension
124-
125-
### Current limitations and differences compared to GNAT Studio
126-
127-
The VSCode extension has a few limitations and some differences compared to [GNAT Studio](https://github.com/AdaCore/gnatstudio):
128-
129-
* **Indentation/formatting**: it does not support automatic indentation when adding a newline and range/document
130-
formatting might no succeed on incomplete/illegal code.
131-
132-
* **Toooling support**: we currently provide minimal support for *SPARK* (see *Prove/Examine* tasks in the [Auto-detected tasks](#auto-detected-tasks) section), but there is no support for tools such as *CodePeer*, *GNATcheck*, *GNATtest* or *GNATcoverage*.
133-
134-
* **Alire support**: if the root folder contains an `alire.toml` file and
135-
there is `alr` executable in the `PATH`, then the language server fetches
136-
the project's search path, environment variables and the project's file
137-
name from the crate description.
138-
139-
* **Project support**: there is no `Scenario` view: users should configure scenarios via the *ada.scenarioVariables* setting (see the settings list available [here](doc/refactoring_tools.md)). You can execute the *Ada: Reload project* command to reload your project after saving the new scenario values (use the *Ctrl+P* shortcut to invoke the **Command Palette**, allowing you to execute commands).
129+
## VS Code Extension
140130

141-
Source directories from imported projects should be added in a [workspace file](https://code.visualstudio.com/docs/editor/workspaces#_multiroot-workspaces). If you already have a workspace file, the extension will propose you to automatically add all the source directories coming from imported projects to your workspace automatically at startup.
131+
A VS Code extension based on this Ada Language Server is available on the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=AdaCore.ada).
132+
It provides a full set of features including syntax highlighting, navigation, building and debugging.
142133

143-
### Bug Reporting
134+
### Getting Started
144135

145-
You can use the VS Code `Issue Reporter` to report issues. Just click on the `Help -> Report Issue` menu, select `An extension` for the `File on` entry and `Language Support for Ada` for the extension name. Put as many information you can in the description, like steps to reproduce, stacktraces or system information (VS Code automatically includes it by default). This will create a GitHub issue in the [Ada Language Server](https://github.com/AdaCore/ada_language_server/) repository.
136+
[Tutorial: Using Ada in VS Code](https://github.com/AdaCore/ada_language_server/wiki/Getting-Started).
146137

147-
ALS log files can be found under the `~/.als` directory (`%USERPROFILE%/.als` on Windows). Feel free to attach them on the issues, it helps a lot for further investigation, specially when the `ALS.IN` and `ALS.OUT` traces are enabled (more info about traces configuration can be found [here](doc/traces.md).)
138+
### Configuration
148139

140+
You can configure the extension via the `.vscode/settings.json` workspace settings file or the [multi-root workspace file](https://code.visualstudio.com/docs/editor/multi-root-workspaces).
141+
See the setting list [here](doc/settings.md).
149142

150-
### Getting started
143+
Here is an example config file:
151144

152-
[Tutorial: Using Ada in VS Code](https://github.com/AdaCore/ada_language_server/wiki/Getting-Started).
145+
```json
146+
{
147+
"ada.projectFile": "gnatcov.gpr",
148+
"ada.scenarioVariables": {
149+
"BINUTILS_BUILD_DIR": "/null",
150+
"BINUTILS_SRC_DIR": "/null"
151+
},
152+
"ada.defaultCharset": "utf-8",
153+
"ada.enableDiagnostics": false,
154+
"ada.renameInComments": false
155+
}
156+
```
153157

154158
### Refactoring
155159

156160
See a [dedicated document](doc/refactoring_tools.md) with the list of available refactorings.
157161

158-
### Auto-detected tasks
162+
### Tasks
159163

160-
The extension includes a task provider. It provides the following "auto-detected" tasks
164+
The extension provides the following auto-detected tasks
161165
(under `/Terminal/Run Task...` menu):
162166

163-
* "ada: Build current project" - launch `gprbuild` to build the current GPR project
164-
* "ada: Check current file" - launch `gprbuild` to check errors in the current editor
165-
* "ada: Clean current project" - launch `gprclean` to clean the current GPR project
166-
* "ada: Examine project" - launch `gnatprove` in flow analysis mode on the current GPR project
167-
* "ada: Examine file" - launch `gnatprove` in flow analysis mode on the file in the current editor
168-
* "ada: Examine subprogram" - launch `gnatprove` in flow analysis mode on the current subprogram in the current editor
169-
* "ada: Prove project" - launch `gnatprove` on the current GPR project
170-
* "ada: Prove file" - launch `gnatprove` on the file in the current editor
171-
* "ada: Prove subprogram" - launch `gnatprove` on the current subprogram in the current editor
172-
* "ada: Prove selected region" - launch `gnatprove` on the selected region in the current editor
173-
* "ada: Prove line" - launch `gnatprove` on the cursor line in the current editor
174-
* "ada: Clean project for proof" - launch `gnatprove` on the current GPR project to clean proof artefacts
167+
* `ada: Build current project` - launch `gprbuild` to build the current GPR project
168+
* `ada: Check current file` - launch `gprbuild` to check errors in the current editor
169+
* `ada: Clean current project` - launch `gprclean` to clean the current GPR project
170+
* `spark: Examine project` - launch `gnatprove` in flow analysis mode on the current GPR project
171+
* `spark: Examine file` - launch `gnatprove` in flow analysis mode on the file in the current editor
172+
* `spark: Examine subprogram` - launch `gnatprove` in flow analysis mode on the current subprogram in the current editor
173+
* `spark: Prove project` - launch `gnatprove` on the current GPR project
174+
* `spark: Prove file` - launch `gnatprove` on the file in the current editor
175+
* `spark: Prove subprogram` - launch `gnatprove` on the current subprogram in the current editor
176+
* `spark: Prove selected region` - launch `gnatprove` on the selected region in the current editor
177+
* `spark: Prove line` - launch `gnatprove` on the cursor line in the current editor
178+
* `spark: Clean project for proof` - launch `gnatprove` on the current GPR project to clean proof artefacts
175179

176180
You can bind keyboard shortcuts to them by adding to the `keybindings.json` file:
177181

@@ -184,35 +188,34 @@ You can bind keyboard shortcuts to them by adding to the `keybindings.json` file
184188
}
185189
```
186190

187-
#### Short demo
188-
189-
[A demo for auto-detected tasks](https://github.com/AdaCore/ada_language_server/wiki/auto_detected_tasks.mp4)
191+
#### Task Customization
190192

191-
#### Task customization
192-
You can [customize autodetected tasks](https://code.visualstudio.com/docs/editor/tasks#_customizing-autodetected-tasks)
193-
by providing extra tool command line options via `args` property in the `tasks.json`:
193+
You can [customize auto-detected tasks](https://code.visualstudio.com/docs/editor/tasks#_customizing-autodetected-tasks)
194+
by providing extra tool command line options via the `args` property of the `configuration` object in the `tasks.json`:
194195

195196
```json
196197
{
197-
"version": "2.0.0",
198-
"tasks": [
199-
{
200-
"type": "gnat",
201-
"taskKind": "buildProject",
202-
"problemMatcher": [
203-
"$ada"
204-
],
205-
"group": "build",
206-
"label": "ada: Build project",
207-
"args": ["-gargs", "-vh"]
208-
}
209-
]
198+
"version": "2.0.0",
199+
"tasks": [
200+
{
201+
"type": "ada",
202+
"configuration": {
203+
"kind": "buildProject",
204+
"projectFile": "${config:ada.projectFile}",
205+
"args": ["-gargs", "-vh"]
206+
},
207+
"problemMatcher": ["$ada"],
208+
"group": "build",
209+
"label": "ada: Build current project with custom options"
210+
}
211+
]
210212
}
211213
```
212214

213-
### Commands and shortcuts
215+
### Commands and Shortcuts
214216

215-
The extension contributes a few commands and corresponding key bindings.
217+
The extension contributes commands and a few default key bindings.
218+
Below are a few examples, and other commands can be found by searching for `Ada:` in the command list.
216219

217220
#### Ada: Go to other file
218221

@@ -229,36 +232,29 @@ The default shortcut is `Alt+Shift+B`.
229232
This command reloads the current project.
230233
The default shortcut is `None`.
231234

232-
### Launch the extension to debug it
235+
### Bug Reporting
233236

234-
For the moment, this repository includes a vscode extension that is used as the
235-
reference extension for this implementation.
237+
You can use the VS Code `Issue Reporter` to report issues. Just click on the `Help -> Report Issue` menu, select `An extension` for the `File on` entry and `Language Support for Ada` for the extension name. Put as many information you can in the description, like steps to reproduce, stacktraces or system information (VS Code automatically includes it by default). This will create a GitHub issue in the [Ada Language Server](https://github.com/AdaCore/ada_language_server/) repository.
236238

237-
You can try it by running:
239+
ALS log files can be found under the `~/.als` directory (`%USERPROFILE%/.als` on Windows). Feel free to attach them on the issues, it helps a lot for further investigation, specially when the `ALS.IN` and `ALS.OUT` traces are enabled (more info about traces configuration can be found [here](doc/traces.md).)
238240

239-
```sh
240-
code --extensionDevelopmentPath=<path_to_this_repo>/integration/vscode/ada <workspace directory>
241-
```
241+
### Limitations and Differences with GNAT Studio
242242

243-
### Configuration
243+
The VS Code extension has a few limitations and some differences compared to [GNAT Studio](https://github.com/AdaCore/gnatstudio):
244244

245-
You can configure the extension via the `.vscode/settings.json` settings file.
246-
See the setting list [here](doc/settings.md).
245+
* **Indentation/formatting**: it does not support automatic indentation when adding a newline and range/document
246+
formatting might no succeed on incomplete/illegal code.
247247

248-
Here is an example config file from the gnatcov project:
248+
* **Tooling support**: we currently provide minimal support for *SPARK* (see *Prove/Examine* tasks in the [Auto-detected tasks](#auto-detected-tasks) section), but there is no support for tools such as *CodePeer*, *GNATcheck*, *GNATtest* or *GNATcoverage*.
249249

250-
```json
251-
{
252-
"ada.projectFile": "gnatcov.gpr",
253-
"ada.scenarioVariables": {
254-
"BINUTILS_BUILD_DIR": "/null",
255-
"BINUTILS_SRC_DIR": "/null"
256-
},
257-
"ada.defaultCharset": "utf-8",
258-
"ada.enableDiagnostics": false,
259-
"ada.renameInComments": false
260-
}
261-
```
250+
* **Alire support**: if the root folder contains an `alire.toml` file and
251+
there is `alr` executable in the `PATH`, then the language server fetches
252+
the project's search path, environment variables and the project's file
253+
name from the crate description.
254+
255+
* **Project support**: there is no `Scenario` view: users should configure scenarios via the *ada.scenarioVariables* setting (see the settings list available [here](doc/refactoring_tools.md)). You can execute the *Ada: Reload project* command to reload your project after saving the new scenario values (use the *Ctrl+P* shortcut to invoke the **Command Palette**, allowing you to execute commands).
256+
257+
Source directories from imported projects should be added in a [workspace file](https://code.visualstudio.com/docs/editor/workspaces#_multiroot-workspaces). If you already have a workspace file, the extension will propose you to automatically add all the source directories coming from imported projects to your workspace automatically at startup.
262258

263259
## Integration with other editors and IDEs
264260

‎doc/HACKING.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@ make
3030

3131
## Debugging
3232

33+
One way to run the ALS is by running the VS Code extension in development mode.
34+
You can do that using the VS Code workspace at the root of this repository and the launch configuration `(vscode) Launch vscode with the Ada extension`.
35+
3336
You can activate traces that show all the server input/output. This is done
3437
by creating a file `$HOME/.als/traces.cfg` with the following contents:
3538

0 commit comments

Comments
 (0)