This is an archive of the discontinued LLVM Phabricator instance.

Differential D58607

Moved clangd docs to a separate directory in preparation to restructure them into multiple files
ClosedPublic

Authored by gribozavr on Feb 25 2019, 4:35 AM.

Details

Reviewers
ilya-biryukov
Commits
rGa06e0290814d: Moved clangd docs to a separate directory in preparation to restructure them…
rL354786: Moved clangd docs to a separate directory in preparation to restructure them…
rCTE354786: Moved clangd docs to a separate directory in preparation to restructure them…

Diff Detail

Event Timeline

gribozavr created this revision.Feb 25 2019, 4:35 AM
Herald added a project: Restricted Project. · View Herald TranscriptFeb 25 2019, 4:35 AM
Herald added subscribers: jdoerfert, kadircet, arphaman and 3 others. · View Herald Transcript
Harbormaster completed remote builds in B28479: Diff 188131.Feb 25 2019, 4:38 AM
ilya-biryukov added inline comments.Feb 25 2019, 4:39 AM
clang-tools-extra/docs/clangd.rst
1 ↗(On Diff #188131)

Having this does page not seem useful in the long-run.
Do we plan to remove it later? Or maybe there a way to create a redirect instead?

gribozavr marked an inline comment as done.Feb 25 2019, 4:41 AM
gribozavr added inline comments.
clang-tools-extra/docs/clangd.rst
1 ↗(On Diff #188131)

Yes, it should be eventually removed. It is supposed to be a redirect -- it is the best we can do in plain HTML without access to HTTP headers.

ilya-biryukov accepted this revision.Feb 25 2019, 5:02 AM

LGTM

clang-tools-extra/docs/clangd.rst
1 ↗(On Diff #188131)

Yeah, looks like it's the best we can do.

This revision is now accepted and ready to land.Feb 25 2019, 5:02 AM
Closed by commit rCTE354786: Moved clangd docs to a separate directory in preparation to restructure them… (authored by gribozavr). · Explain WhyFeb 25 2019, 5:44 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents

PathSize
docs/
181 lines
clangd/
180 lines
2 lines

Diff 188151

docs/clangd.rst

============ :orphan:
Clangd
============
.. contents:: All :program:`clangd` documentation was moved to the :doc:`clangd/index` pages.
.. toctree::
:maxdepth: 1
:program:`Clangd` is an implementation of the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang.
Clangd's goal is to provide language "smartness" features like code completion,
find references, etc. for clients such as C/C++ Editors.
Using Clangd
==================
:program:`Clangd` is not meant to be used by C/C++ developers directly but
rather from a client implementing the protocol. A client would be typically
implemented in an IDE or an editor.
At the moment, `Visual Studio Code <https://code.visualstudio.com/>`_ is mainly
used in order to test :program:`Clangd` but more clients are likely to make
use of :program:`Clangd` in the future as it matures and becomes a production
quality tool. If you are interested in trying :program:`Clangd` in combination
with Visual Studio Code, you can start by `installing Clangd`_ or
`building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and
launch the extension.
Installing Clangd
==================
Packages are available for debian-based distributions, see the `LLVM packages
page <https://apt.llvm.org/>`_. :program:`Clangd` is included in the
`clang-tools` package.
However, it is a good idea to check your distribution's packaging system first
as it might already be available.
Otherwise, you can install :program:`Clangd` by `building Clangd`_ first.
Building Clangd
==================
You can follow the instructions for `building Clang
<https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not**
optional.
Current Status
==================
Many features could be implemented in :program:`Clangd`.
Here is a list of features that could be useful with the status of whether or
not they are already implemented in :program:`Clangd` and specified in the
Language Server Protocol. Note that for some of the features, it is not clear
whether or not they should be part of the Language Server Protocol, so those
features might be eventually developed outside :program:`Clangd` or as an
extension to the protocol.
+-------------------------------------+------------+----------+
| C/C++ Editor feature | LSP | Clangd |
+=====================================+============+==========+
| Formatting | Yes | Yes |
+-------------------------------------+------------+----------+
| Completion | Yes | Yes |
+-------------------------------------+------------+----------+
| Diagnostics | Yes | Yes |
+-------------------------------------+------------+----------+
| Fix-its | Yes | Yes |
+-------------------------------------+------------+----------+
| Go to Definition | Yes | Yes |
+-------------------------------------+------------+----------+
| Signature Help | Yes | Yes |
+-------------------------------------+------------+----------+
| Document Highlights | Yes | Yes |
+-------------------------------------+------------+----------+
| Rename | Yes | Yes |
+-------------------------------------+------------+----------+
| Source hover | Yes | Yes |
+-------------------------------------+------------+----------+
| Find References | Yes | No |
+-------------------------------------+------------+----------+
| Code Lens | Yes | No |
+-------------------------------------+------------+----------+
| Document Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Workspace Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Syntax and Semantic Coloring | No | No |
+-------------------------------------+------------+----------+
| Code folding | No | No |
+-------------------------------------+------------+----------+
| Call hierarchy | No | No |
+-------------------------------------+------------+----------+
| Type hierarchy | No | No |
+-------------------------------------+------------+----------+
| Organize Includes | No | No |
+-------------------------------------+------------+----------+
| Quick Assist | No | No |
+-------------------------------------+------------+----------+
| Extract Local Variable | No | No |
+-------------------------------------+------------+----------+
| Extract Function/Method | No | No |
+-------------------------------------+------------+----------+
| Hide Method | No | No |
+-------------------------------------+------------+----------+
| Implement Method | No | No |
+-------------------------------------+------------+----------+
| Gen. Getters/Setters | No | No |
+-------------------------------------+------------+----------+
Editor Integration
==================
Any full-featured Language Server Protocol Client implementation should work
with :program:`Clangd`. This `list
<https://langserver.org/#implementations-client>`_ contains information about
extensions and plugins that are known to work for different editors.
Vim Integration
---------------
LanguageClient-neovim
~~~~~~~~~~~~~~~~~~~~~
One of the options of using :program:`Clangd` in :program:`vim` (or
:program:`nvim`) is to utilize `LanguageClient-neovim
<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the
`Clangd Wiki page
<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for
instructions.
VSCode Integration
------------------
:program:`VSCode` provides `vscode-clangd
<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_
which is published in Visual Studio Marketplace and can be installed direcetly
from :program:`VSCode`.
Emacs Integration
-----------------
:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and
`Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration.
Project-wide Index
==================
By default :program:`Clangd` only has a view on symbols coming from files you
are currently editing. You can extend this view to whole project by providing a
project-wide index to :program:`Clangd`.
There are two ways you can generate a project-wide index for clangd:
- Passing experimental `-background-index` commandline argument, which will
incrementally build an index of projects that you work on and make use of that
in clangd automatically.
- Generate an index file using `clangd-indexer
<https://github.com/llvm-mirror/clang-tools-extra/blob/master/clangd/indexer/IndexerMain.cpp>`_
Afterwards you can pass generated index file to clangd using
`-index-file=/path/to/index_file`. *Note that clangd-indexer isn't included
alongside clangd in the standard clang-tools package. You will likely have to
build from source to use this option*
Getting Involved
==================
A good place for interested contributors is the `Clangd developer mailing list
<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the
broader community on topics not only related to Clangd, use
`Clang developer mailing list
<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
If you're also interested in contributing patches to :program:`Clangd`, take a
look at the `LLVM Developer Policy
<https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews
<https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features
to the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ itself would also be
very useful, so that :program:`Clangd` can eventually implement them in a
conforming way.

docs/clangd/index.rst

============
Clangd
============
.. contents::
.. toctree::
:maxdepth: 1
:program:`Clangd` is an implementation of the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang.
Clangd's goal is to provide language "smartness" features like code completion,
find references, etc. for clients such as C/C++ Editors.
Using Clangd
==================
:program:`Clangd` is not meant to be used by C/C++ developers directly but
rather from a client implementing the protocol. A client would be typically
implemented in an IDE or an editor.
At the moment, `Visual Studio Code <https://code.visualstudio.com/>`_ is mainly
used in order to test :program:`Clangd` but more clients are likely to make
use of :program:`Clangd` in the future as it matures and becomes a production
quality tool. If you are interested in trying :program:`Clangd` in combination
with Visual Studio Code, you can start by `installing Clangd`_ or
`building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and
launch the extension.
Installing Clangd
==================
Packages are available for debian-based distributions, see the `LLVM packages
page <https://apt.llvm.org/>`_. :program:`Clangd` is included in the
`clang-tools` package.
However, it is a good idea to check your distribution's packaging system first
as it might already be available.
Otherwise, you can install :program:`Clangd` by `building Clangd`_ first.
Building Clangd
==================
You can follow the instructions for `building Clang
<https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not**
optional.
Current Status
==================
Many features could be implemented in :program:`Clangd`.
Here is a list of features that could be useful with the status of whether or
not they are already implemented in :program:`Clangd` and specified in the
Language Server Protocol. Note that for some of the features, it is not clear
whether or not they should be part of the Language Server Protocol, so those
features might be eventually developed outside :program:`Clangd` or as an
extension to the protocol.
+-------------------------------------+------------+----------+
| C/C++ Editor feature | LSP | Clangd |
+=====================================+============+==========+
| Formatting | Yes | Yes |
+-------------------------------------+------------+----------+
| Completion | Yes | Yes |
+-------------------------------------+------------+----------+
| Diagnostics | Yes | Yes |
+-------------------------------------+------------+----------+
| Fix-its | Yes | Yes |
+-------------------------------------+------------+----------+
| Go to Definition | Yes | Yes |
+-------------------------------------+------------+----------+
| Signature Help | Yes | Yes |
+-------------------------------------+------------+----------+
| Document Highlights | Yes | Yes |
+-------------------------------------+------------+----------+
| Rename | Yes | Yes |
+-------------------------------------+------------+----------+
| Source hover | Yes | Yes |
+-------------------------------------+------------+----------+
| Find References | Yes | No |
+-------------------------------------+------------+----------+
| Code Lens | Yes | No |
+-------------------------------------+------------+----------+
| Document Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Workspace Symbols | Yes | Yes |
+-------------------------------------+------------+----------+
| Syntax and Semantic Coloring | No | No |
+-------------------------------------+------------+----------+
| Code folding | No | No |
+-------------------------------------+------------+----------+
| Call hierarchy | No | No |
+-------------------------------------+------------+----------+
| Type hierarchy | No | No |
+-------------------------------------+------------+----------+
| Organize Includes | No | No |
+-------------------------------------+------------+----------+
| Quick Assist | No | No |
+-------------------------------------+------------+----------+
| Extract Local Variable | No | No |
+-------------------------------------+------------+----------+
| Extract Function/Method | No | No |
+-------------------------------------+------------+----------+
| Hide Method | No | No |
+-------------------------------------+------------+----------+
| Implement Method | No | No |
+-------------------------------------+------------+----------+
| Gen. Getters/Setters | No | No |
+-------------------------------------+------------+----------+
Editor Integration
==================
Any full-featured Language Server Protocol Client implementation should work
with :program:`Clangd`. This `list
<https://langserver.org/#implementations-client>`_ contains information about
extensions and plugins that are known to work for different editors.
Vim Integration
---------------
LanguageClient-neovim
~~~~~~~~~~~~~~~~~~~~~
One of the options of using :program:`Clangd` in :program:`vim` (or
:program:`nvim`) is to utilize `LanguageClient-neovim
<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the
`Clangd Wiki page
<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for
instructions.
VSCode Integration
------------------
:program:`VSCode` provides `vscode-clangd
<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_
which is published in Visual Studio Marketplace and can be installed direcetly
from :program:`VSCode`.
Emacs Integration
-----------------
:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and
`Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration.
Project-wide Index
==================
By default :program:`Clangd` only has a view on symbols coming from files you
are currently editing. You can extend this view to whole project by providing a
project-wide index to :program:`Clangd`.
There are two ways you can generate a project-wide index for clangd:
- Passing experimental `-background-index` commandline argument, which will
incrementally build an index of projects that you work on and make use of that
in clangd automatically.
- Generate an index file using `clangd-indexer
<https://github.com/llvm-mirror/clang-tools-extra/blob/master/clangd/indexer/IndexerMain.cpp>`_
Afterwards you can pass generated index file to clangd using
`-index-file=/path/to/index_file`. *Note that clangd-indexer isn't included
alongside clangd in the standard clang-tools package. You will likely have to
build from source to use this option*
Getting Involved
==================
A good place for interested contributors is the `Clangd developer mailing list
<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the
broader community on topics not only related to Clangd, use
`Clang developer mailing list
<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
If you're also interested in contributing patches to :program:`Clangd`, take a
look at the `LLVM Developer Policy
<https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews
<https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features
to the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ itself would also be
very useful, so that :program:`Clangd` can eventually implement them in a
conforming way.

docs/index.rst

Show All 14 Lines
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
clang-tidy/index clang-tidy/index
include-fixer include-fixer
modularize modularize
pp-trace pp-trace
clang-rename clang-rename
clangd clangd/index
clang-doc clang-doc
Doxygen Documentation Doxygen Documentation
===================== =====================
The Doxygen documentation describes the **internal** software that makes up the The Doxygen documentation describes the **internal** software that makes up the
tools of clang-tools-extra, not the **external** use of these tools. The Doxygen tools of clang-tools-extra, not the **external** use of these tools. The Doxygen
documentation contains no instructions about how to use the tools, only the APIs documentation contains no instructions about how to use the tools, only the APIs
Show All 18 Lines