Ada & SPARK VS Code Extension User's Guide

This extension provides support for the Ada and SPARK programming languages in VS Code via the Ada Language Server based on the Libadalang library.

Features

Ada and SPARK are compiled languages which means that a compiler (GNAT) is needed to translate the source code into a program that can be executed. Other tools are also needed to perform tasks such as testing, static analysis and formal proof of SPARK code.

This extension does not include a compiler nor additional tools. Nonetheless it offers a number of features out of the box and more capabilities can be accessed by installing additional tools.

Tool	Feature	Support
Ada & SPARK Extension
	Syntax Highlighting	✅
	Navigation (except standard runtime)	✅
	Auto-completion (except standard runtime)	✅
	Refactoring	✅
GNAT Compiler
	Full Navigation	✅
	Full Auto-completion	✅
	Build	✅
	Debug	✅
GNAT DAS
	Test	✅
	Code Coverage	✅
GNAT SAS
	Static Analysis	✅
	Metrics	✅
SPARK
	Formal Proof	✅

Getting Started

Here are some links that will help you get familiar with the VS Code extension for Ada & SPARK:

Tutorial: Using Ada in VS Code.

Environment Setup

The following environment variables influence the operation of the Ada extension:

PATH should include the path to the GNAT compiler installation in order to benefit from auto-completion and navigation into the standard runtime. Without it, auto-completion and navigation will work only on the sources visible in the project closure, but not on the packages of the standard library Ada.*.
GPR_PROJECT_PATH provides paths to other .gpr Ada projects that your project depends on.

When running VS Code locally, you can provide these environment variables by exporting them in a terminal, and starting VS Code from that same terminal with the code command.

If you are running VS Code to develop on a remote machine, please refer to the dedicated section to setup your environment properly.

Configuration

ALS settings can be specified in various ways. For example:

A .als.json file at the root of the workspace.
A global user configuration file $HOME/.config/als/config.json
The .vscode/settings.json VS Code workspace settings file.
A multi-root VS Code workspace file
The User or Remote or other VS Code scopes of of settings

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.

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.):

{
   "projectFile": "gnatcov.gpr",
   "scenarioVariables": {
      "BINUTILS_BUILD_DIR": "/null",
      "BINUTILS_SRC_DIR": "/null"
   },
   "defaultCharset": "utf-8",
   "adaFileDiagnostics": false,
   "renameInComments": false
}

Alternatively, the ALS can be configured in the VS Code settings UI or in the JSON settings files. For example:

{
   "ada.projectFile": "gnatcov.gpr",
   "ada.scenarioVariables": {
      "BINUTILS_BUILD_DIR": "/null",
      "BINUTILS_SRC_DIR": "/null"
   },
   "ada.defaultCharset": "utf-8",
   "ada.adaFileDiagnostics": false,
   "ada.renameInComments": false
}

VS Code Remote

The Ada extension can be used on a remote workspace over SSH thanks to the Visual Studio Code Remote - SSH extension, however there are known pitfalls regarding the environment setup.

The recommended method for environment setup in a remote configuration is to set the terminal.integrated.env.* settings. You can set environment variables through the VS Code Workspace or User setting terminal.integrated.env.[linux|windows|osx] depending on your platform. For example:

{
  "terminal.integrated.env.linux": {
    "PATH": "/path/to/my/gnat/installation/bin:${env:PATH}",
    "GPR_PROJECT_PATH": "/path/to/some-lib-1:/path/to/some-lib-2"
  }
}

Note that after changing this VS Code setting, the extension will display a popup asking you to reload the current window to take the environment changes into account. You can still run the Developer: Reload Window command manually to apply the changes later on.

In addition to Workspace and User settings, the Remote settings file can also be used to set the terminal.integrated.env.* settings, with standard precedence rules applying between the different setting scopes. With this method, changes to the environment can be applied simply with the Developer: Reload Window command.

Another method for environment setup is possible. According to VS Code documentation the environment of the remote extension host is based on the default shell configuration scripts such as ~/.bashrc so it is possible to provide your toolchain and project environment setup in your default shell configuration script. However to make changes to that environment the typical Developer: Reload Window command is not enough and it is necessary to fully restart the VS Code server. To do that you must close all VS Code Remote windows, and kill all VS Code server processes on the server (e.g. killall node if no other node processes are used on the server).

Tasks

The extension provides a number of auto-detected tasks under the /Terminal/Run Task... menu. These predefined tasks are all prefixed by ada: and belong to the ada group. 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. Most of these tools are integrated using SARIF, a standard interchange format that can be easily parsed and displayed using the third-party SARIF Viewer extension. The SARIF Viewer extension also supports SARIF fixes as VS Code Actions, so tools that emit them will have their fixes available as quick fixes directly in the editor and the Problems View.

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

{
  "key": "alt+v",
  "command": "workbench.action.tasks.runTask",
  "args": "ada: Check current file",
  "when": "editorLangId == ada"
}

Task Customization

You can customize auto-detected tasks by providing extra tool command line options via the args property of the object in the tasks.json:

{
   "version": "2.0.0",
   "tasks": [
      {
         "type": "ada",
         "command": "gprbuild",
         "args": [
            "${command:ada.gprProjectArgs}",
            "-cargs:ada",
            "-gnatef",
            "-gargs",
            "-vh"
         ],
         "problemMatcher": ["$ada-error", "$ada-warning", "$ada-info"],
         "group": "build",
         "label": "ada: Build current project"
      }
   ]
}

You can also customize the working directory of the task or the environment variables via the options property:

{
   "version": "2.0.0",
   "tasks": [
      {
         "type": "ada",
         "command": "gprbuild",
         "args": [
            "${command:ada.gprProjectArgs}",
            "-cargs:ada",
            "-gnatef"
         ],
         "options": {
            "cwd": "${workspaceFolder}/my/subdir",
            "env": {
               "MY_ENV_VAR": "value"
            }
         },
         "problemMatcher": ["$ada-error", "$ada-warning", "$ada-info"],
         "group": "build",
         "label": "ada: Build current project"
      }
   ]
}

Tasks for Project Mains

If your GPR project defines main programs via the project attribute Main, additional tasks are automatically provided for each defined main. 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:

ada: Build main - src/main1.adb
ada: Run main - src/main1.adb

Same thing for all the predefined tasks that can have a main specified in their command line.

Status Bar

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.

Project View

The Ada & SPARK extension contributes a Project view in the VS Code Explorer sidebar. It shows the structure of the loaded GPR project as a tree, grouping source files by their project and source directory.

The Project view also exposes a toolbar with the following buttons:

Filter — filters the tree view to show only projects, directories, and files whose names contain the filter string.
Open Project... — opens a dialog to select a new GPR project file to load.
Refresh — reloads the project and updates the tree view.
View Options — toggles the display of object directories and runtime files, and allows to switch between flat and hierarchical view modes.

Tree Structure

The tree reflects the GPR project hierarchy:

Root project — the top-level .gpr project file.
Sub-projects — projects imported, aggregated, or extended by the root project, shown as children.
Source directories — each project's source directories are shown as folder nodes. Directories declared in the project file are always shown, even when empty.
Source files — source files are listed under their containing directory. Clicking a file opens it in the editor.
Object directory — optionally displayed under each project (see View Options below).
Runtime project — optionally shown at the bottom of the tree, listing the GNAT runtime source files (see View Options below).

Navigation

Reveal Active File (Ada: Reveal in Project View) — locates and selects the currently open editor file in the Project view tree. This command is also available as an editor context menu.
Go to File in Project (Ada: Go to File in Project..., Ctrl+Alt+P / Cmd+Alt+P on macOS) — opens a quick-pick search restricted to the source files of the loaded GPR project, and opens the selected file in the editor. Unlike the native Go to File... command, it lists exactly the files that the project declares, including sources located outside the workspace folders, and excluding files that do not belong to the project. Type part of a file name, of a directory, or of a project name to narrow the list; each entry also offers a button to reveal the file in the Project view tree. The command is available from the Command Palette and from the Project view toolbar. Runtime sources are listed only when the ada.projectView.showRuntimeFiles setting is enabled. Note that Ctrl+Alt+P coincides with AltGr+P on some keyboard layouts; the shortcut can be changed from Preferences: Open Keyboard Shortcuts.
Reveal in Explorer — available via right-click on a source file or a project file node; opens the VS Code Explorer and selects the item there.

File Management

Source files can be moved between source directories by dragging them from one directory node and dropping them onto another. A confirmation dialog is shown before any move is performed, and name collisions are detected and reported.

Filtering

The Project view toolbar provides a filter button (funnel icon). When active, only projects, directories, and files whose names contain the filter string are shown. Clear the filter by clicking the filled funnel icon that replaces it.

View Options

Click the View Options button (···) in the Project view toolbar to toggle the following display settings:

Option	Setting	Description
Flat Mode	`ada.projectView.flatMode`	Show all projects as a flat list rather than a hierarchy
Show Object directories	`ada.projectView.showObjectDirectories`	Show each project's object directory
Show Runtime files	`ada.projectView.showRuntimeFiles`	Show GNAT runtime source files

These options can also be set permanently via the corresponding VS Code settings.

Context Menu Commands

Right-clicking a node in the Project view exposes additional commands:

Show File Dependencies Graph — opens an interactive graph of Ada file dependencies for the selected file. Only available for source files.
Show GPR Dependencies Graph — opens an interactive graph of GPR project dependencies. Only available for GPR project files.

Project file items also have a context menu with commands to build, analyze, and clean the project, among others.

Scenario View

The Ada & SPARK extension contributes a Scenario view in the VS Code Explorer sidebar, next to the Project view. It lists the scenario (external) variables declared in the loaded project tree, along with each variable's currently resolved value.

Resolved Values

A variable's resolved value comes from whichever of the ada.scenarioVariables setting, the .als.json file, or the OS environment sets it; a variable with no resolved value is shown as (default), and its value is what is defined in the project file.

If the same variable is declared with conflicting types across the project tree, it is shown with a warning icon and an explanatory tooltip.

Editing Values

Clicking a variable, or using its Edit Value… action, opens a picker showing to possible values for typed variables, or a free-text input box otherwise. Picking a value writes it, together with every other variable's currently resolved value, to the ada.scenarioVariables setting (see the settings list). This automatically reloads the project and updates the predefined Tasks to take the new scenario values into account, exactly as if the setting had been selected manually.

A Reset to Default action is available for any variable that currently has a resolved value. Calling it clears the variable from the ada.scenarioVariables setting associated with the Workspace; if the variable is still resolved afterwards, for example because it is also set at the User or Remote scope, that value takes effect instead of falling back to .als.json, the environment, or the project's default value.

Alire Support

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.

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.

All other tasks use alr exec -- ... to execute the command in the environment provided by Alire.

Code Visualizer

The Ada & SPARK VS Code extension can display your code structure as interactive graphs. These graphs help you understand relationships in your codebase by using Language Server Protocol (LSP) requests.

Available Graph Types

The extension provides four types of interactive graphs:

For all languages with Language Server support:

Calls: Show Call Hierarchy Graph - Shows how functions call each other in your project
Types: Show Type Hierarchy Graph - Shows relationships between different data types

Specific to Ada and GPR files:

Ada: Show File Dependencies Graph - Shows how Ada source files depend on each other
Ada: Show GPR Dependencies Graph - Shows relationships between GPR project files

How to Use

To create a graph:

Right-click on a function, type, or anywhere in an Ada/GPR file
Select the appropriate "Show ... Graph" command from the context menu
An interactive graph opens in a new tab where you can:
- Move nodes around by dragging
- Zoom in and out
- Expand or collapse parts of the graph
- Navigate directly to your code

For detailed instructions and advanced features, see the complete documentation.

GNATtest Support

If you install GNATtest, the Ada & SPARK extension for VS Code will provide the following functionalities:

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.
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.
Tests created with GNATtest will be loaded in the VS Code Testing view as follows.
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.
Test execution always starts by executing the ada: Build GNATtest test harness project task to make sure that test executables are up to date.
Test execution results are reflected in the test tree.

Using multi-root workspaces for test development

When developing tests, it is recommended to use the test harness project auto-generated by GNATtest. You can do so by editing the ada.projectFile setting to point to the test harness project. However to avoid switching back and forth between the main application project and the test harness project, see Working with Multiple Projects in the Same VS Code Workspace for instructions on opening the test harness project in a separate VS Code window.

Limitations

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...). This limitation is planned to be lifted.
Sections of test sources delimited by begin read only and end read only comments are not really protected from inadvertant edits. To ensure proper interactions with GNATtest, you must refrain from making edits in those sections.

GNATcoverage Support

GNATcoverage coverage reports can be imported in VS Code as follows:

Instruct GNATcoverage to produce an XML report or a Cobertura report
Invoke the VS Code command ada: GNATcoverage - Load an existing coverage report
Browse to and select the report file:
- For the GNATcoverage XML format: select the index.xml file
- For the Cobertura format: select the Cobertura XML file

The format is detected automatically from the file contents.

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.

Since VS Code does not support reporting MC/DC level coverage natively, that information is imported as branch coverage.

The GNATtest integration in VS Code also supports running tests in coverage mode, if GNATcoverage is installed on the development machine.

Run the task ada: GNATcoverage - Setup runtime library once to set up the GNATcoverage runtime library
If you don't already have a test harness project created, use the task ada: Create or update GNATtest test framework to create one
Switch to the Test Explorer view or use the Testing: Focus on Test Explorer View command to do that
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.
In one go, VS Code will:
1. Invoke GNATcoverage source instrumentation
2. Build the test harness project
3. Run the tests
4. Invoke GNATcoverage source coverage analysis
5. Load the GNATcoverage report into VS Code

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.

Running GNATcoverage Analysis on a Main

As an alternative to running tests in coverage mode via the Test Explorer, the Ada: Run GNATcoverage analysis... command (also available from the editor toolbar, via the run-coverage icon) runs the full instrumentation-based coverage workflow directly on a Main you pick from the list of Mains defined in the project:

Instrument the project
Build the instrumented project
Run the Main
Generate the coverage report, in the project's object directory

As with the GNATtest integration, run the task ada: GNATcoverage - Setup runtime library once beforehand to set up the GNATcoverage runtime library. If the instrumented project fails to build, VS Code prompts to run that setup task, since a missing or outdated runtime library is a common cause of failure.

Unlike the GNATtest integration, the resulting report is not loaded into VS Code automatically: use the ada: GNATcoverage - Load an existing coverage report command described above to visualize it.

Each step is also available as an individual task (ada: GNATcoverage - Instrument project, ada: GNATcoverage - Build instrumented project, ada: GNATcoverage - Generate report - <main>), so the workflow can be customized or run step by step if needed. See Task Customization.

GNAT Metrics Support

The extension provides a predefined task called Compute metrics for current file, which runs gnatmetric and displays file metrics directly in the editor using CodeLenses.

By default, the displayed metrics include code complexity and lines of code. You can customize which metrics are shown by adjusting the command-line options for gnatmetric in the task configuration.

You can configure thresholds for specific metrics to highlight when they are exceeded via the ada.metricThresholds VS Code setting. The extension will display warning or error diagnostics for each violation, and the corresponding CodeLenses will show warning or error icons as appropriate.

While VS Code doesn’t natively support running a task on file save, external extensions can enable this behavior. This is a convenient way to keep the metrics up to date, ensuring they are recomputed each time the code is modified.

Cross and Embedded Support

This section provides some guidance to work on cross or embedded projects. It assumes that your .gpr project files are already properly configured to work on a cross environments/embedded platforms.

GNATemulator Support

If you have loaded an embedded project, the extension will automatically provide predefined tasks and commands to run and debug your application through GNATemulator, if available for your target.

For instance if you have loaded a project with an arm-eabi target configured to run on a STM32F4 board, the extension will provide predefined tasks, commands and CodeLenses to run and debug your program using GNATemulator.

The port used by the debugger launched by VS Code to connect to the running GNATemulator instance is the one specified via the Emulator'Debug_Port project attribute: when not set, the extension will fallback on localhost:1234 (GNATemulator's default debug port).

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.

Remote Debugging

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 to connect to your machine or board.

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 for that purpose.

Once your project is set up, just open the VS Code Run and Debug panel and then click on the Run and Debug button.

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.

GNAT SAS

To learn more about using GNAT SAS with VS Code, consult the GNAT SAS User's Guide, which contains a comprehensive section on this topic.

SPARK Support

When working on a project with SPARK code, it is possible to call GNATprove through the following commands:

SPARK: Examine project
SPARK: Examine file
SPARK: Examine subprogram
SPARK: Prove project
SPARK: Prove file
SPARK: Prove subprogram
SPARK: Prove selected region
SPARK: Prove line

These commands open an interactive picker to choose options before calling GNATprove.

It is also possible to call the options picker directly with the command SPARK: Select GNATprove options....

If you prefer to invoke GNATprove without choosing options interactively, the Tasks: Run Task command offer non-interactive task counterparts of the above commands.

Starting GNATprove 26, a SARIF report is generated and opened automatically in VS Code after execution.

Working with Multiple Projects in the Same VS Code Workspace

It is a possible for a workspace to contain multiple GPR projects. 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. However, only one project can be loaded at a time with the ada.projectFile setting. So you may find yourself switching back and forth between projects which can quickly become cumbersome.

This situation can be improved with VS Code 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:

prj1.code-workspace

{
  "folders": [
    {
      "path": "."
    }
  ],
  "settings": {
    "ada.projectFile": "prj1.gpr"
  }
}

prj2.code-workspace

{
  "folders": [
    {
      "path": "."
    }
  ],
  "settings": {
    "ada.projectFile": "prj2.gpr"
  }
}

(while the name indicates multi-root, we are using a single root folder in each workspace)

Each of these workspaces can be opened in a different VS Code window, allowing to work on both projects side by side. 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.

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.

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.

Important: Path Resolution in Multi-Root Workspaces

When using a single multi-root workspace definition with multiple folders (without separate .code-workspace files for each folder), be aware that:

Relative paths in ada.projectFile are resolved from the first workspace folder listed in the workspace definition
To reference projects in other folders, use one of these approaches:
1. Use absolute paths in ada.projectFile
2. Use per-folder .als.json files in each project directory (recommended for version control)
3. Use the pattern described above with separate .code-workspace files for each project

Commands and Shortcuts

The extension contributes commands and a few default key bindings. Below are a few examples, and other commands can be found by searching for Ada: in the command list.

Ada: Go to other file

This command switches between specification and implementation Ada files. The default shortcut is Alt+O.

Ada: Add subprogram box

This command inserts a comment box before the current subprogram body. The default shortcut is Alt+Shift+B.

Ada: Reload project

This command reloads the current project. The default shortcut is None.

Tasks with keyboard shortcuts

The following default shortcuts are provided for tasks:

Task	Shortcut
`spark: Prove file`	`Meta+Y Meta+F`
`spark: Prove subprogram`	`Meta+Y Meta+S`
`spark: Prove selected region`	`Meta+Y Meta+R`
`spark: Prove line`	`Meta+Y Meta+L`

Meta = ⌘ on macOS, Win on Windows, Meta on Linux

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:

{
    "command": "workbench.action.tasks.runTask",
    "args": "ada: Check current file",
    "key": "meta+y meta+c",
    "when": "editorLangId == ada && editorTextFocus"
}

Navigating references

Navigating references is entirely handled by VS Code itself: the extension only provides the underlying language server requests. The commands below are therefore the standard ones, contributed by the Reference Search View extension that is built into VS Code, and they work in Ada files as in any other language.

They are not available in GPR files: the GPR language server does not implement reference lookup nor the call and type hierarchies, so VS Code disables these commands in a .gpr editor. Go to Definition and Go to Declaration are supported there and remain the way to navigate a project file.

Results are displayed in the References view, which sits in the Activity Bar and appears as soon as a search is run.

Command	Shortcut	Description
`References: Find All References`	`Shift+Alt+F12`, and `Shift+F12` (see below)	Lists the references to the entity under the cursor in the `References` view
`Go to References`	`Shift+F12` in other languages (see below)	Shows the references to the entity under the cursor in the editor's peek widget
`Go to Next Reference`	`F4`	Moves to the next result of the current search
`Go to Previous Reference`	`Shift+F4`	Moves to the previous result of the current search
`References: Show History`	`None` (see below)	Runs one of the reference searches previously made in the same window again
`Calls: Show Call Hierarchy`	`Shift+Alt+H`	Displays the callers of the entity under the cursor in the same view
`Types: Show Type Hierarchy`	`None`	Displays the type hierarchy of the entity under the cursor in the same view
`Go Back`	`Ctrl+Alt+-` (`Ctrl+-` on macOS)	Returns to the previous location in the editor navigation history
`Go Forward`	`Ctrl+Shift+-`	Moves forward again in the editor navigation history

A word of warning about the Command Palette, which hides some of these commands on purpose: Go to Next Reference and Go to Previous Reference are never listed there and are reachable only through F4 / Shift+F4, and References: Show History is listed only once a search has been run — see Going back to a previous search below.

Going back to a previous search

The References view holds one search at a time: running a new search replaces its contents, just as VS Code's Search view does. It does however remember the searches made in the current window, and there are two ways back to them.

The first needs nothing but the view itself, and is the one to prefer because it is always available: press the Clear button in the view's title bar. The results are then replaced by the history — under the message No results. Try running a previous search again: — and any entry can be clicked, or its Rerun button pressed, to return to it.

The second is the References: Show History command, which opens a quick pick titled Select previous reference search. Note that VS Code lists this command in the Command Palette only once a reference search has been run in the current window.

The command has no default key binding, but the Preferences: Open Keyboard Shortcuts (JSON) editor lists it regardless of the condition above, so those who would rather not go through the Command Palette can give it one — for instance:

{
    "command": "references-view.pickFromHistory",
    "key": "meta+y meta+h"
}

In both cases the search is run again rather than restored from a cache, so its results reflect the current state of the sources. And the history is kept in memory only: it is lost when the window is closed or reloaded, and References: Clear History — offered in the view's title bar once the results have been cleared — discards it explicitly.

Peek widget or view?

VS Code has two presentations for reference searches: the transient peek widget displayed in the editor, whose contents are discarded as soon as it is closed, and the persistent References view described above, which is the only one of the two to keep a history. Which of the two you get depends on the command invoked, and on nothing else:

References: Find All References always fills the view. In Ada files the extension binds it to Shift+F12, so that the customary shortcut lands in the view rather than in the peek widget; elsewhere Shift+F12 keeps its standard meaning of Go to References.
Go to References, and Peek > Peek References — also reachable by holding Ctrl and clicking an entity — always open the peek widget, and leave the References view and its history untouched.

To restore the stock VS Code behaviour, remove the key binding with the command Preferences: Open Keyboard Shortcuts (JSON) and an entry like the following:

{
    "command": "-references-view.findReferences",
    "key": "shift+f12",
    "when": "editorHasReferenceProvider && editorTextFocus && editorLangId == ada"
}

macOS and Apple Silicon

On macOS with Apple silicon it is possible to use either the native aarch64 version of the GNAT compiler or the x86_64 version running seamlessly with Rosetta. If you are using the aarch64 version, as this is still a relatively new platform for Ada tools, it is necessary to set the following attribute in your main project file to obtain navigation and auto-completion functionalities on the standard runtime:

for Target use "aarch64-darwin";

If you encounter issues with the compiler on macOS, it is recommended to consult known issues at Simon Wright's GitHub project and discussions on the comp.lang.ada group.

Bug Reporting

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 repository.

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.)

Limitations and Differences with GNAT Studio

The VS Code extension has a few limitations and some differences compared to GNAT Studio:

Indentation/formatting: it does not support automatic indentation when adding a newline and range/document formatting might no succeed on incomplete/illegal code.
References and call trees: GNAT Studio's Find All References and Call Trees views are replaced by VS Code's single References view, which also hosts the call and type hierarchies, described in Navigating references, and by the graphs of the Code Visualizer. Two differences are worth noting. First, the References view displays a single search at a time: where GNAT Studio accumulates searches side by side, VS Code replaces the results on every new search and merely keeps a list of the previous ones, which have to be run again to be consulted; that list is moreover only kept for the lifetime of the window. Second, the Code Visualizer graphs are re-rooted on the entity of each new request instead of growing as GNAT Studio's call trees do.
Tooling support: we currently provide support for some SPARK, GNATtest, GNATcoverage, GNAT SAS, GNATmetric and GNATemulator Tasks, but some workflows may not be supported yet.
Alire support: if the root folder contains an alire.toml file and there is alr executable in the PATH, then the language server fetches the project's search path, environment variables and the project's file name from the crate description. Tasks are also automatically invoked with Alire in this case.
Project support: the Scenario view lets you inspect and edit the scenario (external) variables of the loaded project tree.

Source directories from imported projects should be added in a workspace file. 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.

FilesExpand file tree

vscode-ug.md

Latest commit

History