clang/Frontend/FrontendOptions.h

0001 //===- FrontendOptions.h ----------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLVM_CLANG_FRONTEND_FRONTENDOPTIONS_H
0010 #define LLVM_CLANG_FRONTEND_FRONTENDOPTIONS_H
0011
0012 #include "clang/AST/ASTDumperUtils.h"
0013 #include "clang/Basic/LangStandard.h"
0014 #include "clang/Frontend/CommandLineSourceLoc.h"
0015 #include "clang/Sema/CodeCompleteOptions.h"
0016 #include "clang/Serialization/ModuleFileExtension.h"
0017 #include "llvm/ADT/StringRef.h"
0018 #include "llvm/Support/Compiler.h"
0019 #include "llvm/Support/MemoryBuffer.h"
0020 #include <cassert>
0021 #include <map>
0022 #include <memory>
0023 #include <optional>
0024 #include <string>
0025 #include <vector>
0026
0027 namespace llvm {
0028
0029 class MemoryBuffer;
0030
0031 } // namespace llvm
0032
0033 namespace clang {
0034
0035 namespace frontend {
0036
0037 enum ActionKind {
0038   /// Parse ASTs and list Decl nodes.
0039   ASTDeclList,
0040
0041   /// Parse ASTs and dump them.
0042   ASTDump,
0043
0044   /// Parse ASTs and print them.
0045   ASTPrint,
0046
0047   /// Parse ASTs and view them in Graphviz.
0048   ASTView,
0049
0050   /// Dump the compiler configuration.
0051   DumpCompilerOptions,
0052
0053   /// Dump out raw tokens.
0054   DumpRawTokens,
0055
0056   /// Dump out preprocessed tokens.
0057   DumpTokens,
0058
0059   /// Emit a .s file.
0060   EmitAssembly,
0061
0062   /// Emit a .bc file.
0063   EmitBC,
0064
0065   /// Translate input source into HTML.
0066   EmitHTML,
0067
0068   /// Emit a .cir file
0069   EmitCIR,
0070
0071   /// Emit a .ll file.
0072   EmitLLVM,
0073
0074   /// Generate LLVM IR, but do not emit anything.
0075   EmitLLVMOnly,
0076
0077   /// Generate machine code, but don't emit anything.
0078   EmitCodeGenOnly,
0079
0080   /// Emit a .o file.
0081   EmitObj,
0082
0083   // Extract API information
0084   ExtractAPI,
0085
0086   /// Parse and apply any fixits to the source.
0087   FixIt,
0088
0089   /// Generate pre-compiled module from a module map.
0090   GenerateModule,
0091
0092   /// Generate pre-compiled module from a standard C++ module interface unit.
0093   GenerateModuleInterface,
0094
0095   /// Generate reduced module interface for a standard C++ module interface
0096   /// unit.
0097   GenerateReducedModuleInterface,
0098
0099   /// Generate a C++20 header unit module from a header file.
0100   GenerateHeaderUnit,
0101
0102   /// Generate pre-compiled header.
0103   GeneratePCH,
0104
0105   /// Generate Interface Stub Files.
0106   GenerateInterfaceStubs,
0107
0108   /// Only execute frontend initialization.
0109   InitOnly,
0110
0111   /// Dump information about a module file.
0112   ModuleFileInfo,
0113
0114   /// Load and verify that a PCH file is usable.
0115   VerifyPCH,
0116
0117   /// Parse and perform semantic analysis.
0118   ParseSyntaxOnly,
0119
0120   /// Run a plugin action, \see ActionName.
0121   PluginAction,
0122
0123   /// Print the "preamble" of the input file
0124   PrintPreamble,
0125
0126   /// -E mode.
0127   PrintPreprocessedInput,
0128
0129   /// Expand macros but not \#includes.
0130   RewriteMacros,
0131
0132   /// ObjC->C Rewriter.
0133   RewriteObjC,
0134
0135   /// Rewriter playground
0136   RewriteTest,
0137
0138   /// Run one or more source code analyses.
0139   RunAnalysis,
0140
0141   /// Dump template instantiations
0142   TemplightDump,
0143
0144   /// Run migrator.
0145   MigrateSource,
0146
0147   /// Just lex, no output.
0148   RunPreprocessorOnly,
0149
0150   /// Print the output of the dependency directives source minimizer.
0151   PrintDependencyDirectivesSourceMinimizerOutput
0152 };
0153
0154 } // namespace frontend
0155
0156 /// The kind of a file that we've been handed as an input.
0157 class InputKind {
0158 public:
0159   /// The input file format.
0160   enum Format {
0161     Source,
0162     ModuleMap,
0163     Precompiled
0164   };
0165
0166   // If we are building a header unit, what kind it is; this affects whether
0167   // we look for the file in the user or system include search paths before
0168   // flagging a missing input.
0169   enum HeaderUnitKind {
0170     HeaderUnit_None,
0171     HeaderUnit_User,
0172     HeaderUnit_System,
0173     HeaderUnit_Abs
0174   };
0175
0176 private:
0177   Language Lang;
0178   LLVM_PREFERRED_TYPE(Format)
0179   unsigned Fmt : 3;
0180   LLVM_PREFERRED_TYPE(bool)
0181   unsigned Preprocessed : 1;
0182   LLVM_PREFERRED_TYPE(HeaderUnitKind)
0183   unsigned HeaderUnit : 3;
0184   LLVM_PREFERRED_TYPE(bool)
0185   unsigned IsHeader : 1;
0186
0187 public:
0188   constexpr InputKind(Language L = Language::Unknown, Format F = Source,
0189                       bool PP = false, HeaderUnitKind HU = HeaderUnit_None,
0190                       bool HD = false)
0191       : Lang(L), Fmt(F), Preprocessed(PP), HeaderUnit(HU), IsHeader(HD) {}
0192
0193   Language getLanguage() const { return static_cast<Language>(Lang); }
0194   Format getFormat() const { return static_cast<Format>(Fmt); }
0195   HeaderUnitKind getHeaderUnitKind() const {
0196     return static_cast<HeaderUnitKind>(HeaderUnit);
0197   }
0198   bool isPreprocessed() const { return Preprocessed; }
0199   bool isHeader() const { return IsHeader; }
0200   bool isHeaderUnit() const { return HeaderUnit != HeaderUnit_None; }
0201
0202   /// Is the input kind fully-unknown?
0203   bool isUnknown() const { return Lang == Language::Unknown && Fmt == Source; }
0204
0205   /// Is the language of the input some dialect of Objective-C?
0206   bool isObjectiveC() const {
0207     return Lang == Language::ObjC || Lang == Language::ObjCXX;
0208   }
0209
0210   InputKind getPreprocessed() const {
0211     return InputKind(getLanguage(), getFormat(), true, getHeaderUnitKind(),
0212                      isHeader());
0213   }
0214
0215   InputKind getHeader() const {
0216     return InputKind(getLanguage(), getFormat(), isPreprocessed(),
0217                      getHeaderUnitKind(), true);
0218   }
0219
0220   InputKind withHeaderUnit(HeaderUnitKind HU) const {
0221     return InputKind(getLanguage(), getFormat(), isPreprocessed(), HU,
0222                      isHeader());
0223   }
0224
0225   InputKind withFormat(Format F) const {
0226     return InputKind(getLanguage(), F, isPreprocessed(), getHeaderUnitKind(),
0227                      isHeader());
0228   }
0229 };
0230
0231 /// An input file for the front end.
0232 class FrontendInputFile {
0233   /// The file name, or "-" to read from standard input.
0234   std::string File;
0235
0236   /// The input, if it comes from a buffer rather than a file. This object
0237   /// does not own the buffer, and the caller is responsible for ensuring
0238   /// that it outlives any users.
0239   std::optional<llvm::MemoryBufferRef> Buffer;
0240
0241   /// The kind of input, e.g., C source, AST file, LLVM IR.
0242   InputKind Kind;
0243
0244   /// Whether we're dealing with a 'system' input (vs. a 'user' input).
0245   bool IsSystem = false;
0246
0247 public:
0248   FrontendInputFile() = default;
0249   FrontendInputFile(StringRef File, InputKind Kind, bool IsSystem = false)
0250       : File(File.str()), Kind(Kind), IsSystem(IsSystem) {}
0251   FrontendInputFile(llvm::MemoryBufferRef Buffer, InputKind Kind,
0252                     bool IsSystem = false)
0253       : Buffer(Buffer), Kind(Kind), IsSystem(IsSystem) {}
0254
0255   InputKind getKind() const { return Kind; }
0256   bool isSystem() const { return IsSystem; }
0257
0258   bool isEmpty() const { return File.empty() && Buffer == std::nullopt; }
0259   bool isFile() const { return !isBuffer(); }
0260   bool isBuffer() const { return Buffer != std::nullopt; }
0261   bool isPreprocessed() const { return Kind.isPreprocessed(); }
0262   bool isHeader() const { return Kind.isHeader(); }
0263   InputKind::HeaderUnitKind getHeaderUnitKind() const {
0264     return Kind.getHeaderUnitKind();
0265   }
0266
0267   StringRef getFile() const {
0268     assert(isFile());
0269     return File;
0270   }
0271
0272   llvm::MemoryBufferRef getBuffer() const {
0273     assert(isBuffer());
0274     return *Buffer;
0275   }
0276 };
0277
0278 /// FrontendOptions - Options for controlling the behavior of the frontend.
0279 class FrontendOptions {
0280 public:
0281   /// Disable memory freeing on exit.
0282   LLVM_PREFERRED_TYPE(bool)
0283   unsigned DisableFree : 1;
0284
0285   /// When generating PCH files, instruct the AST writer to create relocatable
0286   /// PCH files.
0287   LLVM_PREFERRED_TYPE(bool)
0288   unsigned RelocatablePCH : 1;
0289
0290   /// Show the -help text.
0291   LLVM_PREFERRED_TYPE(bool)
0292   unsigned ShowHelp : 1;
0293
0294   /// Show frontend performance metrics and statistics.
0295   LLVM_PREFERRED_TYPE(bool)
0296   unsigned ShowStats : 1;
0297
0298   LLVM_PREFERRED_TYPE(bool)
0299   unsigned AppendStats : 1;
0300
0301   /// print the supported cpus for the current target
0302   LLVM_PREFERRED_TYPE(bool)
0303   unsigned PrintSupportedCPUs : 1;
0304
0305   /// Print the supported extensions for the current target.
0306   LLVM_PREFERRED_TYPE(bool)
0307   unsigned PrintSupportedExtensions : 1;
0308
0309   /// Print the extensions enabled for the current target.
0310   LLVM_PREFERRED_TYPE(bool)
0311   unsigned PrintEnabledExtensions : 1;
0312
0313   /// Show the -version text.
0314   LLVM_PREFERRED_TYPE(bool)
0315   unsigned ShowVersion : 1;
0316
0317   /// Apply fixes even if there are unfixable errors.
0318   LLVM_PREFERRED_TYPE(bool)
0319   unsigned FixWhatYouCan : 1;
0320
0321   /// Apply fixes only for warnings.
0322   LLVM_PREFERRED_TYPE(bool)
0323   unsigned FixOnlyWarnings : 1;
0324
0325   /// Apply fixes and recompile.
0326   LLVM_PREFERRED_TYPE(bool)
0327   unsigned FixAndRecompile : 1;
0328
0329   /// Apply fixes to temporary files.
0330   LLVM_PREFERRED_TYPE(bool)
0331   unsigned FixToTemporaries : 1;
0332
0333   /// Emit ARC errors even if the migrator can fix them.
0334   LLVM_PREFERRED_TYPE(bool)
0335   unsigned ARCMTMigrateEmitARCErrors : 1;
0336
0337   /// Skip over function bodies to speed up parsing in cases you do not need
0338   /// them (e.g. with code completion).
0339   LLVM_PREFERRED_TYPE(bool)
0340   unsigned SkipFunctionBodies : 1;
0341
0342   /// Whether we can use the global module index if available.
0343   LLVM_PREFERRED_TYPE(bool)
0344   unsigned UseGlobalModuleIndex : 1;
0345
0346   /// Whether we can generate the global module index if needed.
0347   LLVM_PREFERRED_TYPE(bool)
0348   unsigned GenerateGlobalModuleIndex : 1;
0349
0350   /// Whether we include declaration dumps in AST dumps.
0351   LLVM_PREFERRED_TYPE(bool)
0352   unsigned ASTDumpDecls : 1;
0353
0354   /// Whether we deserialize all decls when forming AST dumps.
0355   LLVM_PREFERRED_TYPE(bool)
0356   unsigned ASTDumpAll : 1;
0357
0358   /// Whether we include lookup table dumps in AST dumps.
0359   LLVM_PREFERRED_TYPE(bool)
0360   unsigned ASTDumpLookups : 1;
0361
0362   /// Whether we include declaration type dumps in AST dumps.
0363   LLVM_PREFERRED_TYPE(bool)
0364   unsigned ASTDumpDeclTypes : 1;
0365
0366   /// Whether we are performing an implicit module build.
0367   LLVM_PREFERRED_TYPE(bool)
0368   unsigned BuildingImplicitModule : 1;
0369
0370   /// Whether to use a filesystem lock when building implicit modules.
0371   LLVM_PREFERRED_TYPE(bool)
0372   unsigned BuildingImplicitModuleUsesLock : 1;
0373
0374   /// Whether we should embed all used files into the PCM file.
0375   LLVM_PREFERRED_TYPE(bool)
0376   unsigned ModulesEmbedAllFiles : 1;
0377
0378   /// Whether timestamps should be written to the produced PCH file.
0379   LLVM_PREFERRED_TYPE(bool)
0380   unsigned IncludeTimestamps : 1;
0381
0382   /// Should a temporary file be used during compilation.
0383   LLVM_PREFERRED_TYPE(bool)
0384   unsigned UseTemporary : 1;
0385
0386   /// When using -emit-module, treat the modulemap as a system module.
0387   LLVM_PREFERRED_TYPE(bool)
0388   unsigned IsSystemModule : 1;
0389
0390   /// Output (and read) PCM files regardless of compiler errors.
0391   LLVM_PREFERRED_TYPE(bool)
0392   unsigned AllowPCMWithCompilerErrors : 1;
0393
0394   /// Whether to share the FileManager when building modules.
0395   LLVM_PREFERRED_TYPE(bool)
0396   unsigned ModulesShareFileManager : 1;
0397
0398   /// Whether to emit symbol graph files as a side effect of compilation.
0399   LLVM_PREFERRED_TYPE(bool)
0400   unsigned EmitSymbolGraph : 1;
0401
0402   /// Whether to emit additional symbol graphs for extended modules.
0403   LLVM_PREFERRED_TYPE(bool)
0404   unsigned EmitExtensionSymbolGraphs : 1;
0405
0406   /// Whether to emit symbol labels for testing in generated symbol graphs
0407   LLVM_PREFERRED_TYPE(bool)
0408   unsigned EmitSymbolGraphSymbolLabelsForTesting : 1;
0409
0410   /// Whether to emit symbol labels for testing in generated symbol graphs
0411   LLVM_PREFERRED_TYPE(bool)
0412   unsigned EmitPrettySymbolGraphs : 1;
0413
0414   /// Whether to generate reduced BMI for C++20 named modules.
0415   LLVM_PREFERRED_TYPE(bool)
0416   unsigned GenReducedBMI : 1;
0417
0418   /// Use Clang IR pipeline to emit code
0419   LLVM_PREFERRED_TYPE(bool)
0420   unsigned UseClangIRPipeline : 1;
0421
0422   CodeCompleteOptions CodeCompleteOpts;
0423
0424   /// Specifies the output format of the AST.
0425   ASTDumpOutputFormat ASTDumpFormat = ADOF_Default;
0426
0427   enum {
0428     ARCMT_None,
0429     ARCMT_Check,
0430     ARCMT_Modify,
0431     ARCMT_Migrate
0432   } ARCMTAction = ARCMT_None;
0433
0434   enum {
0435     ObjCMT_None = 0,
0436
0437     /// Enable migration to modern ObjC literals.
0438     ObjCMT_Literals = 0x1,
0439
0440     /// Enable migration to modern ObjC subscripting.
0441     ObjCMT_Subscripting = 0x2,
0442
0443     /// Enable migration to modern ObjC readonly property.
0444     ObjCMT_ReadonlyProperty = 0x4,
0445
0446     /// Enable migration to modern ObjC readwrite property.
0447     ObjCMT_ReadwriteProperty = 0x8,
0448
0449     /// Enable migration to modern ObjC property.
0450     ObjCMT_Property = (ObjCMT_ReadonlyProperty | ObjCMT_ReadwriteProperty),
0451
0452     /// Enable annotation of ObjCMethods of all kinds.
0453     ObjCMT_Annotation = 0x10,
0454
0455     /// Enable migration of ObjC methods to 'instancetype'.
0456     ObjCMT_Instancetype = 0x20,
0457
0458     /// Enable migration to NS_ENUM/NS_OPTIONS macros.
0459     ObjCMT_NsMacros = 0x40,
0460
0461     /// Enable migration to add conforming protocols.
0462     ObjCMT_ProtocolConformance = 0x80,
0463
0464     /// prefer 'atomic' property over 'nonatomic'.
0465     ObjCMT_AtomicProperty = 0x100,
0466
0467     /// annotate property with NS_RETURNS_INNER_POINTER
0468     ObjCMT_ReturnsInnerPointerProperty = 0x200,
0469
0470     /// use NS_NONATOMIC_IOSONLY for property 'atomic' attribute
0471     ObjCMT_NsAtomicIOSOnlyProperty = 0x400,
0472
0473     /// Enable inferring NS_DESIGNATED_INITIALIZER for ObjC methods.
0474     ObjCMT_DesignatedInitializer = 0x800,
0475
0476     /// Enable converting setter/getter expressions to property-dot syntx.
0477     ObjCMT_PropertyDotSyntax = 0x1000,
0478
0479     ObjCMT_MigrateDecls = (ObjCMT_ReadonlyProperty | ObjCMT_ReadwriteProperty |
0480                            ObjCMT_Annotation | ObjCMT_Instancetype |
0481                            ObjCMT_NsMacros | ObjCMT_ProtocolConformance |
0482                            ObjCMT_NsAtomicIOSOnlyProperty |
0483                            ObjCMT_DesignatedInitializer),
0484     ObjCMT_MigrateAll = (ObjCMT_Literals | ObjCMT_Subscripting |
0485                          ObjCMT_MigrateDecls | ObjCMT_PropertyDotSyntax)
0486   };
0487   unsigned ObjCMTAction = ObjCMT_None;
0488   std::string ObjCMTAllowListPath;
0489
0490   std::string MTMigrateDir;
0491   std::string ARCMTMigrateReportOut;
0492
0493   /// The input kind, either specified via -x argument or deduced from the input
0494   /// file name.
0495   InputKind DashX;
0496
0497   /// The input files and their types.
0498   SmallVector<FrontendInputFile, 0> Inputs;
0499
0500   /// When the input is a module map, the original module map file from which
0501   /// that map was inferred, if any (for umbrella modules).
0502   std::string OriginalModuleMap;
0503
0504   /// The output file, if any.
0505   std::string OutputFile;
0506
0507   /// If given, the new suffix for fix-it rewritten files.
0508   std::string FixItSuffix;
0509
0510   /// If given, filter dumped AST Decl nodes by this substring.
0511   std::string ASTDumpFilter;
0512
0513   /// If given, enable code completion at the provided location.
0514   ParsedSourceLocation CodeCompletionAt;
0515
0516   /// The frontend action to perform.
0517   frontend::ActionKind ProgramAction = frontend::ParseSyntaxOnly;
0518
0519   /// The name of the action to run when using a plugin action.
0520   std::string ActionName;
0521
0522   // Currently this is only used as part of the `-extract-api` action.
0523   /// The name of the product the input files belong too.
0524   std::string ProductName;
0525
0526   // Currently this is only used as part of the `-extract-api` action.
0527   // A comma separated list of files providing a list of APIs to
0528   // ignore when extracting documentation.
0529   std::vector<std::string> ExtractAPIIgnoresFileList;
0530
0531   // Location of output directory where symbol graph information would
0532   // be dumped. This overrides regular -o output file specification
0533   std::string SymbolGraphOutputDir;
0534
0535   /// Args to pass to the plugins
0536   std::map<std::string, std::vector<std::string>> PluginArgs;
0537
0538   /// The list of plugin actions to run in addition to the normal action.
0539   std::vector<std::string> AddPluginActions;
0540
0541   /// The list of plugins to load.
0542   std::vector<std::string> Plugins;
0543
0544   /// The list of module file extensions.
0545   std::vector<std::shared_ptr<ModuleFileExtension>> ModuleFileExtensions;
0546
0547   /// The list of module map files to load before processing the input.
0548   std::vector<std::string> ModuleMapFiles;
0549
0550   /// The list of additional prebuilt module files to load before
0551   /// processing the input.
0552   std::vector<std::string> ModuleFiles;
0553
0554   /// The list of files to embed into the compiled module file.
0555   std::vector<std::string> ModulesEmbedFiles;
0556
0557   /// The list of AST files to merge.
0558   std::vector<std::string> ASTMergeFiles;
0559
0560   /// A list of arguments to forward to LLVM's option processing; this
0561   /// should only be used for debugging and experimental features.
0562   std::vector<std::string> LLVMArgs;
0563
0564   /// File name of the file that will provide record layouts
0565   /// (in the format produced by -fdump-record-layouts).
0566   std::string OverrideRecordLayoutsFile;
0567
0568   /// Auxiliary triple for CUDA/HIP compilation.
0569   std::string AuxTriple;
0570
0571   /// Auxiliary target CPU for CUDA/HIP compilation.
0572   std::optional<std::string> AuxTargetCPU;
0573
0574   /// Auxiliary target features for CUDA/HIP compilation.
0575   std::optional<std::vector<std::string>> AuxTargetFeatures;
0576
0577   /// Filename to write statistics to.
0578   std::string StatsFile;
0579
0580   /// Minimum time granularity (in microseconds) traced by time profiler.
0581   unsigned TimeTraceGranularity;
0582
0583   /// Make time trace capture verbose event details (e.g. source filenames).
0584   /// This can increase the size of the output by 2-3 times.
0585   LLVM_PREFERRED_TYPE(bool)
0586   unsigned TimeTraceVerbose : 1;
0587
0588   /// Path which stores the output files for -ftime-trace
0589   std::string TimeTracePath;
0590
0591   /// Output Path for module output file.
0592   std::string ModuleOutputPath;
0593
0594 public:
0595   FrontendOptions()
0596       : DisableFree(false), RelocatablePCH(false), ShowHelp(false),
0597         ShowStats(false), AppendStats(false), ShowVersion(false),
0598         FixWhatYouCan(false), FixOnlyWarnings(false), FixAndRecompile(false),
0599         FixToTemporaries(false), ARCMTMigrateEmitARCErrors(false),
0600         SkipFunctionBodies(false), UseGlobalModuleIndex(true),
0601         GenerateGlobalModuleIndex(true), ASTDumpDecls(false),
0602         ASTDumpLookups(false), BuildingImplicitModule(false),
0603         BuildingImplicitModuleUsesLock(true), ModulesEmbedAllFiles(false),
0604         IncludeTimestamps(true), UseTemporary(true),
0605         AllowPCMWithCompilerErrors(false), ModulesShareFileManager(true),
0606         EmitSymbolGraph(false), EmitExtensionSymbolGraphs(false),
0607         EmitSymbolGraphSymbolLabelsForTesting(false),
0608         EmitPrettySymbolGraphs(false), GenReducedBMI(false),
0609         UseClangIRPipeline(false), TimeTraceGranularity(500),
0610         TimeTraceVerbose(false) {}
0611
0612   /// getInputKindForExtension - Return the appropriate input kind for a file
0613   /// extension. For example, "c" would return Language::C.
0614   ///
0615   /// \return The input kind for the extension, or Language::Unknown if the
0616   /// extension is not recognized.
0617   static InputKind getInputKindForExtension(StringRef Extension);
0618 };
0619
0620 } // namespace clang
0621
0622 #endif // LLVM_CLANG_FRONTEND_FRONTENDOPTIONS_H