Skip to content

AdaCore/ada_language_server

BranchesTags

Repository files navigation

Ada Language Server

Build binaries GitHub tag (latest by date) VS Marketplace Open VSX Registry Gitpod ready-to-code

This repository contains an implementation of the Microsoft Language Server Protocol for Ada/SPARK and GPR project files.

Current features (general):

For Ada/SPARK, we provide the following:

  • Code completion for names, keywords, aggregates, etc.
  • Code navigation, such as Go to Definition/Declaration, Find All References, Call Hierarchies, etc.
  • Code refactoring like insert named associations, auto-add with-clauses, etc.
  • Document/Workspace symbol search.
  • Code folding and formatting.

The Ada Language Server now also supports the GPR language, via the --language-gpr option, providing support for the most used LSP features such as navigation, outline and tooltips for GPR files. When this switch is present, the server will only support GPR files. To support both GPR and Ada/SPARK, you'll need to launch two instances of the server. You can refer to the Supported LSP Server Requests section for more information.

We also provide Visual Studio Code extension at the VS Marketplace and at the Open VSX Registry.

Table of Contents

Install

The official releases contains ready-built packages for various platforms and architectures and should be your first choice when trying out the language server.

You can also build the language server from source. See build.md for details.

Usage

The ada_language_server doesn't require any command line options, but it understands these options:

  • --tracefile=<FILE> - Full path to a file containing traces configuration
  • --config=<FILE> - Full path to a JSON file containing the server's configuration
  • --help - Display supported command like options and exit.

You can turn some debugging and experimental features through the traces file.

The server also gets configuration via workspace/didChangeConfiguration notification and initializationOptions of initialize request. See more details here. Each LSP client provides its-own way to set such settings. You can use the --config option if you want to provide the configuration directly via a JSON file instead of specifying it via the requests listed just above.

Memory Consumption

The ada_language_server relies on Libadalang to compute the cross references. Most of this computation is done while indexing which will create an internal cache. The expected memory size of this cache is around 300Mb per 100k lines of Ada code. Furthermore, 450Mb are necessary for the runtime. Please note that some Ada structures like generics and tagged types might increase the memory usage. This is also the case when using aggregate projects. These measures were taken using both Resident Set Size and Valgrind massif on Ubuntu 22.04LTS.

Supported LSP Server Requests

See WiKi page for the list of supported requests.

Protocol Extensions

The Ada Language Server supports some features that are not in the official Language Server Protocol specification. See corresponding document.

VS Code Extension

A VS Code extension based on this Ada Language Server is available on the Visual Studio Marketplace. It provides a full set of features including syntax highlighting, navigation, building and debugging.

Getting Started

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

Configuration

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

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
}

Refactoring

See a dedicated document with the list of available refactorings.

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.

GNATtest Test Results

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.

Ada & SPARK Status Bar Item

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.

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.

    GNATtest Test Tree

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

    GNATtest Test Results

GNATtest support has the following known limitations:

  • The extension relies on the default conventions of GNATtest such as the naming, location and object directory of the test harness project. If those aspects are configured or altered manually, the features may no longer work.

  • Language support such as navigation and auto-completion is limited when editing test sources. A workaround is to modify the ada.projectFile setting to point to the test harness project created by GNATtest. That should restore language support when developing tests.

  • 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:

  1. Instruct GNATcoverage to produce an XML report
  2. Invoke the VS Code command ada: GNATcoverage - Load an existing XML coverage report
  3. Browse to the location of the GNATcoverage XML report and select the index.xml file

GNATcoverage report in VS Code

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.

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

  1. Run the task ada: GNATcoverage - Setup runtime library once to set up the GNATcoverage runtime library
  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
  3. Switch to the Test Explorer view or use the Testing: Focus on Test Explorer View command to do that
  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.
  5. 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

GNATtest with GNATcoverage in 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.

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.

Debug with GNATemulator CodeLens

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 setup, 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.

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"
}

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.

  • Tooling support: we currently provide support for some SPARK, GNATtest, GNATcoverage, GNAT SAS 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: there is no Scenario view: users should configure scenarios via the ada.scenarioVariables setting (see the settings list available here). Saving the settings file after changing the values will automatically reload the project and update the predefined tasks to take into account the new scenario values.

    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.

Integration with other editors and IDEs

Integration with Coc.NVim

If you want to use the Ada Language Server with Vim/Neovim, you can use the Coc.NVim. You'll have to install the Ada Language Server manually somewhere on your computer. Follow installation instructions on Coc.NVim website and then configure the Ada Language Server with :CocConfig:

{
  "languageserver": {
    "ada": {
      "settings": {
        "ada": {
          "projectFile": "gnat/vss_text.gpr"
        }
      },
      "command": "<path>/ada_language_server",
      "filetypes": [
        "ads",
        "adb",
        "ada"
      ]
    }
  }
}

Alternatively to the above settings section, workspace-specific ALS Settings such as the projectFile can be provided in a .als.json file at the root of the workspace.

Integration with vim-lsp

If you want to integrate the Ada Language Server into vim, you can use the vim-lsp.

You'll have to install the Ada Language Server manually somewhere on your computer, and then you can add the following line to your .vimrc file:

if executable('ada_language_server')
    au User lsp_setup call lsp#register_server({
        \ 'name': 'ada_language_server',
        \ 'cmd': ['ada_language_server'],
        \ 'allowlist': ['ada'],
        \ })
endif

Workspace-specific ALS Settings such as the projectFile can be provided in a .als.json file at the root of the workspace.

Integration with LanguageClient-Neovim

If you want to integrate the Ada Language Server into Neovim, you can use the LanguageClient-neovim.

You'll have to install the Ada Language Server manually somewhere on your computer, and then you can add the following line to your init.vim file:

" replace the path below with the proper path to the ada_language_server executable
let g:LanguageClient_serverCommands = {
    \ 'ada': ['path/to/ada_language_server'],
    \ }
" if you already have LanguageClient_serverCommands, just add a line for ada.

Workspace-specific ALS Settings such as the projectFile can be provided in a .als.json file at the root of the workspace.

Integration with Neovim's built-in LSP client

Neovim 0.5.0 and later have a built-in LSP client which can be used with the Ada Language Server. In order to use it with minimal effort, follow these steps:

  • Install the ada language server and make sure it's in your $PATH.
  • Use your favorite Neovim plugin manager to add the default set of LSP configuration files to Neovim.
  • Add require('lspconfig').ada_ls.setup{} to your init.lua in order to enable the Ada Language Server.

If you would rather not have the ada language server in your path, you can give the lsp client an absolute path to the ALS executable:

require('lspconfig').ada_ls.setup{ cmd = "/path/to/als/executable" }

Configuring the language server's settings globally can be achieved like this:

require('lspconfig').ada_ls.setup{
  settings = {
    ada = {
      projectFile = "project.gpr";
      scenarioVariables = { ... };
    }
  }
}

Workspace-specific ALS Settings such as the projectFile can be provided in a .als.json file at the root of the workspace.

Alternatively, workspace-specific settings can also be configured as per the lspconfig wiki

Integration with emacs lsp-mode

Workspace-specific ALS Settings such as the projectFile can be provided in a .als.json file at the root of the workspace.

Alternatively the configuration for each project can be provided using a .dir-locals.el file defined at the root of each project.

The scenario variables should be declared in your .emacs or any loaded Emacs configuration file.

(defgroup project-build nil
  "LSP options for Project"
  :group 'ada-mode)

(defcustom project-build-type "Debug"
  "Controls the type of build of a project.
   Default is Debug, other choices are Release and Coverage."
  :type '(choice
          (const "Debug")
          (const "Coverage")
          (const "Release"))
  :group 'project-build)

Your .dir-locals.el in the project root should be similar to:

((ada-mode .
  ((eval . (lsp-register-custom-settings
      '(("ada.scenarioVariables.BINUTILS_SRC_DIR" project-binutils-dir)
        ("ada.scenarioVariables.BUILD_TYPE" project-build-type "Release"))))
   (lsp-ada-project-file . "/home/username/project/project.gpr"))
  ))

The lsp-mode provides built-in support for the ada_language_server and defines default customizable configuration values in the lsp-ada group that can be edited similarly to lsp-ada-project-file in the example above.

Integration with QtCreator

Starting with version 4.9, QtCreator supports a LSP plugin. Follow the official documentation to configure the Ada Language Server in this plugin. Make sure to set Startup behavior to Start Server per Project, otherwise QtCreator won't provide the project root to the Ada Language Server.

Workspace-specific ALS Settings such as the projectFile can be provided in a .als.json file at the root of the workspace.

Refactoring Tools

See corresponding document.

Authors & Contributors

  • Maintained by AdaCore.
  • Original author @MaximReznik.
  • Support for the Visual Studio Code classifier and snippets contributed by @Entomy.

Contribute

Feel free to dive in! Read the developer's guide.

Don't hesitate to open an issue or submit PRs.

License

GPL-3

About

Server implementing the Microsoft Language Protocol for Ada and SPARK

Resources

Readme

License

GPL-3.0 license

Code of conduct

Code of conduct
Activity
Custom properties

Stars

269 stars

Watchers

35 watching

Forks

67 forks
Report repository

Releases 31

26.0.202507021 Latest
Jul 10, 2025
+ 30 releases

Packages

No packages published

Contributors 34

+ 20 contributors

Languages