xref: /freebsd/contrib/llvm-project/clang/include/clang/Frontend/FrontendOptions.h (revision 0fca6ea1d4eea4c934cfff25ac9ee8ad6fe95583) 
1 //===- FrontendOptions.h ----------------------------------------*- 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 #ifndef LLVM_CLANG_FRONTEND_FRONTENDOPTIONS_H
10 #define LLVM_CLANG_FRONTEND_FRONTENDOPTIONS_H
11 
12 #include "clang/AST/ASTDumperUtils.h"
13 #include "clang/Basic/LangStandard.h"
14 #include "clang/Frontend/CommandLineSourceLoc.h"
15 #include "clang/Sema/CodeCompleteOptions.h"
16 #include "clang/Serialization/ModuleFileExtension.h"
17 #include "llvm/ADT/StringRef.h"
18 #include "llvm/Support/Compiler.h"
19 #include "llvm/Support/MemoryBuffer.h"
20 #include <cassert>
21 #include <map>
22 #include <memory>
23 #include <optional>
24 #include <string>
25 #include <vector>
26 
27 namespace llvm {
28 
29 class MemoryBuffer;
30 
31 } // namespace llvm
32 
33 namespace clang {
34 
35 namespace frontend {
36 
37 enum ActionKind {
38   /// Parse ASTs and list Decl nodes.
39   ASTDeclList,
40 
41   /// Parse ASTs and dump them.
42   ASTDump,
43 
44   /// Parse ASTs and print them.
45   ASTPrint,
46 
47   /// Parse ASTs and view them in Graphviz.
48   ASTView,
49 
50   /// Dump the compiler configuration.
51   DumpCompilerOptions,
52 
53   /// Dump out raw tokens.
54   DumpRawTokens,
55 
56   /// Dump out preprocessed tokens.
57   DumpTokens,
58 
59   /// Emit a .s file.
60   EmitAssembly,
61 
62   /// Emit a .bc file.
63   EmitBC,
64 
65   /// Translate input source into HTML.
66   EmitHTML,
67 
68   /// Emit a .cir file
69   EmitCIR,
70 
71   /// Emit a .ll file.
72   EmitLLVM,
73 
74   /// Generate LLVM IR, but do not emit anything.
75   EmitLLVMOnly,
76 
77   /// Generate machine code, but don't emit anything.
78   EmitCodeGenOnly,
79 
80   /// Emit a .o file.
81   EmitObj,
82 
83   // Extract API information
84   ExtractAPI,
85 
86   /// Parse and apply any fixits to the source.
87   FixIt,
88 
89   /// Generate pre-compiled module from a module map.
90   GenerateModule,
91 
92   /// Generate pre-compiled module from a standard C++ module interface unit.
93   GenerateModuleInterface,
94 
95   /// Generate reduced module interface for a standard C++ module interface
96   /// unit.
97   GenerateReducedModuleInterface,
98 
99   /// Generate a C++20 header unit module from a header file.
100   GenerateHeaderUnit,
101 
102   /// Generate pre-compiled header.
103   GeneratePCH,
104 
105   /// Generate Interface Stub Files.
106   GenerateInterfaceStubs,
107 
108   /// Only execute frontend initialization.
109   InitOnly,
110 
111   /// Dump information about a module file.
112   ModuleFileInfo,
113 
114   /// Load and verify that a PCH file is usable.
115   VerifyPCH,
116 
117   /// Parse and perform semantic analysis.
118   ParseSyntaxOnly,
119 
120   /// Run a plugin action, \see ActionName.
121   PluginAction,
122 
123   /// Print the "preamble" of the input file
124   PrintPreamble,
125 
126   /// -E mode.
127   PrintPreprocessedInput,
128 
129   /// Expand macros but not \#includes.
130   RewriteMacros,
131 
132   /// ObjC->C Rewriter.
133   RewriteObjC,
134 
135   /// Rewriter playground
136   RewriteTest,
137 
138   /// Run one or more source code analyses.
139   RunAnalysis,
140 
141   /// Dump template instantiations
142   TemplightDump,
143 
144   /// Run migrator.
145   MigrateSource,
146 
147   /// Just lex, no output.
148   RunPreprocessorOnly,
149 
150   /// Print the output of the dependency directives source minimizer.
151   PrintDependencyDirectivesSourceMinimizerOutput
152 };
153 
154 } // namespace frontend
155 
156 /// The kind of a file that we've been handed as an input.
157 class InputKind {
158 public:
159   /// The input file format.
160   enum Format {
161     Source,
162     ModuleMap,
163     Precompiled
164   };
165 
166   // If we are building a header unit, what kind it is; this affects whether
167   // we look for the file in the user or system include search paths before
168   // flagging a missing input.
169   enum HeaderUnitKind {
170     HeaderUnit_None,
171     HeaderUnit_User,
172     HeaderUnit_System,
173     HeaderUnit_Abs
174   };
175 
176 private:
177   Language Lang;
178   LLVM_PREFERRED_TYPE(Format)
179   unsigned Fmt : 3;
180   LLVM_PREFERRED_TYPE(bool)
181   unsigned Preprocessed : 1;
182   LLVM_PREFERRED_TYPE(HeaderUnitKind)
183   unsigned HeaderUnit : 3;
184   LLVM_PREFERRED_TYPE(bool)
185   unsigned IsHeader : 1;
186 
187 public:
188   constexpr InputKind(Language L = Language::Unknown, Format F = Source,
189                       bool PP = false, HeaderUnitKind HU = HeaderUnit_None,
190                       bool HD = false)
Lang(L)191       : Lang(L), Fmt(F), Preprocessed(PP), HeaderUnit(HU), IsHeader(HD) {}
192 
getLanguage()193   Language getLanguage() const { return static_cast<Language>(Lang); }
getFormat()194   Format getFormat() const { return static_cast<Format>(Fmt); }
getHeaderUnitKind()195   HeaderUnitKind getHeaderUnitKind() const {
196     return static_cast<HeaderUnitKind>(HeaderUnit);
197   }
isPreprocessed()198   bool isPreprocessed() const { return Preprocessed; }
isHeader()199   bool isHeader() const { return IsHeader; }
isHeaderUnit()200   bool isHeaderUnit() const { return HeaderUnit != HeaderUnit_None; }
201 
202   /// Is the input kind fully-unknown?
isUnknown()203   bool isUnknown() const { return Lang == Language::Unknown && Fmt == Source; }
204 
205   /// Is the language of the input some dialect of Objective-C?
isObjectiveC()206   bool isObjectiveC() const {
207     return Lang == Language::ObjC || Lang == Language::ObjCXX;
208   }
209 
getPreprocessed()210   InputKind getPreprocessed() const {
211     return InputKind(getLanguage(), getFormat(), true, getHeaderUnitKind(),
212                      isHeader());
213   }
214 
getHeader()215   InputKind getHeader() const {
216     return InputKind(getLanguage(), getFormat(), isPreprocessed(),
217                      getHeaderUnitKind(), true);
218   }
219 
withHeaderUnit(HeaderUnitKind HU)220   InputKind withHeaderUnit(HeaderUnitKind HU) const {
221     return InputKind(getLanguage(), getFormat(), isPreprocessed(), HU,
222                      isHeader());
223   }
224 
withFormat(Format F)225   InputKind withFormat(Format F) const {
226     return InputKind(getLanguage(), F, isPreprocessed(), getHeaderUnitKind(),
227                      isHeader());
228   }
229 };
230 
231 /// An input file for the front end.
232 class FrontendInputFile {
233   /// The file name, or "-" to read from standard input.
234   std::string File;
235 
236   /// The input, if it comes from a buffer rather than a file. This object
237   /// does not own the buffer, and the caller is responsible for ensuring
238   /// that it outlives any users.
239   std::optional<llvm::MemoryBufferRef> Buffer;
240 
241   /// The kind of input, e.g., C source, AST file, LLVM IR.
242   InputKind Kind;
243 
244   /// Whether we're dealing with a 'system' input (vs. a 'user' input).
245   bool IsSystem = false;
246 
247 public:
248   FrontendInputFile() = default;
249   FrontendInputFile(StringRef File, InputKind Kind, bool IsSystem = false)
250       : File(File.str()), Kind(Kind), IsSystem(IsSystem) {}
251   FrontendInputFile(llvm::MemoryBufferRef Buffer, InputKind Kind,
252                     bool IsSystem = false)
Buffer(Buffer)253       : Buffer(Buffer), Kind(Kind), IsSystem(IsSystem) {}
254 
getKind()255   InputKind getKind() const { return Kind; }
isSystem()256   bool isSystem() const { return IsSystem; }
257 
isEmpty()258   bool isEmpty() const { return File.empty() && Buffer == std::nullopt; }
isFile()259   bool isFile() const { return !isBuffer(); }
isBuffer()260   bool isBuffer() const { return Buffer != std::nullopt; }
isPreprocessed()261   bool isPreprocessed() const { return Kind.isPreprocessed(); }
isHeader()262   bool isHeader() const { return Kind.isHeader(); }
getHeaderUnitKind()263   InputKind::HeaderUnitKind getHeaderUnitKind() const {
264     return Kind.getHeaderUnitKind();
265   }
266 
getFile()267   StringRef getFile() const {
268     assert(isFile());
269     return File;
270   }
271 
getBuffer()272   llvm::MemoryBufferRef getBuffer() const {
273     assert(isBuffer());
274     return *Buffer;
275   }
276 };
277 
278 /// FrontendOptions - Options for controlling the behavior of the frontend.
279 class FrontendOptions {
280 public:
281   /// Disable memory freeing on exit.
282   LLVM_PREFERRED_TYPE(bool)
283   unsigned DisableFree : 1;
284 
285   /// When generating PCH files, instruct the AST writer to create relocatable
286   /// PCH files.
287   LLVM_PREFERRED_TYPE(bool)
288   unsigned RelocatablePCH : 1;
289 
290   /// Show the -help text.
291   LLVM_PREFERRED_TYPE(bool)
292   unsigned ShowHelp : 1;
293 
294   /// Show frontend performance metrics and statistics.
295   LLVM_PREFERRED_TYPE(bool)
296   unsigned ShowStats : 1;
297 
298   LLVM_PREFERRED_TYPE(bool)
299   unsigned AppendStats : 1;
300 
301   /// print the supported cpus for the current target
302   LLVM_PREFERRED_TYPE(bool)
303   unsigned PrintSupportedCPUs : 1;
304 
305   /// Print the supported extensions for the current target.
306   LLVM_PREFERRED_TYPE(bool)
307   unsigned PrintSupportedExtensions : 1;
308 
309   /// Print the extensions enabled for the current target.
310   LLVM_PREFERRED_TYPE(bool)
311   unsigned PrintEnabledExtensions : 1;
312 
313   /// Show the -version text.
314   LLVM_PREFERRED_TYPE(bool)
315   unsigned ShowVersion : 1;
316 
317   /// Apply fixes even if there are unfixable errors.
318   LLVM_PREFERRED_TYPE(bool)
319   unsigned FixWhatYouCan : 1;
320 
321   /// Apply fixes only for warnings.
322   LLVM_PREFERRED_TYPE(bool)
323   unsigned FixOnlyWarnings : 1;
324 
325   /// Apply fixes and recompile.
326   LLVM_PREFERRED_TYPE(bool)
327   unsigned FixAndRecompile : 1;
328 
329   /// Apply fixes to temporary files.
330   LLVM_PREFERRED_TYPE(bool)
331   unsigned FixToTemporaries : 1;
332 
333   /// Emit ARC errors even if the migrator can fix them.
334   LLVM_PREFERRED_TYPE(bool)
335   unsigned ARCMTMigrateEmitARCErrors : 1;
336 
337   /// Skip over function bodies to speed up parsing in cases you do not need
338   /// them (e.g. with code completion).
339   LLVM_PREFERRED_TYPE(bool)
340   unsigned SkipFunctionBodies : 1;
341 
342   /// Whether we can use the global module index if available.
343   LLVM_PREFERRED_TYPE(bool)
344   unsigned UseGlobalModuleIndex : 1;
345 
346   /// Whether we can generate the global module index if needed.
347   LLVM_PREFERRED_TYPE(bool)
348   unsigned GenerateGlobalModuleIndex : 1;
349 
350   /// Whether we include declaration dumps in AST dumps.
351   LLVM_PREFERRED_TYPE(bool)
352   unsigned ASTDumpDecls : 1;
353 
354   /// Whether we deserialize all decls when forming AST dumps.
355   LLVM_PREFERRED_TYPE(bool)
356   unsigned ASTDumpAll : 1;
357 
358   /// Whether we include lookup table dumps in AST dumps.
359   LLVM_PREFERRED_TYPE(bool)
360   unsigned ASTDumpLookups : 1;
361 
362   /// Whether we include declaration type dumps in AST dumps.
363   LLVM_PREFERRED_TYPE(bool)
364   unsigned ASTDumpDeclTypes : 1;
365 
366   /// Whether we are performing an implicit module build.
367   LLVM_PREFERRED_TYPE(bool)
368   unsigned BuildingImplicitModule : 1;
369 
370   /// Whether to use a filesystem lock when building implicit modules.
371   LLVM_PREFERRED_TYPE(bool)
372   unsigned BuildingImplicitModuleUsesLock : 1;
373 
374   /// Whether we should embed all used files into the PCM file.
375   LLVM_PREFERRED_TYPE(bool)
376   unsigned ModulesEmbedAllFiles : 1;
377 
378   /// Whether timestamps should be written to the produced PCH file.
379   LLVM_PREFERRED_TYPE(bool)
380   unsigned IncludeTimestamps : 1;
381 
382   /// Should a temporary file be used during compilation.
383   LLVM_PREFERRED_TYPE(bool)
384   unsigned UseTemporary : 1;
385 
386   /// When using -emit-module, treat the modulemap as a system module.
387   LLVM_PREFERRED_TYPE(bool)
388   unsigned IsSystemModule : 1;
389 
390   /// Output (and read) PCM files regardless of compiler errors.
391   LLVM_PREFERRED_TYPE(bool)
392   unsigned AllowPCMWithCompilerErrors : 1;
393 
394   /// Whether to share the FileManager when building modules.
395   LLVM_PREFERRED_TYPE(bool)
396   unsigned ModulesShareFileManager : 1;
397 
398   /// Whether to emit symbol graph files as a side effect of compilation.
399   LLVM_PREFERRED_TYPE(bool)
400   unsigned EmitSymbolGraph : 1;
401 
402   /// Whether to emit additional symbol graphs for extended modules.
403   LLVM_PREFERRED_TYPE(bool)
404   unsigned EmitExtensionSymbolGraphs : 1;
405 
406   /// Whether to emit symbol labels for testing in generated symbol graphs
407   LLVM_PREFERRED_TYPE(bool)
408   unsigned EmitSymbolGraphSymbolLabelsForTesting : 1;
409 
410   /// Whether to emit symbol labels for testing in generated symbol graphs
411   LLVM_PREFERRED_TYPE(bool)
412   unsigned EmitPrettySymbolGraphs : 1;
413 
414   /// Whether to generate reduced BMI for C++20 named modules.
415   LLVM_PREFERRED_TYPE(bool)
416   unsigned GenReducedBMI : 1;
417 
418   /// Use Clang IR pipeline to emit code
419   LLVM_PREFERRED_TYPE(bool)
420   unsigned UseClangIRPipeline : 1;
421 
422   CodeCompleteOptions CodeCompleteOpts;
423 
424   /// Specifies the output format of the AST.
425   ASTDumpOutputFormat ASTDumpFormat = ADOF_Default;
426 
427   enum {
428     ARCMT_None,
429     ARCMT_Check,
430     ARCMT_Modify,
431     ARCMT_Migrate
432   } ARCMTAction = ARCMT_None;
433 
434   enum {
435     ObjCMT_None = 0,
436 
437     /// Enable migration to modern ObjC literals.
438     ObjCMT_Literals = 0x1,
439 
440     /// Enable migration to modern ObjC subscripting.
441     ObjCMT_Subscripting = 0x2,
442 
443     /// Enable migration to modern ObjC readonly property.
444     ObjCMT_ReadonlyProperty = 0x4,
445 
446     /// Enable migration to modern ObjC readwrite property.
447     ObjCMT_ReadwriteProperty = 0x8,
448 
449     /// Enable migration to modern ObjC property.
450     ObjCMT_Property = (ObjCMT_ReadonlyProperty | ObjCMT_ReadwriteProperty),
451 
452     /// Enable annotation of ObjCMethods of all kinds.
453     ObjCMT_Annotation = 0x10,
454 
455     /// Enable migration of ObjC methods to 'instancetype'.
456     ObjCMT_Instancetype = 0x20,
457 
458     /// Enable migration to NS_ENUM/NS_OPTIONS macros.
459     ObjCMT_NsMacros = 0x40,
460 
461     /// Enable migration to add conforming protocols.
462     ObjCMT_ProtocolConformance = 0x80,
463 
464     /// prefer 'atomic' property over 'nonatomic'.
465     ObjCMT_AtomicProperty = 0x100,
466 
467     /// annotate property with NS_RETURNS_INNER_POINTER
468     ObjCMT_ReturnsInnerPointerProperty = 0x200,
469 
470     /// use NS_NONATOMIC_IOSONLY for property 'atomic' attribute
471     ObjCMT_NsAtomicIOSOnlyProperty = 0x400,
472 
473     /// Enable inferring NS_DESIGNATED_INITIALIZER for ObjC methods.
474     ObjCMT_DesignatedInitializer = 0x800,
475 
476     /// Enable converting setter/getter expressions to property-dot syntx.
477     ObjCMT_PropertyDotSyntax = 0x1000,
478 
479     ObjCMT_MigrateDecls = (ObjCMT_ReadonlyProperty | ObjCMT_ReadwriteProperty |
480                            ObjCMT_Annotation | ObjCMT_Instancetype |
481                            ObjCMT_NsMacros | ObjCMT_ProtocolConformance |
482                            ObjCMT_NsAtomicIOSOnlyProperty |
483                            ObjCMT_DesignatedInitializer),
484     ObjCMT_MigrateAll = (ObjCMT_Literals | ObjCMT_Subscripting |
485                          ObjCMT_MigrateDecls | ObjCMT_PropertyDotSyntax)
486   };
487   unsigned ObjCMTAction = ObjCMT_None;
488   std::string ObjCMTAllowListPath;
489 
490   std::string MTMigrateDir;
491   std::string ARCMTMigrateReportOut;
492 
493   /// The input kind, either specified via -x argument or deduced from the input
494   /// file name.
495   InputKind DashX;
496 
497   /// The input files and their types.
498   SmallVector<FrontendInputFile, 0> Inputs;
499 
500   /// When the input is a module map, the original module map file from which
501   /// that map was inferred, if any (for umbrella modules).
502   std::string OriginalModuleMap;
503 
504   /// The output file, if any.
505   std::string OutputFile;
506 
507   /// If given, the new suffix for fix-it rewritten files.
508   std::string FixItSuffix;
509 
510   /// If given, filter dumped AST Decl nodes by this substring.
511   std::string ASTDumpFilter;
512 
513   /// If given, enable code completion at the provided location.
514   ParsedSourceLocation CodeCompletionAt;
515 
516   /// The frontend action to perform.
517   frontend::ActionKind ProgramAction = frontend::ParseSyntaxOnly;
518 
519   /// The name of the action to run when using a plugin action.
520   std::string ActionName;
521 
522   // Currently this is only used as part of the `-extract-api` action.
523   /// The name of the product the input files belong too.
524   std::string ProductName;
525 
526   // Currently this is only used as part of the `-extract-api` action.
527   // A comma separated list of files providing a list of APIs to
528   // ignore when extracting documentation.
529   std::vector<std::string> ExtractAPIIgnoresFileList;
530 
531   // Location of output directory where symbol graph information would
532   // be dumped. This overrides regular -o output file specification
533   std::string SymbolGraphOutputDir;
534 
535   /// Args to pass to the plugins
536   std::map<std::string, std::vector<std::string>> PluginArgs;
537 
538   /// The list of plugin actions to run in addition to the normal action.
539   std::vector<std::string> AddPluginActions;
540 
541   /// The list of plugins to load.
542   std::vector<std::string> Plugins;
543 
544   /// The list of module file extensions.
545   std::vector<std::shared_ptr<ModuleFileExtension>> ModuleFileExtensions;
546 
547   /// The list of module map files to load before processing the input.
548   std::vector<std::string> ModuleMapFiles;
549 
550   /// The list of additional prebuilt module files to load before
551   /// processing the input.
552   std::vector<std::string> ModuleFiles;
553 
554   /// The list of files to embed into the compiled module file.
555   std::vector<std::string> ModulesEmbedFiles;
556 
557   /// The list of AST files to merge.
558   std::vector<std::string> ASTMergeFiles;
559 
560   /// A list of arguments to forward to LLVM's option processing; this
561   /// should only be used for debugging and experimental features.
562   std::vector<std::string> LLVMArgs;
563 
564   /// File name of the file that will provide record layouts
565   /// (in the format produced by -fdump-record-layouts).
566   std::string OverrideRecordLayoutsFile;
567 
568   /// Auxiliary triple for CUDA/HIP compilation.
569   std::string AuxTriple;
570 
571   /// Auxiliary target CPU for CUDA/HIP compilation.
572   std::optional<std::string> AuxTargetCPU;
573 
574   /// Auxiliary target features for CUDA/HIP compilation.
575   std::optional<std::vector<std::string>> AuxTargetFeatures;
576 
577   /// Filename to write statistics to.
578   std::string StatsFile;
579 
580   /// Minimum time granularity (in microseconds) traced by time profiler.
581   unsigned TimeTraceGranularity;
582 
583   /// Make time trace capture verbose event details (e.g. source filenames).
584   /// This can increase the size of the output by 2-3 times.
585   LLVM_PREFERRED_TYPE(bool)
586   unsigned TimeTraceVerbose : 1;
587 
588   /// Path which stores the output files for -ftime-trace
589   std::string TimeTracePath;
590 
591   /// Output Path for module output file.
592   std::string ModuleOutputPath;
593 
594 public:
FrontendOptions()595   FrontendOptions()
596       : DisableFree(false), RelocatablePCH(false), ShowHelp(false),
597         ShowStats(false), AppendStats(false), ShowVersion(false),
598         FixWhatYouCan(false), FixOnlyWarnings(false), FixAndRecompile(false),
599         FixToTemporaries(false), ARCMTMigrateEmitARCErrors(false),
600         SkipFunctionBodies(false), UseGlobalModuleIndex(true),
601         GenerateGlobalModuleIndex(true), ASTDumpDecls(false),
602         ASTDumpLookups(false), BuildingImplicitModule(false),
603         BuildingImplicitModuleUsesLock(true), ModulesEmbedAllFiles(false),
604         IncludeTimestamps(true), UseTemporary(true),
605         AllowPCMWithCompilerErrors(false), ModulesShareFileManager(true),
606         EmitSymbolGraph(false), EmitExtensionSymbolGraphs(false),
607         EmitSymbolGraphSymbolLabelsForTesting(false),
608         EmitPrettySymbolGraphs(false), GenReducedBMI(false),
609         UseClangIRPipeline(false), TimeTraceGranularity(500),
610         TimeTraceVerbose(false) {}
611 
612   /// getInputKindForExtension - Return the appropriate input kind for a file
613   /// extension. For example, "c" would return Language::C.
614   ///
615   /// \return The input kind for the extension, or Language::Unknown if the
616   /// extension is not recognized.
617   static InputKind getInputKindForExtension(StringRef Extension);
618 };
619 
620 } // namespace clang
621 
622 #endif // LLVM_CLANG_FRONTEND_FRONTENDOPTIONS_H
623