Skip to content

Commit 5810f56

Browse files
elierichaeliericha
committed
Update the VS Code Ada extension landing page
1 parent caa864f commit 5810f56

File tree

1 file changed

+97
-28
lines changed

1 file changed

+97
-28
lines changed

‎integration/vscode/ada/README.md

Lines changed: 97 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,119 @@
1-
# Ada/SPARK for Visual Studio Code
1+
# Ada & SPARK for Visual Studio Code
22

3+
<!-- markdownlint-disable MD001 -->
34
#### [Repository](https://github.com/AdaCore/ada_language_server)&nbsp;&nbsp;|&nbsp;&nbsp;[Issues](https://github.com/AdaCore/ada_language_server/issues)&nbsp;&nbsp;|&nbsp;&nbsp;[Documentation](https://github.com/AdaCore/ada_language_server/blob/master/integration/vscode/ada/README.md#documentation)&nbsp;&nbsp;|&nbsp;&nbsp;[Code Samples](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/Code%20Samples)&nbsp;&nbsp;|&nbsp;&nbsp;[Tutorial](https://github.com/AdaCore/ada_language_server/wiki/Getting-Started)
45

5-
66
[![Build binaries](https://github.com/AdaCore/ada_language_server/workflows/Build%20binaries/badge.svg)](https://github.com/AdaCore/ada_language_server/actions)
77
[![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/AdaCore/ada_language_server)](https://github.com/AdaCore/ada_language_server/releases)
88
[![VS Marketplace](https://img.shields.io/visual-studio-marketplace/v/adacore.ada?label=VS%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=AdaCore.ada)
99
[![Open VSX Registry](https://img.shields.io/open-vsx/v/AdaCore/ada?label=Open%20VSX)](https://open-vsx.org/extension/AdaCore/ada)
1010
[![Gitpod ready-to-code](https://img.shields.io/badge/Gitpod-ready--to--code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/AdaCore/ada_language_server/tree/edge)
1111

12-
This extension provides support for Ada/SPARK programing language via
13-
[Ada language server](https://github.com/AdaCore/ada_language_server)
14-
which utilizes
15-
[Libadalang library](https://github.com/AdaCore/libadalang).
12+
This extension provides support for the Ada and SPARK programming languages in VS Code via the [Ada Language Server](https://github.com/AdaCore/ada_language_server) based on the [Libadalang library](https://github.com/AdaCore/libadalang).
1613

17-
## Getting started
14+
## Features
1815

19-
### Ada compiler and debugger
20-
The extension does not include an Ada compiler nor debugger. You will need to install these tools or use those already installed on your computer.
16+
Ada and SPARK are compiled languages which means that a compiler is needed to translate the source code into a program that can be executed.
17+
Additionally if your source code uses the SPARK subset of Ada, you can perform formal proof on it using GNATprove.
2118

22-
Popular Ada compilers are:
23-
* [GNAT Community Edition](https://www.adacore.com/download/more)
24-
* GNAT of [GCC](https://gcc.gnu.org/) in a Linux distro. Also install `gprbuild` package.
25-
* GNAT for Windows in [msys2](https://www.msys2.org/). Also install `gprbuild` package.
26-
* [GNAT for Mac OS X](https://sourceforge.net/projects/gnuada/files/GNAT_GCC%20Mac%20OS%20X/)
19+
Even though this extension **does not include a compiler nor a proof tool**, a number of features are available without those tools, and it is easy to obtain them if needed.
2720

28-
Make sure your compiler executable is in your platform path so the extension can find it. You can check availability of your Ada tools by opening the Integrated Terminal (Ctrl+\`) in VS Code and try running the executable (for example `gnatls -v`).
21+
<!-- markdownlint-disable MD033 -->
22+
| | Without<br>Additional Tools | With<br>Ada Compiler | With<br>Ada Compiler & GNATprove |
23+
|---------------------|:------------------------------:|:---------------------:|:---------------------------------:|
24+
| Syntax Highlighting | ✅ | ✅ | ✅ |
25+
| Navigation | ✅<br>(except standard runtime) | ✅ | ✅ |
26+
| Auto-completion | ✅<br>(except standard runtime) | ✅ | ✅ |
27+
| Refactoring | ✅ | ✅ | ✅ |
28+
| Build | | ✅ | ✅ |
29+
| Debug | | ✅ | ✅ |
30+
| Formal Proof | | | ✅ |
2931

30-
### Install the Language Support for Ada extension
32+
## Getting an Ada Compiler or GNATprove
3133

32-
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
34+
For a fully operational development environment you can obtain a compiler and/or GNATprove from the following channels.
3335

34-
ext install AdaCore.ada
36+
### AdaCore Customers
3537

36-
## Documentation
38+
If you are an [AdaCore](https://www.adacore.com/) customer, you can log into your account on [GNAT Tracker](https://support.adacore.com/csm) to download the tools available in your subscription.
39+
40+
### Community Users
41+
42+
The Ada & SPARK tools are available to the community through different channels:
43+
44+
* [ALIRE](https://alire.ada.dev/): The Ada LIbrary Repository provides the means to install compiler [toolchains](https://alire.ada.dev/docs/#toolchain-management).
45+
The `gnatprove` crate provides GNATprove.
46+
Both tools are available for Linux, Windows and macOS.
47+
* On Linux distributions you can use your package manager to install [GCC](https://gcc.gnu.org/) which includes the GNAT Ada compiler.
48+
You also need to install the `gprbuild` package.
49+
* On Windows with [msys2](https://www.msys2.org/) you can install the `gcc` and `gprbuild` packages.
50+
* On macOS you can find GCC releases including GNAT for Intel and Apple silicon at [this project on GitHub](https://github.com/simonjwright/distributing-gcc/releases) courtesy of Simon Wright.
51+
52+
## Environment Setup
53+
54+
The following environment variables influence the operation of the Ada extension:
55+
56+
* `PATH` should include the path to the GNAT compiler installation in order to benefit from auto-completion and navigation into the standard runtime.
57+
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.*`.
58+
59+
* `GPR_PROJECT_PATH` provides paths to other `.gpr` Ada projects that your project depends on.
60+
61+
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.
62+
63+
Alternatively, you can set environment variables through the VS Code Workspace or User setting `terminal.integrated.env.[linux|windows|osx]` depending on your platform.
64+
For example:
65+
66+
```json
67+
{
68+
"terminal.integrated.env.linux": {
69+
"PATH": "/path/to/my/gnat/installation/bin:${env:PATH}",
70+
"GPR_PROJECT_PATH": "/path/to/some-lib-1:/path/to/some-lib-2"
71+
}
72+
}
73+
```
3774

38-
Some useful links:
39-
* [Tutorial: Using Ada in VS Code](https://github.com/AdaCore/ada_language_server/wiki/Getting-Started)
40-
* [Supported refactoring tools](https://github.com/AdaCore/ada_language_server/blob/master/doc/refactoring_tools.md)
41-
* [Custom colors for Ada sources](https://github.com/AdaCore/ada_language_server/wiki/Custom-colors-in-VS-Code)
42-
* [Usage in a Remote container](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/Code%20Samples/docker) example
43-
* Ada Language Server [README.md](https://github.com/AdaCore/ada_language_server/blob/master/README.md)
44-
* [Code Samples](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/Code%20Samples) with Build and Debug tasks
75+
Note that after changes to this VS Code setting, you must run the `Developer: Reload Window` command to apply the changes.
4576

77+
## Settings
78+
79+
This extension can be configured with a set of `ada.*` settings documented [here](https://github.com/AdaCore/ada_language_server/blob/master/doc/settings.md).
80+
81+
The most prominent one is `ada.projectFile` where you can provide the path to the `.gpr` project file.
82+
If no project is provided and if your workspace contains a single project file at the root, then that one will be automatically used.
83+
84+
## VS Code Remote
85+
86+
The Ada extension can be used on a remote workspace over SSH thanks to the [Visual Studio Code Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) extension, however there are known pitfalls regarding the environment setup.
87+
88+
The recommended method for environment setup in a remote configuration is to set the `terminal.integrated.env.*` settings as described in the [Environment Setup](#environment-setup) section.
89+
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.
90+
With this method, changes to the environment can be applied simply with the `Developer: Reload Window` command.
91+
92+
Another method for environment setup is possible.
93+
According to [VS Code documentation](https://code.visualstudio.com/docs/remote/troubleshooting#_configure-the-environment-for-the-remote-extension-host) 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.
94+
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.
95+
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).
96+
97+
## macOS and Apple Silicon
98+
99+
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](https://support.apple.com/en-us/HT211861).
100+
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:
101+
102+
```ada
103+
for Target use "aarch64-darwin";
104+
```
105+
106+
If you encounter issues with the compiler on macOS, it is recommended to consult known issues at Simon Wright's [GitHub project](https://github.com/simonjwright/distributing-gcc/issues) and discussions on the [comp.lang.ada](https://groups.google.com/g/comp.lang.ada) group.
107+
108+
## Documentation
46109

47-
## Feedback and Known Issues
110+
* [Ada Language Server README.md: VS Code Extension](https://github.com/AdaCore/ada_language_server/blob/master/README.md#vs-code-extension)
111+
* [Tutorial: Using Ada in VS Code](https://github.com/AdaCore/ada_language_server/wiki/Getting-Started)
112+
* [Supported refactoring tools](https://github.com/AdaCore/ada_language_server/blob/master/doc/refactoring_tools.md)
113+
* [Custom colors for Ada sources](https://github.com/AdaCore/ada_language_server/wiki/Custom-colors-in-VS-Code)
114+
* [Usage in a Remote container](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/Code%20Samples/docker) example
115+
* [Code Samples](https://github.com/AdaCore/ada_language_server/tree/master/integration/vscode/Code%20Samples) with Build and Debug tasks
48116

49-
File a bug or see known issues [at github](https://github.com/AdaCore/ada_language_server/issues/).
117+
## Known Issues and Feedback
50118

119+
You can browse known issues and report bugs at the [Ada Language Server](https://github.com/AdaCore/ada_language_server/issues/) GitHub project.

0 commit comments

Comments
 (0)