-------------------
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 different 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 different parts of the compiler,
+for example ``PreprocessorOptions``, ``LanguageOptions`` or ``CodeGenOptions``.
Command Line Interface
----------------------
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
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
// 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,
/// 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<[], "">> {
// 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<[], "">> {
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#")";
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> {
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";
projects / platform / upstream / llvm.git / commitdiff