From 00895831ab23f4de2713a6ad529ba48773d067c1 Mon Sep 17 00:00:00 2001 From: Jan Svoboda Date: Tue, 4 May 2021 15:15:44 +0200 Subject: [PATCH] [clang][cli][docs] Clarify marshalling infrastructure documentation --- clang/docs/InternalsManual.rst | 30 +++++++++++++++++++----------- clang/include/clang/Driver/Options.td | 6 ++++++ llvm/include/llvm/Option/OptParser.td | 20 ++++++++++++++++---- 3 files changed, 41 insertions(+), 15 deletions(-) diff --git a/clang/docs/InternalsManual.rst b/clang/docs/InternalsManual.rst index c1e4556..b5f3e41 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 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 ---------------------- @@ -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 2825fba..e76cfc3 100644 --- a/clang/include/clang/Driver/Options.td +++ b/clang/include/clang/Driver/Options.td @@ -394,6 +394,8 @@ class MarshalledFlagRec. +/// Used for -cc1 frontend options. Driver-only options do not map to +/// CompilerInvocation. multiclass BoolFOption> { @@ -425,6 +429,8 @@ multiclass BoolFOption. +// Used for -cc1 frontend options. Driver-only options do not map to +// CompilerInvocation. multiclass BoolGOption> { diff --git a/llvm/include/llvm/Option/OptParser.td b/llvm/include/llvm/Option/OptParser.td index ad0c1eb..96014b5 100644 --- a/llvm/include/llvm/Option/OptParser.td +++ b/llvm/include/llvm/Option/OptParser.td @@ -144,56 +144,68 @@ class MetaVarName { string MetaVarName = name; } class Values { string Values = value; } class ValuesCode { 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 { 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 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 { code KeyPath = kpm.KeyPath; code MacroPrefix = kpm.MacroPrefix; code DefaultValue = defaultvalue; } +// Marshalled option accepting a string argument. class MarshallingInfoString : MarshallingInfo { code Normalizer = "normalizeString"; code Denormalizer = "denormalizeString"; } +// Marshalled option accepting an integer argument. class MarshallingInfoInt : MarshallingInfo { code Normalizer = "normalizeStringIntegral<"#type#">"; code Denormalizer = "denormalizeString<"#type#">"; } +// Marshalled option accepting vector of strings. class MarshallingInfoStringVector : MarshallingInfo({})"> { code Normalizer = "normalizeStringVector"; code Denormalizer = "denormalizeStringVector"; } +// Marshalled option - single positive flag. class MarshallingInfoFlag : MarshallingInfo { code Normalizer = "normalizeSimpleFlag"; code Denormalizer = "denormalizeSimpleFlag"; } +// Marshalled option - single negative flag. class MarshallingInfoNegativeFlag : MarshallingInfo { code Normalizer = "normalizeSimpleNegativeFlag"; code Denormalizer = "denormalizeSimpleFlag"; } +// Marshalled option - single flag contributing to a bitfield. class MarshallingInfoBitfieldFlag : MarshallingInfoFlag { code Normalizer = "makeFlagToValueNormalizer("#value#")"; @@ -201,7 +213,7 @@ class MarshallingInfoBitfieldFlag code ValueExtractor = "(extractMaskValue)"; } -// Marshalling info for booleans. Applied to the flag setting keypath to false. +// Implementation detail of BoolOption. class MarshallingInfoBooleanFlag : MarshallingInfoFlag { @@ -209,8 +221,8 @@ class MarshallingInfoBooleanFlag : MarshallingInfo { code Normalizer = "normalizeSimpleEnum"; -- 2.7.4