Skip to content

Commit 071b64d

Browse files
AnthonyLeonardoGracioAnthonyLeonardoGracio
committed
Create doc for the Ada & SPARK Extension User's Guide
And add a reference to in the repository's main README file. For eng/ide/ada_language_server#1705
1 parent ab5b09e commit 071b64d

File tree

3 files changed

+407
-412
lines changed

3 files changed

+407
-412
lines changed

‎README.md‎

Lines changed: 1 addition & 368 deletions
Original file line numberDiff line numberDiff line change
@@ -136,374 +136,7 @@ specification. See [corresponding document](doc/README.md).
136136
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).
137137
It provides a full set of features including syntax highlighting, navigation, building and debugging.
138138

139-
### Getting Started
140-
141-
Here are some links that will help you get familiar with the VS Code extension for Ada & SPARK:
142-
143-
* [Ada & SPARK for VS Code](integration/vscode/ada/README.md).
144-
* [Tutorial: Using Ada in VS Code](https://github.com/AdaCore/ada_language_server/wiki/Getting-Started).
145-
146-
### Configuration
147-
148-
[ALS settings](doc/settings.md) can be specified in various ways. For example:
149-
150-
- A `.als.json` file at the root of the workspace.
151-
- A global user configuration file `$HOME/.config/als/config.json`
152-
- The `.vscode/settings.json` VS Code workspace settings file.
153-
- A [multi-root VS Code workspace file](https://code.visualstudio.com/docs/editor/multi-root-workspaces)
154-
- The User or Remote or other VS Code [scopes of of settings](https://code.visualstudio.com/docs/configure/settings#_settings-precedence)
155-
156-
The `.als.json` file is the preferred method of defining workspace-specific settings because it applies in any IDE or editor that uses ALS. More information about configuration files can be found [here](doc/settings.md).
157-
158-
Here is an example config file that sets the project file to use and the scenario variables, as well as other useful settings (charset, whether we should show file diagnostics etc.):
159-
160-
```json
161-
{
162-
"projectFile": "gnatcov.gpr",
163-
"scenarioVariables": {
164-
"BINUTILS_BUILD_DIR": "/null",
165-
"BINUTILS_SRC_DIR": "/null"
166-
},
167-
"defaultCharset": "utf-8",
168-
"adaFileDiagnostics": false,
169-
"renameInComments": false
170-
}
171-
```
172-
173-
Alternatively, the ALS can be configured in the VS Code settings UI or in the JSON settings files. For example:
174-
175-
```json
176-
{
177-
"ada.projectFile": "gnatcov.gpr",
178-
"ada.scenarioVariables": {
179-
"BINUTILS_BUILD_DIR": "/null",
180-
"BINUTILS_SRC_DIR": "/null"
181-
},
182-
"ada.defaultCharset": "utf-8",
183-
"ada.adaFileDiagnostics": false,
184-
"ada.renameInComments": false
185-
}
186-
```
187-
188-
### Refactoring
189-
190-
See a [dedicated document](doc/refactoring_tools.md) with the list of available refactorings.
191-
192-
### Tasks
193-
194-
The extension provides a number of auto-detected tasks under the `/Terminal/Run Task...` menu. These
195-
predefined tasks are all prefixed by `ada:` and belong to the `ada` group.
196-
They can be used to build and run your program (`ada: Build current project` task) or launch external tools such as GNAT SAS, GNATprove and a few others.
197-
198-
<img src="doc/media/run-task-ada-tasks.png" width="500" alt="GNATtest Test Results"/>
199-
200-
You can bind keyboard shortcuts to them by adding to the `keybindings.json` file:
201-
202-
```json
203-
{
204-
"key": "alt+v",
205-
"command": "workbench.action.tasks.runTask",
206-
"args": "ada: Check current file",
207-
"when": "editorLangId == ada"
208-
}
209-
```
210-
211-
#### Task Customization
212-
213-
You can [customize auto-detected tasks](https://code.visualstudio.com/docs/editor/tasks#_customizing-autodetected-tasks)
214-
by providing extra tool command line options via the `args` property of the object in the `tasks.json`:
215-
216-
```json
217-
{
218-
"version": "2.0.0",
219-
"tasks": [
220-
{
221-
"type": "ada",
222-
"command": "gprbuild",
223-
"args": [
224-
"${command:ada.gprProjectArgs}",
225-
"-cargs:ada",
226-
"-gnatef",
227-
"-gargs",
228-
"-vh"
229-
],
230-
"problemMatcher": ["$ada-error", "$ada-warning", "$ada-info"],
231-
"group": "build",
232-
"label": "ada: Build current project"
233-
}
234-
]
235-
}
236-
```
237-
238-
You can also customize the working directory of the task or the environment variables via the `options` property:
239-
240-
```json
241-
{
242-
"version": "2.0.0",
243-
"tasks": [
244-
{
245-
"type": "ada",
246-
"command": "gprbuild",
247-
"args": [
248-
"${command:ada.gprProjectArgs}",
249-
"-cargs:ada",
250-
"-gnatef"
251-
],
252-
"options": {
253-
"cwd": "${workspaceFolder}/my/subdir",
254-
"env": {
255-
"MY_ENV_VAR": "value"
256-
}
257-
},
258-
"problemMatcher": ["$ada-error", "$ada-warning", "$ada-info"],
259-
"group": "build",
260-
"label": "ada: Build current project"
261-
}
262-
]
263-
}
264-
```
265-
266-
#### Tasks for Project Mains
267-
268-
If your GPR project defines main programs via the project attribute `Main`, additional tasks are automatically provided for each defined main.
269-
For example, if the project defines a `main1.adb` and `main2.adb` located under the `src/` source directory, two different tasks will be available to build a given main:
270-
271-
* `ada: Build main - src/main1.adb`
272-
* `ada: Run main - src/main1.adb`
273-
274-
Same thing for all the predefined tasks that can have a main specified in their command line.
275-
276-
### Status Bar
277-
278-
A status bar item displaying the project-loading status and various useful commands provided by the Ada & SPARK extension (e.g `Ada: Reload Project` to reload a project after modifying it) is displayed on the left-side of the VS Code Status Bar.
279-
280-
<img src="doc/media/status_bar.gif" width="650" alt="Ada & SPARK Status Bar Item"/>
281-
282-
### Alire Support
283-
284-
When the workspace is an Alire crate (i.e. it contains an `alire.toml` file), the extension uses Alire to determine the GPR project that should be loaded and to obtain an environment where the crate's dependencies have been provisioned.
285-
286-
Moreover when working with an Alire crate, VS Code tasks automatically use standard Alire commands. For example, the `ada: Build current project` task uses the command `alr build` and the `ada: Clean current project` task uses the command `alr clean`.
287-
288-
All other tasks use `alr exec -- ...` to execute the command in the environment provided by Alire.
289-
290-
### GNATtest Support
291-
292-
If you install GNATtest, the Ada & SPARK extension for VS Code will provide the following functionalities:
293-
294-
* The task `ada: Create or update GNATtest test framework` will call `gnattest` to create a test harness and test skeletons for your project automatically. You can use standard VS Code task customization to configure command line arguments to your liking in a `tasks.json` file.
295-
296-
* Once the test harness project is created, the task `ada: Build GNATtest test harness project` is provided automatically for building it. Command line arguments can be customized by configuring the task in a `tasks.json` file.
297-
298-
* Tests created with GNATtest will be loaded in the VS Code **Testing** view as follows.
299-
300-
<img src="doc/media/gnattest-test-tree.png" width="650" alt="GNATtest Test Tree"/>
301-
302-
* Tests can be executed individually or in batch through the available buttons in the interface, or through the `Test: Run All Tests` command or related commands.
303-
304-
* Test execution always starts by executing the `ada: Build GNATtest test harness project` task to make sure that test executables are up to date.
305-
306-
* Test execution results are reflected in the test tree.
307-
308-
<img src="doc/media/gnattest-results.png" width="500" alt="GNATtest Test Results"/>
309-
310-
#### Using multi-root workspaces for test development
311-
312-
When developing tests, it is recommended to use the test harness project auto-generated by GNATtest.
313-
You can do so by editing the `ada.projectFile` setting to point to the test harness project.
314-
However to avoid switching back and forth between the main application project and the test harness project,
315-
see [Working with Multiple Projects in the Same VS Code Workspace](#working-with-multiple-projects-in-the-same-vs-code-workspace) for instructions on opening the test harness project in a separate VS Code window.
316-
317-
#### Limitations
318-
319-
* If you use a separate window to load the test harness project and edit tests, you have to go back to the main application project to benefit from the integration with the Test Explorer view (e.g. listing and searching for tests, running tests, etc...).
320-
This limitation is planned to be lifted.
321-
322-
* Sections of test sources delimited by `begin read only` and `end read only` comments are not really protected from inadvertant edits.
323-
To ensure proper interactions with GNATtest, you must refrain from making edits in those sections.
324-
325-
### GNATcoverage Support
326-
327-
GNATcoverage coverage reports can be imported in VS Code as follows:
328-
329-
1. Instruct GNATcoverage to produce an [XML report](https://docs.adacore.com/live/wave/gnatdas/html/gnatdas_ug/gnatcov/cov_source.html#xml-report-xml-xml)
330-
2. Invoke the VS Code command `ada: GNATcoverage - Load an existing XML coverage report`
331-
3. Browse to the location of the GNATcoverage XML report and select the `index.xml` file
332-
333-
<img src="doc/media/gnatcov-report.png" width="1000" alt="GNATcoverage report in VS Code" />
334-
335-
Note that importing coverage reports does not require GNATcoverage to be installed. In particular, this enables a workflow where the coverage report is produced in CI and downloaded and imported into VS Code for visualization and analysis.
336-
337-
Since VS Code does not support reporting MC/DC level coverage natively, that information is imported as branch coverage.
338-
339-
The GNATtest integration in VS Code also supports running tests in coverage mode, if GNATcoverage is installed on the development machine.
340-
341-
1. Run the task `ada: GNATcoverage - Setup runtime library` once to set up the GNATcoverage runtime library
342-
2. If you don't already have a test harness project created, use the task `ada: Create or update GNATtest test framework` to create one
343-
3. Switch to the _Test Explorer_ view or use the `Testing: Focus on Test Explorer View` command to do that
344-
4. Run the tests in coverage mode using the command `Test: Run All Tests with Coverage`, or use the "play" icon next to a single test or group of tests with the label _Run Test with Coverage_.
345-
5. In one go, VS Code will:
346-
1. Invoke [GNATcoverage source instrumentation](https://docs.adacore.com/live/wave/gnatdas/html/gnatdas_ug/gnatcov/src_traces.html)
347-
1. Build the test harness project
348-
1. Run the tests
349-
1. Invoke [GNATcoverage source coverage analysis](https://docs.adacore.com/live/wave/gnatdas/html/gnatdas_ug/gnatcov/cov_source.html)
350-
1. Load the GNATcoverage report into VS Code
351-
352-
<img src="doc/media/gnattest-gnatcov.png" width="1000" alt="GNATtest with GNATcoverage in VS Code" />
353-
354-
Integrating the steps of source instrumentation and test harness build into the test execution workflow allows for a quick feedback loop: run a test, observe results and coverage, edit the test or the tested code, repeat... In this context invoking the VS Code commands `Test: Rerun Last Run` and `Test: Rerun Last Run with Coverage` with their respective keyboard shortcuts can be valuable.
355-
356-
### Cross and Embedded Support
357-
358-
This section provides some guidance to work on cross or embedded projects. It assumes
359-
that your `.gpr` project files are already properly configured to work on a cross environments/embedded platforms.
360-
361-
#### GNATemulator Support
362-
363-
If you have loaded an embedded project, the extension will automatically provide predefined tasks and commands
364-
to run and debug your application through GNATemulator, if available for your target.
365-
366-
For instance if you have loaded a project with an `arm-eabi` target configured to run on a STM32F4
367-
board, the extension will provide predefined tasks, commands and CodeLenses to run and debug your
368-
program using GNATemulator.
369-
370-
<img src="doc/media/gnatemu-debug-codelens.gif" width="800" alt="Debug with GNATemulator CodeLens" />
371-
372-
The port used by the debugger launched by VS Code to connect to the running GNATemulator instance
373-
is the one specified via the `Emulator'Debug_Port` project attribute: when not set, the extension
374-
will fallback on `localhost:1234` (GNATemulator's default debug port).
375-
376-
Note that GNATemulator is not available for all GNAT embedded toolchains. For more information about GNATemulator itself and its availabilty please refer to the [GNATemulator User's Guide](https://docs.adacore.com/gnatemulator-docs/gnatemulator.html).
377-
378-
#### Remote Debugging
379-
380-
If your project can be debugged remotely via GDB using the `target remote <ip-of-target:port>` command, you will just need to set the `IDE'Program_Host` project attribute in your `.gpr` file to specify the address that should be used
381-
to connect to your machine or board.
382-
383-
You will also need to run the debugging utility that spawns the remote `gdbserver` before launching the debugger in VS Code ( e.g: `st-util` or `openocd` for STM32F4 boards). This can be done directly through a VS Code `Terminal` or by configuring a custom [VS Code task](https://code.visualstudio.com/docs/editor/tasks) for that purpose.
384-
385-
Once your project is setup, just open the VS Code
386-
`Run and Debug` panel and then click on the `Run and Debug` button.
387-
388-
For more advanced use cases or if your program cannot be debugged remotely via GDB, you can try creating your custom VS Code debug launch configuration following [VS Code User's Guide for Launch Configurations](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations).
389-
390-
### Working with Multiple Projects in the Same VS Code Workspace
391-
392-
It is a possible for a workspace to contain multiple GPR projects.
393-
For example, this is a typical scenario when working with GNATtest which generates (potentially multiple) test harness projects that contain test and stub sources that interface with the application code.
394-
However, only one project can be loaded at a time with the `ada.projectFile` setting.
395-
So you may find yourself switching back and forth between projects which can quickly become cumbersome.
396-
397-
This situation can be improved with [VS Code multi-root workspaces](https://code.visualstudio.com/docs/editing/workspaces/multi-root-workspaces). For example, in a workspace containing `prj1.gpr` and `prj2.gpr` it is possible to define the following two multi-root workspace files:
398-
399-
* `prj1.code-workspace`
400-
401-
```json
402-
{
403-
"folders": [
404-
{
405-
"path": "."
406-
}
407-
],
408-
"settings": {
409-
"ada.projectFile": "prj1.gpr"
410-
}
411-
}
412-
```
413-
414-
* `prj2.code-workspace`
415-
416-
```json
417-
{
418-
"folders": [
419-
{
420-
"path": "."
421-
}
422-
],
423-
"settings": {
424-
"ada.projectFile": "prj2.gpr"
425-
}
426-
}
427-
```
428-
429-
(while the name indicates _multi-root_, we are using a single root folder in each workspace)
430-
431-
Each of these workspaces can be opened in a different VS Code window, allowing to work on both projects side by side.
432-
Alternatively, the root workspace materialized by `.vscode/settings.json` can be kept as the main workspace with `prj1.gpr`, and the other multi-root workspace is created as `prj2.code-workspace` for working with `prj2.gpr`.
433-
434-
In the use case of GNATtest, this allows us to load the main application project in a window and the test harness project in another window, and work on both simultaneously.
435-
436-
Note that a separate Ada Language Server instance is used for each VS Code window, so you might observe high memory consumption in this situation.
437-
438-
### Commands and Shortcuts
439-
440-
The extension contributes commands and a few default key bindings.
441-
Below are a few examples, and other commands can be found by searching for `Ada:` in the command list.
442-
443-
#### Ada: Go to other file
444-
445-
This command switches between specification and implementation Ada files.
446-
The default shortcut is `Alt+O`.
447-
448-
#### Ada: Add subprogram box
449-
450-
This command inserts a comment box before the current subprogram body.
451-
The default shortcut is `Alt+Shift+B`.
452-
453-
#### Ada: Reload project
454-
455-
This command reloads the current project.
456-
The default shortcut is `None`.
457-
458-
#### Tasks with keyboard shortcuts
459-
460-
The following default shortcuts are provided for tasks:
461-
462-
| Task | Shortcut |
463-
|--------------------------------|-----------------|
464-
| `spark: Prove file` | `Meta+Y Meta+F` |
465-
| `spark: Prove subprogram` | `Meta+Y Meta+S` |
466-
| `spark: Prove selected region` | `Meta+Y Meta+R` |
467-
| `spark: Prove line` | `Meta+Y Meta+L` |
468-
469-
`Meta` = ⌘ on macOS, `Win` on Windows, `Meta` on Linux
470-
471-
These shortcuts can be customized and new shortcuts can be added for other tasks by using the command `Preferences: Open Keyboard Shortcuts (JSON)` and adding entries like the following example:
472-
473-
```json
474-
{
475-
"command": "workbench.action.tasks.runTask",
476-
"args": "ada: Check current file",
477-
"key": "meta+y meta+c",
478-
"when": "editorLangId == ada && editorTextFocus"
479-
}
480-
```
481-
482-
### Bug Reporting
483-
484-
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.
485-
486-
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).)
487-
488-
### Limitations and Differences with GNAT Studio
489-
490-
The VS Code extension has a few limitations and some differences compared to [GNAT Studio](https://github.com/AdaCore/gnatstudio):
491-
492-
* **Indentation/formatting**: it does not support automatic indentation when adding a newline and range/document
493-
formatting might no succeed on incomplete/illegal code.
494-
495-
* **Tooling support**: we currently provide support for some *SPARK*, *GNATtest*, *GNATcoverage*, *GNAT SAS* and *GNATemulator* [Tasks](#tasks), but some workflows may not be supported yet.
496-
497-
* **Alire support**: if the root folder contains an `alire.toml` file and
498-
there is `alr` executable in the `PATH`, then the language server fetches
499-
the project's search path, environment variables and the project's file
500-
name from the crate description. [Tasks](#tasks) are also automatically
501-
invoked with Alire in this case.
502-
503-
* **Project support**: there is no `Scenario` view: users should configure scenarios via the *ada.scenarioVariables* setting (see the settings list available [here](doc/settings.md)). Saving the settings file after changing the values will automatically reload the project and update the
504-
predefined tasks to take into account the new scenario values.
505-
506-
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.
139+
See the [Ada & SPARK VS Code Extension User's Guide](doc/vscode-ug.md) for more information.
507140

508141
## Integration with other editors and IDEs
509142

0 commit comments

Comments
 (0)