[clang] 0089583 - [clang][cli][docs] Clarify marshalling infrastructure documentation
Jan Svoboda via cfe-commits
cfe-commits at lists.llvm.org
Tue May 4 06:16:41 PDT 2021
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";
More information about the cfe-commits
mailing list