Page MenuHomePhabricator

clangd doc: Show a test case for clangd with some commands
Needs ReviewPublic

Authored by sylvestre.ledru on Mar 11 2020, 5:42 AM.

Details

Reviewers
sammccall
Summary

clangd is designed for IDE usage but having a simple test case
explains how it works.
It will help newcomers or potential users.

Diff Detail

Event Timeline

Herald added a project: Restricted Project. · View Herald TranscriptMar 11 2020, 5:42 AM

Add a link to the doc

Harbormaster completed remote builds in B48801: Diff 249595.

Thanks Sylvestre!

We're actually in the process of moving docs to a new site (preview: https://clangd.github.io - once set up it will be at clangd.llvm.org).

Who do you think is the audience/purpose for this doc? End-users don't need to understand this to use clangd (hopefully!).
On the other hand, they are developers, and "roughly how does this work" is a pretty good question.

Maybe we can include an incomplete snippet (e.g. abbreviated open, completion, response) on the front page or on /design/?
Some of the details (-lit-test flag, test uri scheme) should probably be changed unless the purpose really is to explain the lit-testtest setup specifically.

Good question :)
I have been wearing two hats here.

With my Debian/Ubuntu hat, i have been interested to write some dumb integration tests to be sure that clangd, as a package, works as expected.
I just need to make sure that the binary starts, that I can send some data and I am getting some outputs which makes sense.
https://salsa.debian.org/pkg-llvm-team/llvm-toolchain/-/blob/10/debian/qualify-clang.sh#L106-266 (I know it is ugly :)

With my Mozilla hat, I was interested to see how clangd works and we could call it from tooling. I think this doc helps understanding how it works quickly. Without spending too much time reading LSP or reading at the code of extensions.

About the -lit-test thing, it is because I am a noob :) I would be interested to know if there is a better way!

Happy to do any change you want, just let me know!

fix some typo + desc

Thanks for the context!

With my Debian/Ubuntu hat, i have been interested to write some dumb integration tests to be sure that clangd, as a package, works as expected.
I just need to make sure that the binary starts, that I can send some data and I am getting some outputs which makes sense.
https://salsa.debian.org/pkg-llvm-team/llvm-toolchain/-/blob/10/debian/qualify-clang.sh#L106-266 (I know it is ugly :)

That test looks pretty good to me! If you want to smoke-test the install a little more, one of the ways clangd can be setup wrong is unable to find the c++ standard library or the clang builtin headers. If you example has #include <map> or so and you scan for "diagnostics": [] in the output, you'll detect that.

This perspective seems fairly niche though, I'm not sure we need to cover it prominently in the docs.

With my Mozilla hat, I was interested to see how clangd works and we could call it from tooling. I think this doc helps understanding how it works quickly. Without spending too much time reading LSP or reading at the code of extensions.

Yeah, I think we should cover this one somehow. LSP spec isn't terribly readable if you want to get a flavour.
I think we could use a page on the new site "embedding" or "programmatic use" of clangd or something (not sure of the best title). It'd cover this (use features via LSP on stdio), using the C++ API, and the tradeoffs between the two. Is it OK if I take a stab at this and incorporates parts from here?

(Happy to discuss tooling use cases BTW - we've not got much experience for using outside a fairly standard language client/server setup)

About the -lit-test thing, it is because I am a noob :) I would be interested to know if there is a better way!

-lit-test is the right thing to use for the type of testing you're doing, but not anything else (including explaining clangd).

clangd -help-hidden | grep lit-test
--lit-test - Abbreviation for -input-style=delimited -pretty -sync -enable-test-scheme -log=verbose. Intended to simplify lit tests

For explanations -input-style=delimited -pretty is probably useful (and we should probably explain the former).