Eclipse CDT LSP - LSP based C/C++ Editor

Target audience are Eclipse plugin developers who want to use/develop a LSP based C/C++ Editor.

This plugin is based on the LSP4E and TM4E Eclipse projects. The editor is based on the ExtensionBasedTextEditor in Eclipse.

The org.eclipse.cdt.lsp is the core plugin. C/C++ IDE Developers can use the serverProvider extension point to define a C/C++ language server. If there is no extension defined, the LLVM clangd language server will be used and searched on the PATH environment variable. Clangd searches for a compile_commands.json file in the source file folder and its parents. It's needed to determine the compile informations. In the default clangd configuration, the PATH will be searched for a gcc compiler to determine the default compiler include paths.

The editor is basically the ExtensionBasedTextEditor. The language grammar comes from TM4E.

The Editors features depends on the support on client (LSP4E) and server (clangd) side. Currently these feature are supported (clangd 15 and 16) and current LSP4E:

• Auto completion
• Hovering
• Formatting
• Go to Declaration
• Find References
• Code actions (Declare implicit copy/move members, Extract to function/variable, rename)
• Quick Fix (Ctrl+1)
• Type hierarchy
• Call hierarchy
• Outline view

Not supported (yet):

• Include browser (Eclipse CDT speciality)

Activating LSP based C/C++ Editor

The org.eclipse.cdt.lsp.clangd plugin provides an activation UI for the LSP based C/C++ Editor on project and workspace level. The clangd language server path and the arguments can be changed in the workspace preferences as well:

Newly created C/C++ projects will use the settings from the workspace preferences. This can be changed in the project properties:

Different C/C++ projects using the old and new C/C++ editor can be mixed in one workspace. The linked include files will be opened with the same editor.

To use these plugins import them in your CDT sources.

TODO: see issues

Try it out

1. Download the latest Developer Build of Eclipse for C/C++ Developers or Eclipse for Embedded C/C++ Developers using the Eclipse installer or downloading and extracting the latest release available on eclipse.org.
2. Add to your Available Software Sites and install C/C++ LSP Support in the Eclipse CDT LSP Category and restart Eclipse from one of these p2 sites:
   • For latest release: https://download.eclipse.org/tools/cdt/releases/cdt-lsp-latest
   • For current master branch continuous build: https://download.eclipse.org/tools/cdt/builds/cdt-lsp/master/
3. Install Pre-requisites listed below
4. Create a CMake project or import an existing project following guidelines below
5. Enable the LSP based C/C++ Editor following instructions above.

See contribution guide for details on running CDT LSP from source.

Install pre-requisites

The following tools are needed on the PATH to operate the demo.

• gcc, make and other standard build tools
• cmake 3.10 or more recent - See cmake installation instructions
• clangd 15.0.3 or more recent - See clangd installation instructions

Import an existing project

You can import an existing project that contains a compile_commands.json file, or follow these instructions to create a simple starting project.

Create an example CMake project

1. File -> New -> Project...
2. Choose C/C++ -> C/C++ Project and press Next
3. Choose CMake Project and press Next
4. Enter a name for the project, e.g. example (avoid special characters and dashes, see eclipse-cdt/cdt#288)
5. Press Finish
6. Build the project to create the Compilation Database (compile_commands.json file)

The root of the project contains a .clangd file which tells clangd where clangd should fine the compilation database. This file may be hidden by default, therefore to see the file uncheck the .* resources in the filters for the Project Explorer view

Open a file

By default C/C++ will be opened with the standard CEditor. The default can be changed per project or per workspace with the C/C++ General -> Editor (LSP) -> Prefer C/C++ Editor (LSP) checkbox in the project setting or preferences.

• Note: The workspace setting will be used for projects that have not checked the Enable project specific settings checkbox in the project properties -> C/C++ General -> Editor (LSP) page.

Alternatively, you can choose which editor to open the file by using Open With:

With the C/C++ Editor (LSP) open, the presentation of the C++ file will follow the LSP4E conventions augmented by the information returned from clangd.

Version Support

The following table shows the versions of the main dependencies of CDT LSP for best operation as developed and tested. For example, CDT LSP 1.0.x was developed against clangd 15.0.x but CDT LSP should work with newer versions of clangd as well. For plug-in dependencies the MANIFEST.MF's dependency information will provide the most accurate information.

CDT LSP Version	clangd	cmake*	Eclipse IDE Release
1.0.x	15.0.x	3.x	2023-09

* cmake is required to run through the demo flow, but any tool that can create compile_commands.json or otherwise feed settings to clangd is suitable.

Known issues

See the open issues for known issues and workarounds while the code is in active development.