[PATCH] Tooling docs - structuring proposal

I'm working on documenting stuff around the general tooling efforts
that clang offers.
ind attached a crude first draft of where I want to start for people
who have no idea what they should look into.

The general structure I imagine is:
Tooling.html - basically the attached document, explaining what to use
when, linking to the other docs

ClangPlugins.html - tutorial on how to write a clang plugin,
eventually leading to FrontendAction.html
LibTooling.html - tutorial on how to write clang standalone tools,
also leading to FrontendAction.html
(LibClang.html would fit here, but I'm not in a position to write it :wink:

FrontendAction.html - explains how to create your own FrontendAction
to use in a plugin or clang tool, possibly including the use of the
RAV (not sure whether we should split that out), linking to
ClangAST.html for reference

ClangAST.html - a more generic introduction to the Clang AST, what it
looks like on a high level, the basic nodes it's made up from, how to
dig into the docs etc

If nobody objects I'll just go on writing initial rough draft versions...

Thoughts?
/Manuel

docs.patch (3.88 KB)

Manuel Klimek wrote:

I'm working on documenting stuff around the general tooling efforts
that clang offers.
ind attached a crude first draft of where I want to start for people
who have no idea what they should look into.

The general structure I imagine is:
Tooling.html - basically the attached document, explaining what to use
when, linking to the other docs

ClangPlugins.html - tutorial on how to write a clang plugin,
eventually leading to FrontendAction.html
LibTooling.html - tutorial on how to write clang standalone tools,
also leading to FrontendAction.html
(LibClang.html would fit here, but I'm not in a position to write it :wink:

FrontendAction.html - explains how to create your own FrontendAction
to use in a plugin or clang tool, possibly including the use of the
RAV (not sure whether we should split that out), linking to
ClangAST.html for reference

ClangAST.html - a more generic introduction to the Clang AST, what it
looks like on a high level, the basic nodes it's made up from, how to
dig into the docs etc

If nobody objects I'll just go on writing initial rough draft versions...

Thoughts?
/Manuel

Did any more documentation along these lines ever get written?

Not yet, last week I was pretty busy with the conference :slight_smile: But I'm
working on it - it's high on my priority list.

Cheers,
/Manuel

Attached is a first version of Tooling.html for review. The links will
be updated as I write the rest of the docs.

Btw, what's the review process for docs? :slight_smile:

Cheers,
/Manuel

Tooling.html (3.77 KB)

Attached is a first version of Tooling.html for review. The links will
be updated as I write the rest of the docs.

Btw, what's the review process for docs? :slight_smile:

I don't know, but you've got some errors in your docs, in the libTooling section.

Canonical examples of when to use LibTooling:

  • a simple syntax checker
  • refactoringh tools

RefactoringH ? Is that a german thing? :wink:

Use LibTooling when you...

  • want to run tools over a single file, or a specific subset of files, independently of the build system
  • want full control over the Clang AST

Do not use Clang Plugins when you...

  • want to run as part of the build triggered by dependency changes
  • want a stable high-level interface
  • do not want to write your tools in C++

"Do not use Clang Plugins"… ?
Copy/paste error?

-- Marshall

Marshall Clow Idio Software <mailto:mclow.lists@gmail.com>

A.D. 1517: Martin Luther nails his 95 Theses to the church door and is promptly moderated down to (-1, Flamebait).
        -- Yu Suzuki

Attached is a first version of Tooling.html for review. The links will
be updated as I write the rest of the docs.

Btw, what's the review process for docs? :slight_smile:

I don't know, but you've got some errors in your docs, in the libTooling section.

Canonical examples of when to use LibTooling:

  • a simple syntax checker
  • refactoringh tools

RefactoringH ? Is that a german thing? :wink:

It's a Manuel-too-stupid-to-use-vim thing :stuck_out_tongue:

Use LibTooling when you...

  • want to run tools over a single file, or a specific subset of files, independently of the build system
  • want full control over the Clang AST

Do not use Clang Plugins when you...

  • want to run as part of the build triggered by dependency changes
  • want a stable high\-level interface
  • do not want to write your tools in C\+\+

"Do not use Clang Plugins"… ?
Copy/paste error?

Done.

Thx for the review!
/Manuel

Tooling.html (3.77 KB)

And one more:
special lint-style *warningsi*

Done. Oh, I love compilers... :smiley:

Thx for the review!

Tooling.html (3.77 KB)

Attached is a first version of Tooling.html for review.

Hi Manuel!

One thing missing from this overview is that after reading it I still don't really know what LibTooling offers. Is the only difference between LibTooling and LibClang that LibTooling is C++ not C, and that it gives full control over the Clang AST? If it offers other convenient functionality, it might be worth (very briefly) listing that functionality specifically (right here on this page, not LibTooling.html).

Is LibTooling less "high level" than LibClang? (I understand that it offers fuller access to the details of the Clang AST, so in a sense it is more "low level", but does that also mean that doing simple things is more difficult?)

Or with LibTooling are you essentially using the same Clang API (for the AST etc) as when you are writing a Plugin, but with additional helper functions provided by LibTooling?

Some minor points of style (these are only suggestions):

--- Tooling.html.orig
+++ Tooling.html
@@ -28,6 +28,8 @@
</ul>
<p>Use LibClang when you...</p>
<ul>
+ <li>want to run tools over a single file, or a specific subset of files,
+ independently of the build system</li>
   <li>want to interface with clang from other languages than C++</li>
   <li>need a stable interface that takes care to be backwards compatible</li>
   <li>want powerful high-level abstractions, like iterating throught an AST
@@ -37,6 +39,7 @@
<p>Do not use LibClang when you...</p>
<ul>
   <li>want full control over the Clang AST</li>
+ <li>want to run as part of the build triggered by dependency changes</li>
</ul>

<!-- ======================================================================= -->

...because I want to compare the 3 options against each other, so anything that holds for LibClang *and* LibTooling should be listed under both.

@@ -70,7 +72,7 @@
<h2 id="libtooling"><a href="http://clang.llvm.org/doxygen/namespaceclang_1_1tooling.html">LibTooling</a></h2>
<!-- ======================================================================= -->

-<p>LibTooling is a library aimed at writing standalone tools, as well as
+<p>LibTooling is C++ interface aimed at writing standalone tools, as well as
integrating into services that run clang tools.</p>
<p>Canonical examples of when to use LibTooling:</p>
<ul>

...to mirror the structure of the LibClang section, instead of leaving the reader to infer the C++ness of the interface from the "do not use" bullet-point later on.

@@ -86,7 +88,7 @@
<p>Do not use LibTooling when you...</p>
<ul>
   <li>want to run as part of the build triggered by dependency changes</li>
- <li>want a stable high-level interface</li>
+ <li>want a stable interface</li>
   <li>do not want to write your tools in C++</li>
</ul>

...this depends on the answer to my question "is LibTooling less high-level", but I think the stability of the interface is a separate concern from its high-levelness.

Thanks for doing this! Sorry for nit-picking. :slight_smile:

Dave.

"need to run over a specific subset of files in your project which is not
necessarily related to any changes"
It's unclear what you mean by "not necessarily related to any changes".

Done, hopefully.

Attached is a first version of Tooling.html for review.

Hi Manuel!

One thing missing from this overview is that after reading it I still don't really know what LibTooling offers. Is the only difference between LibTooling and LibClang that LibTooling is C++ not C, and that it gives full control over the Clang AST? If it offers other convenient functionality, it might be worth (very briefly) listing that functionality specifically (right here on this page, not LibTooling.html).

Plus the build system point, pretty much, yes... I've added a point
for sharing code with clang plugins.

Is LibTooling less "high level" than LibClang? (I understand that it offers fuller access to the details of the Clang AST, so in a sense it is more "low level", but does that also mean that doing simple things is more difficult?)

LibClang offers more high level abstractions (I added that in the "Do
not use LibTooling..." list)

Or with LibTooling are you essentially using the same Clang API (for the AST etc) as when you are writing a Plugin, but with additional helper functions provided by LibTooling?

Yep.

Some minor points of style (these are only suggestions):

--- Tooling.html.orig
+++ Tooling.html
@@ -28,6 +28,8 @@
</ul>
<p>Use LibClang when you...</p>
<ul>
+ <li>want to run tools over a single file, or a specific subset of files,
+ independently of the build system</li>
<li>want to interface with clang from other languages than C++</li>
<li>need a stable interface that takes care to be backwards compatible</li>
<li>want powerful high-level abstractions, like iterating throught an AST
@@ -37,6 +39,7 @@
<p>Do not use LibClang when you...</p>
<ul>
<li>want full control over the Clang AST</li>
+ <li>want to run as part of the build triggered by dependency changes</li>
</ul>

<!-- ======================================================================= -->

...because I want to compare the 3 options against each other, so anything that holds for LibClang *and* LibTooling should be listed under both.

But ... those are exactly the *differences* :slight_smile: I tried to put that in
positively formulated in the Clang Plugins section.

@@ -70,7 +72,7 @@
<h2 id="libtooling"><a href="http://clang.llvm.org/doxygen/namespaceclang_1_1tooling.html">LibTooling</a></h2>
<!-- ======================================================================= -->

-<p>LibTooling is a library aimed at writing standalone tools, as well as
+<p>LibTooling is C++ interface aimed at writing standalone tools, as well as
integrating into services that run clang tools.</p>
<p>Canonical examples of when to use LibTooling:</p>
<ul>

...to mirror the structure of the LibClang section, instead of leaving the reader to infer the C++ness of the interface from the "do not use" bullet-point later on.

Done.

@@ -86,7 +88,7 @@
<p>Do not use LibTooling when you...</p>
<ul>
<li>want to run as part of the build triggered by dependency changes</li>
- <li>want a stable high-level interface</li>
+ <li>want a stable interface</li>
<li>do not want to write your tools in C++</li>
</ul>

...this depends on the answer to my question "is LibTooling less high-level", but I think the stability of the interface is a separate concern from its high-levelness.

Done.

Thanks for doing this! Sorry for nit-picking. :slight_smile:

If you think what you're doing is nit-picking, you have not been
subjected to nit-picking yet :slight_smile:

Thanks for the review!

Cheers,
/Manuel

Tooling.html (3.99 KB)

Attached is a first version of Tooling.html for review.

One last suggestion:

Is this the most recent revision of this document, or is it already checked
in?

Manuel Klimek wrote:

<p>Canonical examples of when to use Clang Plugins:</p>
<ul>
<li>special lint-style warnings or errors for your project</li>
<li>creating additional build artifacts from a singe compile step</li>
</ul>

Typo here. singe -> single.

Thanks,

Steve.

Is this the most recent revision of this document, or is it already checked
in?

Now checked in.

Manuel Klimek wrote:

<p>Canonical examples of when to use Clang Plugins:</p>
<ul>
<li>special lint-style warnings or errors for your project</li>
<li>creating additional build artifacts from a singe compile step</li>
</ul>

Typo here. singe -> single.

Done. Thx for the review.

Cheers,
/Manuel