Author: Jan Svoboda Date: 2021-05-04T15:16:32+02:00 New Revision: 00895831ab23f4de2713a6ad529ba48773d067c1
URL: https://github.com/llvm/llvm-project/commit/00895831ab23f4de2713a6ad529ba48773d067c1 DIFF: https://github.com/llvm/llvm-project/commit/00895831ab23f4de2713a6ad529ba48773d067c1.diff LOG: [clang][cli][docs] Clarify marshalling infrastructure documentation Added: Modified: clang/docs/InternalsManual.rst clang/include/clang/Driver/Options.td llvm/include/llvm/Option/OptParser.td Removed: ################################################################################ diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index c1e45569a816..b5f3e4166d38 100644 --- a/clang/docs/InternalsManual.rst +++ b/clang/docs/InternalsManual.rst @@ -576,11 +576,11 @@ Compiler Invocation ------------------- One of the classes provided by the Frontend library is ``CompilerInvocation``, -which holds information that describe current invocation of the Clang frontend. -The information typically comes from the command line constructed by the Clang -driver or from clients performing custom initialization. The data structure is -split into logical units used by diff erent parts of the compiler, for example -``PreprocessorOptions``, ``LanguageOptions`` or ``CodeGenOptions``. +which holds information that describe current invocation of the Clang ``-cc1`` +frontend. The information typically comes from the command line constructed by +the Clang driver or from clients performing custom initialization. The data +structure is split into logical units used by diff erent parts of the compiler, +for example ``PreprocessorOptions``, ``LanguageOptions`` or ``CodeGenOptions``. Command Line Interface ---------------------- @@ -758,12 +758,16 @@ desired. Option Marshalling Infrastructure --------------------------------- -The option marshalling infrastructure automates the parsing of command line -arguments into ``CompilerInvocation`` and their generation from -``CompilerInvocation``. The system replaces lots of repetitive C++ code with -simple, declarative tablegen annotations and it's being used for the majority of -the ``-cc1`` command line interface. This section provides an overview of the -system. +The option marshalling infrastructure automates the parsing of the Clang +``-cc1`` frontend command line arguments into ``CompilerInvocation`` and their +generation from ``CompilerInvocation``. The system replaces lots of repetitive +C++ code with simple, declarative tablegen annotations and it's being used for +the majority of the ``-cc1`` command line interface. This section provides an +overview of the system. + +**Note:** The marshalling infrastructure is not intended for driver-only +options. Only options of the ``-cc1`` frontend need to be marshalled to/from +``CompilerInvocation`` instance. To read and modify contents of ``CompilerInvocation``, the marshalling system uses key paths, which are declared in two steps. First, a tablegen definition @@ -856,6 +860,10 @@ generated ``Options.inc``? This is specified by the ``Marshalling`` utilities described below. All of them take a key path argument and possibly other information required for parsing or generating the command line argument. +**Note:** The marshalling infrastructure is not intended for driver-only +options. Only options of the ``-cc1`` frontend need to be marshalled to/from +``CompilerInvocation`` instance. + **Positive Flag** The key path defaults to ``false`` and is set to ``true`` when the flag is diff --git a/clang/include/clang/Driver/Options.td b/clang/include/clang/Driver/Options.td index 2825fba16ef0..e76cfc3ea21f 100644 --- a/clang/include/clang/Driver/Options.td +++ b/clang/include/clang/Driver/Options.td @@ -394,6 +394,8 @@ class MarshalledFlagRec<FlagDefExpanded flag, FlagDefExpanded other, // key path via the marshalling infrastructure. // Names of the records consist of the specified prefix, "no_" for the negative // flag, and NAME. +// Used for -cc1 frontend options. Driver-only options do not map to +// CompilerInvocation. multiclass BoolOption<string prefix = "", string spelling_base, KeyPathAndMacro kpm, Default default, FlagDef flag1_base, FlagDef flag2_base, @@ -416,6 +418,8 @@ multiclass BoolOption<string prefix = "", string spelling_base, /// Creates a BoolOption where both of the flags are prefixed with "f", are in /// the Group<f_Group>. +/// Used for -cc1 frontend options. Driver-only options do not map to +/// CompilerInvocation. multiclass BoolFOption<string flag_base, KeyPathAndMacro kpm, Default default, FlagDef flag1, FlagDef flag2, BothFlags both = BothFlags<[], "">> { @@ -425,6 +429,8 @@ multiclass BoolFOption<string flag_base, KeyPathAndMacro kpm, // Creates a BoolOption where both of the flags are prefixed with "g" and have // the Group<g_Group>. +// Used for -cc1 frontend options. Driver-only options do not map to +// CompilerInvocation. multiclass BoolGOption<string flag_base, KeyPathAndMacro kpm, Default default, FlagDef flag1, FlagDef flag2, BothFlags both = BothFlags<[], "">> { diff --git a/llvm/include/llvm/Option/OptParser.td b/llvm/include/llvm/Option/OptParser.td index ad0c1eb7406a..96014b505d0f 100644 --- a/llvm/include/llvm/Option/OptParser.td +++ b/llvm/include/llvm/Option/OptParser.td @@ -144,56 +144,68 @@ class MetaVarName<string name> { string MetaVarName = name; } class Values<string value> { string Values = value; } class ValuesCode<code valuecode> { code ValuesCode = valuecode; } -// Helpers for defining marshalling information. +// Helpers for defining marshalling information (typically used in Clang's -cc1 +// frontend). +// The key path to the mapped field and the macro prefix for the resulting +// definition database. class KeyPathAndMacro<string key_path_prefix, string key_path_base, string macro_prefix = ""> { code KeyPath = !strconcat(key_path_prefix, key_path_base); code MacroPrefix = macro_prefix; } +// Mixin that implies the specified value for the current option when any of the +// given key paths evaluates to true. class ImpliedByAnyOf<list<string> key_paths, code value = "true"> { code ImpliedCheck = !foldl("false", key_paths, accumulator, key_path, !strconcat(accumulator, " || ", key_path)); code ImpliedValue = value; } +// Parent class for marshalled options (typically used in Clang's -cc1 frontend). class MarshallingInfo<KeyPathAndMacro kpm, code defaultvalue> { code KeyPath = kpm.KeyPath; code MacroPrefix = kpm.MacroPrefix; code DefaultValue = defaultvalue; } +// Marshalled option accepting a string argument. class MarshallingInfoString<KeyPathAndMacro kpm, code defaultvalue="std::string()"> : MarshallingInfo<kpm, defaultvalue> { code Normalizer = "normalizeString"; code Denormalizer = "denormalizeString"; } +// Marshalled option accepting an integer argument. class MarshallingInfoInt<KeyPathAndMacro kpm, code defaultvalue="0", code type="unsigned"> : MarshallingInfo<kpm, defaultvalue> { code Normalizer = "normalizeStringIntegral<"#type#">"; code Denormalizer = "denormalizeString<"#type#">"; } +// Marshalled option accepting vector of strings. class MarshallingInfoStringVector<KeyPathAndMacro kpm> : MarshallingInfo<kpm, "std::vector<std::string>({})"> { code Normalizer = "normalizeStringVector"; code Denormalizer = "denormalizeStringVector"; } +// Marshalled option - single positive flag. class MarshallingInfoFlag<KeyPathAndMacro kpm, code defaultvalue = "false"> : MarshallingInfo<kpm, defaultvalue> { code Normalizer = "normalizeSimpleFlag"; code Denormalizer = "denormalizeSimpleFlag"; } +// Marshalled option - single negative flag. class MarshallingInfoNegativeFlag<KeyPathAndMacro kpm, code defaultvalue = "true"> : MarshallingInfo<kpm, defaultvalue> { code Normalizer = "normalizeSimpleNegativeFlag"; code Denormalizer = "denormalizeSimpleFlag"; } +// Marshalled option - single flag contributing to a bitfield. class MarshallingInfoBitfieldFlag<KeyPathAndMacro kpm, code value> : MarshallingInfoFlag<kpm, "0u"> { code Normalizer = "makeFlagToValueNormalizer("#value#")"; @@ -201,7 +213,7 @@ class MarshallingInfoBitfieldFlag<KeyPathAndMacro kpm, code value> code ValueExtractor = "(extractMaskValue<unsigned, decltype("#value#"), "#value#">)"; } -// Marshalling info for booleans. Applied to the flag setting keypath to false. +// Implementation detail of BoolOption. class MarshallingInfoBooleanFlag<KeyPathAndMacro kpm, code defaultvalue, code value, code name, code other_value, code other_name> : MarshallingInfoFlag<kpm, defaultvalue> { @@ -209,8 +221,8 @@ class MarshallingInfoBooleanFlag<KeyPathAndMacro kpm, code defaultvalue, code va code Denormalizer = "makeBooleanOptionDenormalizer("#value#")"; } -// Marshalling info for enums. Typically used with `Values`, `NormalizedValues` -// and `NormalizedValuesScope` mixins. +// Marshalled option accepting any of the specified enum values. +// Typically used with `Values`, `NormalizedValues` and `NormalizedValuesScope`. class MarshallingInfoEnum<KeyPathAndMacro kpm, code defaultvalue> : MarshallingInfo<kpm, defaultvalue> { code Normalizer = "normalizeSimpleEnum"; _______________________________________________ cfe-commits mailing list cfe-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits