[Analyzer][Docs][NFC] Add CodeChecker to the command line tools

[martong]

Summary

We add a new common html file that documents the available command line tools.
Also a new html is added for a brief description of CodeChecker, this way complementing scan-build.

[Szelethus]

For reasons other than being a part of the project, CodeChecker is objectively an amazing tool to use with the analyzer. LGTM!

[martong]

@Szelethus, Kristof thanks for the review.
@NoQ Ping. I'd like to have an approve from somebody who is outside the CodeChecker/E/// gang.

[martong]

@NoQ Ping.

[NoQ]

Hey, thanks for waiting on me! I'm slow these days, just 50 more mails to go >.<

This review strikes me as a wiki material. I wonder what's the community stance on making wikis. #showerthoughs

clang/www/analyzer/codechecker.html

14

Note related to your patch, but SSI seem to be completely broken these days; previously the dropdown menus header kept working on the front page but now even that's missing. Patches are very welcome >.<

24

I think you should start with installing CodeChecker. I.e.,

1. Clone it from github: git clone ....
2. ???

29

I'm confused. I obtained an overview, but what are the steps that i need to do if i want to actually view the issues? I have to start the web server anyway, right? Then what's the point of of invoking check separately? Can you invoke check from the web server directly?

I wish this document looked more like a step-by-step guide on how to obtain the results (or how to set up a collaborative server). Right now it's a collection of seemingly unrelated solutions for sub-problems that I don't immediately understand how to combine in order to obtain the desired result.

clang/www/analyzer/command-line.html

19

The first thing that we want to underline here is that the user should ABSOLUTELY NOT try to read warnings from the command line. I still see a lot of users who try to read scan-build's standard output and understand warnings from there without seeing any path notes.

I suggest the following intro:

"Static Analyzer is by design a GUI tool. Its purpose is to find buggy execution paths in the program, and such paths are very hard to comprehend by looking at a non-interactive standard output. It is possible, however, to invoke the Static Analyzer from the command line in order to obtain analysis results, and then later view them interactively in a graphical interface."

20

Do you plan to eventually mention clang-tidy as well?

23–28

WDYT of the following:

Scan-Build is an old and simple command-line tool that emits static analyzer warnings as HTML files while compiling your project. You can view analysis results in your web browser.

• Useful for individual developers who simply want to view static analysis results at their desk, or in very simple collaborative environment.
• Works on all major platforms (Windows, Linux, macOS) and is available as a package in many linux distributions.
• Does not include support for cross-translation-unit analysis.

29

Let's describe the tool a bit as well. Maybe something like this:

CodeChecker is a web server that runs the Static Analyzer on your projects on demand and maintains a database of issues.

• Perfect for managing large amounts of Static Analyzer warnings in a collaborative environment.
• Generally much more feature-rich than scan-build.
• (more stuff here)

32

LLVM is now also hosted on github, so not sure what the message is. We should probably either provide a link or just say that it's out-of-tree.

33–34

The same is true for scan-build.

Also, while it is possible that one of the tools does a strictly better job than the other, but the problem is, i think, generally unsolvable, because there's no perfect correspondence between GCC flags and Clang flags. So i think we should avoid strong statements here ("work seamlessly") - even intercepting the build system (let alone setting correct compiler flags) is an unsolvable problem in general.

[martong]

Addressing Artem's review comments.
Artem, thanks for the review!

clang/www/analyzer/codechecker.html

14

Ok, actually, this line is a result of copy pasting from scan-build.html. I don't think I'd be competence enough to solve the drop-down menu issue, so, I just removed this line.

29

Ok, I've rewritten this to be more like a step-by-step howto and to be as simple as possible.

clang/www/analyzer/command-line.html

19

Okay, I added it at the beginning of the first paragraph.

20

Ok, I added that since CodeChecker can handle clang-tidy checkers too.

23–28

Sounds good to me, updated like that.

29

Ok.

32

Ok, I removed the "github" part.

33–34

Alright, I removed this list item.

[NoQ]

clang/www/analyzer/codechecker.html

14

No-no, i'd rather keep it. Otherwise how do we remember to fix it? :D

49

Maybe xdg-open?

[Charusso]

I would change the order of CCh and scan-build because we usually list stuff in alphabetical order. Also the chronological order is that, the newest is the first.

clang/www/analyzer/command-line.html

55

LLVM peoples seems to care to use open source projects, so I would mention it.

[martong]

In D70439#1772168, @Charusso wrote:

I would change the order of CCh and scan-build because we usually list stuff in alphabetical order. Also the chronological order is that, the newest is the first.

I am not sure if the order matters that much because the page is very terse and small, so a reader can have a quick look to see that there are only these tools.

clang/www/analyzer/codechecker.html

14

Alright, I've put it back.

49

I'd like to keep "firefox" so readers immediately know that we are dealing with a web-browser. "xdg-open" might not be that obvious I think.

clang/www/analyzer/command-line.html

55

Ok, I added that to this list item.

[martong]

Put back the menu, add "open source" property.

[NoQ]

Thanks!!~

clang/www/analyzer/codechecker.html

+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+          "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+  <title>CodeChecker: running the analyzer from the command line</title>
+  <link type="text/css" rel="stylesheet" href="content.css">
+  <link type="text/css" rel="stylesheet" href="menu.css">
+  <script type="text/javascript" src="scripts/menu.js"></script>
+</head>
+<body>
+
+<div id="page">
+<!--#include virtual="menu.html.incl"-->
+<div id="content">
+
+<h1>CodeChecker: running the analyzer from the command line</h1>
+
+<h2>Basic Usage</h2>
+
+<p>
+Install CodeChecker as described here: <a href="https://github.com/Ericsson/codechecker/#Install-guide"> CodeChecker Install Guide.</a>
+</p>
+
+<p>
+Create a compilation database. If you use cmake then pass the <tt>-DCMAKE_EXPORT_COMPILE_COMMANDS=1</tt> parameter to cmake. Cmake will create a <tt>compile_commands.json</tt> file.
+If you have a Makefile based or similar build system then you can log the build commands with the help of CodeChecker:
+<pre class="code_example">
+make clean
+CodeChecker log -b "make" -o compile_commands.json
+</pre>
+</p>
+
+<p>
+Analyze your project.
+<pre class="code_example">
+CodeChecker analyze compile_commands.json -o ./reports
+</pre>
+</p>
+
+<p>
+View the analysis results.
+Print the detailed results in the command line:
+<pre class="code_example">
+CodeChecker parse --print-steps ./reports
+</pre>
+Or view the detailed results in a browser:
+<pre class="code_example">
+CodeChecker parse ./reports -e html -o ./reports_html
+firefox ./reports_html/index.html
+</pre>
+</p>
+
+<p>
+Optional: store the analysis results in a DB.
+<pre class="code_example">
+mkdir ./ws
+CodeChecker server -w ./ws -v 8555 &
+CodeChecker store ./reports --name my-project --url http://localhost:8555/Default
+</pre>
+</p>
+
+<p>
+Optional: manage (categorize, suppress) the results in your web browser:
+<pre class="code_example">
+firefox http://localhost:8555/Default
+</pre>
+</p>
+
+<h2>Detailed Usage</h2>
+
+<p>
+For extended documentation please refer to the <a href="https://github.com/Ericsson/codechecker/blob/master/docs/usage.md">official site of CodeChecker</a>!
+</p>

clang/www/analyzer/command-line.html

+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+          "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+  <title>Running the analyzer from the command line</title>
+  <link type="text/css" rel="stylesheet" href="content.css">
+  <link type="text/css" rel="stylesheet" href="menu.css">
+  <script type="text/javascript" src="scripts/menu.js"></script>
+</head>
+<body>
+
+<div id="page">
+<!--#include virtual="menu.html.incl"-->
+<div id="content">
+
+<h1>Running the analyzer from the command line</h1>
+
+<p> Static Analyzer is by design a GUI tool. Its purpose is to find buggy execution
+paths in the program, and such paths are very hard to comprehend by looking at
+a non-interactive standard output. It is possible, however, to invoke the
+Static Analyzer from the command line in order to obtain analysis results, and
+then later view them interactively in a graphical interface. The following
+tools are used commonly to run the analyzer from the command line. Both tools
+are wrapper scripts to drive the analysis and the underlying invocations of the
+Clang compiler:
+<ol>
+  <li><a href="scan-build.html">Scan-Build</a>
+    is an old and simple command-line tool that emits static analyzer warnings as HTML files while compiling your project. You can view the analysis results in your web browser.
+  </li>
+  <ul>
+    <li>
+      Useful for individual developers who simply want to view static analysis results at their desk, or in a very simple collaborative environment.
+    </li>
+    <li>
+      Works on all major platforms (Windows, Linux, macOS) and is available as a package in many Linux distributions.
+    </li>
+    <li>
+      Does not include support for cross-translation-unit analysis.
+    </li>
+  </ul>
+  <li><a href="codechecker.html">CodeChecker</a>
+     is a web server that runs the Static Analyzer on your projects on demand and maintains a database of issues.
+  </li>
+  <ul>
+    <li>
+      Perfect for managing large amounts of Static Analyzer warnings in a collaborative environment.
+    </li>
+    <li>
+      Generally much more feature-rich than scan-build.
+    </li>
+    <li>Supports incremental analysis: Results can be stored in a database, subsequent analysis runs can be compared to list the newly added defects.</li>
+    <li><a href="https://clang.llvm.org/docs/analyzer/user-docs/CrossTranslationUnit.html">Cross Translation Unit (CTU) analysis</a> is supported fully on Linux via CodeChecker.</li>
+    <li>Can run clang-tidy checkers too.</li>
+    <li>Open source, but out-of-tree, i.e. not part of the LLVM project.</li>
+  </ul>
+</ol>
+</p>
+
+<p>
+</p>
+<p>
+</p>
+
+</div>
+</div>
+</body>
+</html>

clang/www/analyzer/index.html

 <table style="margin-top:0px" width="100%" border="0" cellpadding="0px" cellspacing="0">
 <tr><td>
 
 <h1>Clang Static Analyzer</h1>
 
 <p>The Clang Static Analyzer is a source code analysis tool that finds bugs in
 C, C++, and Objective-C programs.</p>
 
-<p>Currently it can be run either as a <a href="scan-build.html">standalone
-tool</a> or <a href="xcode.html">within Xcode</a>. The standalone tool is
-invoked from the command line, and is intended to be run in tandem with a build
+<p>Currently it can be run either from the <a href="command-line.html">command
+  line</a> or if you use macOS then <a href="xcode.html">within Xcode</a>. When
+invoked from the command line, it is intended to be run in tandem with a build
 of a codebase.</p>
 
 <p>The analyzer is 100% open source and is part of the <a
 href="https://clang.llvm.org">Clang</a> project. Like the rest of Clang, the
 analyzer is implemented as a C++ library that can be used by other tools and
 applications.</p>
 
 <h2>Download</h2>