[cfe-commits] r160138 - /cfe/trunk/docs/LibTooling.html

[Manuel Klimek]

Author: klimek
Date: Thu Jul 12 13:32:50 2012
New Revision: 160138

URL: http://llvm.org/viewvc/llvm-project?rev=160138&view=rev
Log:
Updates the example to the latest incarnation of clang-check and
adds a paragraph on builtin headers.


Modified:
    cfe/trunk/docs/LibTooling.html

Modified: cfe/trunk/docs/LibTooling.html
URL: http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/LibTooling.html?rev=160138&r1=160137&r2=160138&view=diff
==============================================================================
--- cfe/trunk/docs/LibTooling.html (original)
+++ cfe/trunk/docs/LibTooling.html Thu Jul 12 13:32:50 2012
@@ -72,17 +72,21 @@
   if (!Compilations) {
     // In case the user did not specify the compile command line via positional
     // command line arguments after "--", try to load the compile commands from
-    // a database in the specified build directory.
+    // a database in the specified build directory or auto-detect it from a
+    // source file.
     std::string ErrorMessage;
-    Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
-                                                              ErrorMessage));
-
+    if (!BuildPath.empty()) {
+      Compilations.reset(
+         CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage));
+    } else {
+      Compilations.reset(CompilationDatabase::autoDetectFromSource(
+          SourcePaths[0], ErrorMessage));
+    }
     // If there is still no valid compile command database, we don't know how
     // to run the tool.
     if (!Compilations)
       llvm::report_fatal_error(ErrorMessage);
   }
-...
 }
 </pre>
 </p>
@@ -113,37 +117,43 @@
 <p>Now we combine the two previous steps into our first real tool. This example
 tool is also checked into the clang tree at tools/clang-check/ClangCheck.cpp.
 <pre>
-  #include "llvm/Support/CommandLine.h"
-  #include "clang/Frontend/FrontendActions.h"
-  #include "clang/Tooling/CompilationDatabase.h"
-  #include "clang/Tooling/Tooling.h"
-
-  using namespace clang::tooling;
-  using namespace llvm;
-
-  cl::opt<std::string> BuildPath(
-    cl::Positional,
-    cl::desc("<build-path>"));
-
-  cl::list<std::string> SourcePaths(
-    cl::Positional,
-    cl::desc("<source0> [... <sourceN>]"),
-    cl::OneOrMore);
-
-  int main(int argc, const char **argv) {
-    llvm::OwningPtr<CompilationDatabase> Compilations(
-      FixedCompilationDatabase::loadFromCommandLine(argc, argv));
-    cl::ParseCommandLineOptions(argc, argv);
-    if (!Compilations) {
-      std::string ErrorMessage;
-      Compilations.reset(CompilationDatabase::loadFromDirectory(BuildPath,
-                                                                ErrorMessage));
-      if (!Compilations)
-        llvm::report_fatal_error(ErrorMessage);
+#include "llvm/Support/CommandLine.h"
+#include "clang/Frontend/FrontendActions.h"
+#include "clang/Tooling/CompilationDatabase.h"
+#include "clang/Tooling/Tooling.h"
+
+using namespace clang::tooling;
+using namespace llvm;
+
+cl::opt<std::string> BuildPath(
+  "p",
+  cl::desc("<build-path>"),
+  cl::Optional);
+
+cl::list<std::string> SourcePaths(
+  cl::Positional,
+  cl::desc("<source0> [... <sourceN>]"),
+  cl::OneOrMore);
+
+int main(int argc, const char **argv) {
+  llvm::OwningPtr<CompilationDatabase> Compilations(
+    FixedCompilationDatabase::loadFromCommandLine(argc, argv));
+  cl::ParseCommandLineOptions(argc, argv);
+  if (!Compilations) {
+    std::string ErrorMessage;
+    if (!BuildPath.empty()) {
+      Compilations.reset(
+         CompilationDatabase::autoDetectFromDirectory(BuildPath, ErrorMessage));
+    } else {
+      Compilations.reset(CompilationDatabase::autoDetectFromSource(
+          SourcePaths[0], ErrorMessage));
     }
-    ClangTool Tool(*Compilations, SourcePaths);
-    return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+    if (!Compilations)
+      llvm::report_fatal_error(ErrorMessage);
   }
+  ClangTool Tool(*Compilations, SourcePaths);
+  return Tool.run(newFrontendActionFactory<clang::SyntaxOnlyAction>());
+}
 </pre>
 </p>
 
@@ -155,7 +165,7 @@
 <pre>
   $ cd /path/to/source/llvm
   $ export BD=/path/to/build/llvm
-  $ $BD/bin/clang-check . tools/clang/tools/clang-check/ClangCheck.cpp -- \
+  $ $BD/bin/clang-check tools/clang/tools/clang-check/ClangCheck.cpp -- \
     clang++ -D__STDC_CONSTANT_MACROS -D__STDC_LIMIT_MACROS \
     -Itools/clang/include -I$BD/include -Iinclude -Itools/clang/lib/Headers -c
 </pre>
@@ -176,10 +186,21 @@
 <pre>
   $ cd /path/to/source/llvm
   $ export BD=/path/to/build/llvm
-  $ $BD/bin/clang-check $BD tools/clang/tools/clang-check/ClangCheck.cpp
+  $ $BD/bin/clang-check -p $BD tools/clang/tools/clang-check/ClangCheck.cpp
 </pre>
 </p>
 
+<h3 id="builtin">Builtin includes.</h3>
+<p>Clang tools need their builtin headers and search for them the same way clang
+does. Thus, the default location to look for builtin headers is in a path
+$(dirname /path/to/tool)/../lib/clang/3.2/include relative to the tool
+binary. This works out-of-the-box for tools running from llvm's toplevel
+binary directory after building clang-headers, or if the tool is running
+from the binary directory of a clang install next to the clang binary.</p>
+
+<p>Tips: if your tool fails to find stddef.h or similar headers, call
+the tool with -v and look at the search paths it looks through.</p>
+
 <h3 id="linking">Linking.</h3>
 <p>Please note that this presents the linking requirements at the time of this
 writing. For the most up-to-date information, look at one of the tools'