1 //===- CommonOptionsParser.h - common options for clang tools -*- C++ -*-=====//
2 //
3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4 // See https://llvm.org/LICENSE.txt for license information.
5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6 //
7 //===----------------------------------------------------------------------===//
8 //
9 //  This file implements the CommonOptionsParser class used to parse common
10 //  command-line options for clang tools, so that they can be run as separate
11 //  command-line applications with a consistent common interface for handling
12 //  compilation database and input files.
13 //
14 //  It provides a common subset of command-line options, common algorithm
15 //  for locating a compilation database and source files, and help messages
16 //  for the basic command-line interface.
17 //
18 //  It creates a CompilationDatabase and reads common command-line options.
19 //
20 //  This class uses the Clang Tooling infrastructure, see
21 //    http://clang.llvm.org/docs/HowToSetupToolingForLLVM.html
22 //  for details on setting it up with LLVM source tree.
23 //
24 //===----------------------------------------------------------------------===//
25 
26 #ifndef LLVM_CLANG_TOOLING_COMMONOPTIONSPARSER_H
27 #define LLVM_CLANG_TOOLING_COMMONOPTIONSPARSER_H
28 
29 #include "clang/Tooling/ArgumentsAdjusters.h"
30 #include "clang/Tooling/CompilationDatabase.h"
31 #include "llvm/Support/CommandLine.h"
32 #include "llvm/Support/Error.h"
33 
34 namespace clang {
35 namespace tooling {
36 /// A parser for options common to all command-line Clang tools.
37 ///
38 /// Parses a common subset of command-line arguments, locates and loads a
39 /// compilation commands database and runs a tool with user-specified action. It
40 /// also contains a help message for the common command-line options.
41 ///
42 /// An example of usage:
43 /// \code
44 /// #include "clang/Frontend/FrontendActions.h"
45 /// #include "clang/Tooling/CommonOptionsParser.h"
46 /// #include "clang/Tooling/Tooling.h"
47 /// #include "llvm/Support/CommandLine.h"
48 ///
49 /// using namespace clang::tooling;
50 /// using namespace llvm;
51 ///
52 /// static cl::OptionCategory MyToolCategory("My tool options");
53 /// static cl::extrahelp CommonHelp(CommonOptionsParser::HelpMessage);
54 /// static cl::extrahelp MoreHelp("\nMore help text...\n");
55 /// static cl::opt<bool> YourOwnOption(...);
56 /// ...
57 ///
58 /// int main(int argc, const char **argv) {
59 ///   CommonOptionsParser OptionsParser(argc, argv, MyToolCategory);
60 ///   ClangTool Tool(OptionsParser.getCompilations(),
61 ///                  OptionsParser.getSourcePathList());
62 ///   return Tool.run(newFrontendActionFactory<SyntaxOnlyAction>().get());
63 /// }
64 /// \endcode
65 class CommonOptionsParser {
66 
67 protected:
68   /// Parses command-line, initializes a compilation database.
69   ///
70   /// This constructor can change argc and argv contents, e.g. consume
71   /// command-line options used for creating FixedCompilationDatabase.
72   ///
73   /// All options not belonging to \p Category become hidden.
74   ///
75   /// It also allows calls to set the required number of positional parameters.
76   CommonOptionsParser(
77       int &argc, const char **argv, llvm::cl::OptionCategory &Category,
78       llvm::cl::NumOccurrencesFlag OccurrencesFlag = llvm::cl::OneOrMore,
79       const char *Overview = nullptr);
80 
81 public:
82   /// A factory method that is similar to the above constructor, except
83   /// this returns an error instead exiting the program on error.
84   static llvm::Expected<CommonOptionsParser>
85   create(int &argc, const char **argv, llvm::cl::OptionCategory &Category,
86          llvm::cl::NumOccurrencesFlag OccurrencesFlag = llvm::cl::OneOrMore,
87          const char *Overview = nullptr);
88 
89   /// Returns a reference to the loaded compilations database.
getCompilations()90   CompilationDatabase &getCompilations() {
91     return *Compilations;
92   }
93 
94   /// Returns a list of source file paths to process.
getSourcePathList()95   const std::vector<std::string> &getSourcePathList() const {
96     return SourcePathList;
97   }
98 
99   /// Returns the argument adjuster calculated from "--extra-arg" and
100   //"--extra-arg-before" options.
getArgumentsAdjuster()101   ArgumentsAdjuster getArgumentsAdjuster() { return Adjuster; }
102 
103   static const char *const HelpMessage;
104 
105 private:
106   CommonOptionsParser() = default;
107 
108   llvm::Error init(int &argc, const char **argv,
109                    llvm::cl::OptionCategory &Category,
110                    llvm::cl::NumOccurrencesFlag OccurrencesFlag,
111                    const char *Overview);
112 
113   std::unique_ptr<CompilationDatabase> Compilations;
114   std::vector<std::string> SourcePathList;
115   ArgumentsAdjuster Adjuster;
116 };
117 
118 class ArgumentsAdjustingCompilations : public CompilationDatabase {
119 public:
ArgumentsAdjustingCompilations(std::unique_ptr<CompilationDatabase> Compilations)120   ArgumentsAdjustingCompilations(
121       std::unique_ptr<CompilationDatabase> Compilations)
122       : Compilations(std::move(Compilations)) {}
123 
124   void appendArgumentsAdjuster(ArgumentsAdjuster Adjuster);
125 
126   std::vector<CompileCommand>
127   getCompileCommands(StringRef FilePath) const override;
128 
129   std::vector<std::string> getAllFiles() const override;
130 
131   std::vector<CompileCommand> getAllCompileCommands() const override;
132 
133 private:
134   std::unique_ptr<CompilationDatabase> Compilations;
135   std::vector<ArgumentsAdjuster> Adjusters;
136 
137   std::vector<CompileCommand>
138   adjustCommands(std::vector<CompileCommand> Commands) const;
139 };
140 
141 }  // namespace tooling
142 }  // namespace clang
143 
144 #endif // LLVM_CLANG_TOOLING_COMMONOPTIONSPARSER_H
145