* Modules doc
@ 2020-11-20 15:19 Nathan Sidwell
2020-11-20 16:45 ` Marek Polacek
0 siblings, 1 reply; 6+ messages in thread
From: Nathan Sidwell @ 2020-11-20 15:19 UTC (permalink / raw)
To: GCC Patches; +Cc: Jeff Law, Sandra Loosemore
[-- Attachment #1: Type: text/plain, Size: 170 bytes --]
Here is an update c++ modules documentation patch. I'd be grateful for
review. Especially checking I'm not using too much implementor-speak
nathan
--
Nathan Sidwell
[-- Attachment #2: 13-doc.diff --]
[-- Type: text/x-patch, Size: 21630 bytes --]
diff --git c/gcc/doc/cppopts.texi w/gcc/doc/cppopts.texi
index 7f1849d841f..e5ece92487b 100644
--- c/gcc/doc/cppopts.texi
+++ w/gcc/doc/cppopts.texi
@@ -139,6 +139,10 @@ this useless.
This feature is used in automatic updating of makefiles.
+@item -Mno-modules
+@opindex Mno-modules
+Disable dependency generation for compiled module interfaces.
+
@item -MP
@opindex MP
This option instructs CPP to add a phony target for each dependency
diff --git c/gcc/doc/invoke.texi w/gcc/doc/invoke.texi
index 02abac39de8..29ae36861ad 100644
--- c/gcc/doc/invoke.texi
+++ w/gcc/doc/invoke.texi
@@ -172,6 +172,7 @@ listing and explanation of the binary and decimal byte size prefixes.
* Spec Files:: How to pass switches to sub-processes.
* Environment Variables:: Env vars that affect GCC.
* Precompiled Headers:: Compiling a header once, and using it many times.
+* C++ Modules:: Experimental C++20 module system.
@end menu
@c man begin OPTIONS
@@ -214,14 +215,21 @@ in the following sections.
-faligned-new=@var{n} -fargs-in-order=@var{n} -fchar8_t -fcheck-new @gol
-fconstexpr-depth=@var{n} -fconstexpr-cache-depth=@var{n} @gol
-fconstexpr-loop-limit=@var{n} -fconstexpr-ops-limit=@var{n} @gol
+-fmodule-header@r{[}=@var{kind}@r{]} -fmodule-only -fmodules-ts @gol
+-fmodule-implicit-inline @gol
+-fmodule-mapper=@var{specification} @gol
+-fmodule-version-ignore @gol
-fno-elide-constructors @gol
-fno-enforce-eh-specs @gol
-fno-gnu-keywords @gol
-fno-implicit-templates @gol
-fno-implicit-inline-templates @gol
--fno-implement-inlines -fms-extensions @gol
+-fno-implement-inlines @gol
+-fno-module-lazy @gol
+-fms-extensions @gol
-fnew-inheriting-ctors @gol
-fnew-ttp-matching @gol
+-fno-module-lazy @gol
-fno-nonansi-builtins -fnothrow-opt -fno-operator-names @gol
-fno-optional-diags -fpermissive @gol
-fno-pretty-templates @gol
@@ -233,12 +241,14 @@ in the following sections.
-fvisibility-inlines-hidden @gol
-fvisibility-ms-compat @gol
-fext-numeric-literals @gol
+-flang-info-include-translate@r{[}=@var{name}@r{]} @gol
-Wabi-tag -Wcatch-value -Wcatch-value=@var{n} @gol
-Wno-class-conversion -Wclass-memaccess @gol
-Wcomma-subscript -Wconditionally-supported @gol
-Wno-conversion-null -Wctad-maybe-unsupported @gol
-Wctor-dtor-privacy -Wno-delete-incomplete @gol
--Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
+-Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
+-Winvalid-imported-macros @gol
-Wno-deprecated-enum-enum-conversion -Wno-deprecated-enum-float-conversion @gol
-Weffc++ -Wno-exceptions -Wextra-semi -Wno-inaccessible-base @gol
-Wno-inherited-variadic-ctor -Wno-init-list-lifetime @gol
@@ -599,7 +609,7 @@ Objective-C and Objective-C++ Dialects}.
-fpreprocessed -ftabstop=@var{width} -ftrack-macro-expansion @gol
-fwide-exec-charset=@var{charset} -fworking-directory @gol
-H -imacros @var{file} -include @var{file} @gol
--M -MD -MF -MG -MM -MMD -MP -MQ -MT @gol
+-M -MD -MF -MG -MM -MMD -MP -Mno-modules -MQ -MT @gol
-no-integrated-cpp -P -pthread -remap @gol
-traditional -traditional-cpp -trigraphs @gol
-U@var{macro} -undef @gol
@@ -1571,7 +1581,7 @@ name suffix). This option applies to all following input files until
the next @option{-x} option. Possible values for @var{language} are:
@smallexample
c c-header cpp-output
-c++ c++-header c++-cpp-output
+c++ c++-header c++-system-header c++-user-header c++-cpp-output
objective-c objective-c-header objective-c-cpp-output
objective-c++ objective-c++-header objective-c++-cpp-output
assembler assembler-with-cpp
@@ -3056,6 +3066,53 @@ To save space, do not emit out-of-line copies of inline functions
controlled by @code{#pragma implementation}. This causes linker
errors if these functions are not inlined everywhere they are called.
+@item -fmodules-ts
+@itemx -fno-modules-ts
+@opindex fmodules-ts
+@opindex fno-modules-ts
+Enable support for C++ 20 modules. The @option{-fno-modules-ts} is
+usually not needed, as that is the default. Even though this is a
+C++20 feature, it is not currently implicitly enabled by selecting
+that standard version.
+
+@item -fmodule-header
+@itemx -fmodule-header=user
+@itemx -fmodule-header=system
+@opindex fmodule-header
+Compile as a header unit.
+
+@item -fmodule-implicit-inline
+@opindex fmodule-implicit-inline
+Memmber functions defined in their class definitions are not
+implicitly inline for modular code. This is different to traditional
+C++ behaviour, for good reasons. However, it may result in a
+difficulty during code porting. This option will make such function
+definitions implicitly inline. It does however generate an ABI
+incompatibility, so you must use it everywhere or nowhere. (Such
+definitions outside of a named module remain implicitly inline,
+regardless.)
+
+@item -fno-module-lazy
+@opindex fno-module-lazy
+@opindex fmodule-lazy
+Disable lazy module importing and module mapper creation.
+
+@item -fmodule-mapper=@r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=|@var{program}@r{[}?@var{ident}@r{]} @var{args...}
+@itemx -fmodule-mapper==@var{socket}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=<>@r{[}@var{fdinout}@r{]}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=<@var{fdin}>@var{fdout}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=@var{file}@r{[}?@var{ident}@r{]}
+@vindex CXX_MODULE_MAPPER @r{environment variable}
+@opindex fmodule-mapper
+An oracle to query for module name to filename mappings. If
+unspecified the @env{CXX_MODULE_MAPPER} environment variable is used,
+and if that is unset, an in-process default is provided.
+
+@item -fmodule-only
+@opindex fmodule-only
+Only emit the module CMI, inhibiting any object file.
+
@item -fms-extensions
@opindex fms-extensions
Disable Wpedantic warnings about constructs used in MFC, such as implicit
@@ -3303,6 +3360,12 @@ for ISO C++11 onwards (@option{-std=c++11}, ...).
Do not search for header files in the standard directories specific to
C++, but do still search the other standard directories. (This option
is used when building the C++ library.)
+
+@item -flang-info-include-translate
+@itemx -flang-info-include-translate=@var{header}
+@opindex flang-info-include-translate
+Note include translation events.
+
@end table
In addition, these warning options have meanings only for C++ programs:
@@ -3460,6 +3523,13 @@ the variable declaration statement.
@end itemize
+@item -Winvalid-imported-macros
+@opindex Winvalid-imported-macros
+@opindex Wno-invalid-imported-macros
+Verify all imported macro definitions are valid at end of
+compilation. This is not enabled by default, as it requires
+additional processing to determine.
+
@item -Wno-literal-suffix @r{(C++ and Objective-C++ only)}
@opindex Wliteral-suffix
@opindex Wno-literal-suffix
@@ -16728,6 +16798,11 @@ By default, the dump will contain messages about successful
optimizations (equivalent to @option{-optimized}) together with
low-level details about the analysis.
+@item -fdump-lang
+@opindex fdump-lang
+Dump language-specific information. The file name is made by appending
+@file{.lang} to the source file name.
+
@item -fdump-lang-all
@itemx -fdump-lang-@var{switch}
@itemx -fdump-lang-@var{switch}-@var{options}
@@ -16748,6 +16823,14 @@ Enable all language-specific dumps.
Dump class hierarchy information. Virtual table information is emitted
unless '@option{slim}' is specified. This option is applicable to C++ only.
+@item module
+Dump module information. Options @option{lineno} (locations),
+@option{graph} (reachability), @option{blocks} (clusters),
+@option{uid} (serialization), @option{alias} (mergeable),
+@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops}
+(macros) may provide additional information. This option is
+applicable to C++ only.
+
@item raw
Dump the raw internal tree data. This option is applicable to C++ only.
@@ -32492,3 +32575,275 @@ precompiled header, the actual behavior is a mixture of the
behavior for the options. For instance, if you use @option{-g} to
generate the precompiled header but not when using it, you may or may
not get debugging information for routines in the precompiled header.
+
+@node C++ Modules
+@section C++ Modules
+@cindex speed of compilation
+
+Modules are a C++ 20 language feature. As the name suggests, it
+provides a modular compilation system, intending to provide both
+faster builds and better library isolation. The ``Merging Modules''
+paper @uref{https://wg21.link/p1103}, provides the easiest to read set
+of changes to the standard, although it does not capture later
+changes. That specification is now part of C++20,
+@uref{git@@github.com:cplusplus/draft.git}, it is considered complete
+(there may be defect reports to come).
+
+@emph{G++'s modules support is not complete.} Other than bugs, the
+missing pieces are:
+
+@table @emph
+
+@item Private Module Fragment
+The Private Module Fragment is recognized, but an error is emitted.
+
+@item Partition definition visibility rules
+Entities may be defined in implementation partitions, and those
+definitions are not available outside of the module. This is not
+implemented.
+
+@item Textual merging of reachable GM entities
+Entitites may be multiply defined across different header-units.
+These must be de-duplicated, and this is implemented across imports,
+or when an import redefines a textually-defined entity. However the
+reverse is not implemented -- textually redefining an entity that has
+been defined in an imported header-unit. A redefinition error will be
+emitted.
+
+@item Translation-Unit local referencing rules
+Papers p1815 (@uref{https://wg21.link/p1815}) and p2003
+(@uref{https://wg21.link/p2003} adds limitations on which entities an
+exported region may reference (for instance, the entities an exported
+template definition may reference). These are not fully implemented.
+
+@end table
+
+Modular compilation is @emph{not} enabled with just the
+@option{-std=c++20} option. You must explicitly enable it with the
+@option{-fmodules-ts} option. It is independent of the language
+version selected, although in pre-c++20 versions, it is of course an
+extension.
+
+No new source file suffixes are required or supported. If you wish to
+use a non-standard suffix (@xref{Overall Options}), you will also need
+to provide a @option{-x c++} option too.@footnote{Some users like to
+distinguish module interface files with a new suffix, such as naming
+the source @code{module.cppm}, which involves
+teaching all tools about the new suffix. A different scheme, such as
+naming @code{module-m.cpp} would be less invasive.}
+
+Compiling a module interface unit produces an additional output (to
+the assembly or object file), called a Compiled Module Interface
+(CMI). This encodes the exported declarations of the module.
+Importing a module reads in the CMI. The import graph is a Directed
+Acyclic Graph (DAG). You must build imports before the importer.
+
+Header files may themselves be compiled to header units, which are a
+transitional ability aiming at faster compilation. The
+@option{-fmodule-header} option is used to enable this, and implies
+the @option{-fmodules-ts} option. These CMIs are named by the fully
+resolved underlying header file, and thus may be a complete pathname
+containing subdirectories. If the header file is found at an absolute
+pathname, the CMI location is still relative to a CMI root directory.
+
+As header files often have no suffix, you commonly have to specify a
+@option{-x} option to tell the compiler the source is a header file.
+You may use @option{-x c++-header}, @option{-x c++-user-header} or
+@option{-x c++-system-header}. When used in conjunction with
+@option{-fmodules-ts}, these all imply an appropriate
+@option{-fmodule-header} option. The latter two variants will use the
+user or system include path to search for the file specified. This
+allows you to, for instance, compile standard library header files as
+header units, without needing to know exactly where they are
+installed. Specifying the language as one of these variants also
+inhibits output of the object file, as header files have no associated
+object file.
+
+When creating an output CMI any missing directory components are
+created in a manner that is safe for concurrent builds creating
+multiple, different, CMIs within a common subdirectory tree.
+
+CMI contents are written to a temporary file, which is then atomically
+renamed. Observers will either see old contents (if there is an
+existing file), or complete new contents. They will not observe the
+CMI during its creation. This is unlike object file writing, which
+may be observed by an external process.
+
+CMIs are read in lazily, if the host OS provides @code{mmap}
+functionality. Generally blocks are read when name lookup or template
+instantiation occurs. To inhibit this, the @option{-fno-module-lazy}
+option may be used.
+
+The @option{-fmodule-only} option disables generation of the
+associated object file for compiling a module interface. Only the CMI
+is generated. This option is implied when using the
+@option{-fmodule-header} option.
+
+The @option{--param lazy-modules=@var{n}} parameter controls the limit
+on the number of concurrently open module files during lazy loading.
+Should more modules be imported, an LRU algorithm is used to determine
+which files to close -- until that file is needed again. This limit
+may be exceeded with deep module dependency hierarchies. With large
+code bases there may be more imports than the process limit of file
+descriptors. By default, the limit is a few less than the per-process
+file descriptor hard limit, if that is determinable.@footnote{Where
+applicable the soft limit is incremented as needed towards the hard limit.}
+
+The @option{-flang-info-include-translate} option notes whether
+include translation occurs. With no argument, all include translation
+is noted. Otherwise, queries about include translation of a specific
+header file is noted. The latter form may be repeated. This option
+may be helpful in determining whether include translation is
+happenning -- if it is working correctly, it'll behave as if it wasn't
+there at all.
+
+The @option{-Winvalid-imported-macros} option causes all imported macros
+to be resolved at the end of compilation. Without this, imported
+macros are only resolved when expanded or (re)defined. This option
+will detect conflicting import definitions for all macros.
+
+The @option{-fmodule-mapper} family of options are described below.
+
+@menu
+* C++ Module Mapper:: Module Mapper
+* C++ Module Preprocessing:: Module Preprocessing
+@end menu
+
+@node C++ Module Mapper
+@subsection Module Mapper
+@cindex C++ Module Mapper
+
+A module mapper provides a server or file that the compiler queries to
+determine the mapping between module names and CMI files. It is also
+used to build CMIs on demand. @emph{Mapper functionality is in its
+infancy and is intended for experimentation with build system
+interactions.}
+
+A mapper may be specified with the @option{-fmodule-mapper=@var{val}}
+option or @env{CXX_MODULE_MAPPER} environment variable. The value may
+have one of the following forms:
+
+@table @gcctabopt
+
+@item @r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
+An optional hostname and a numeric port number to connect to. If the
+hostname is omitted, the loopback address is used. If the hostname
+corresponds to multiple IPV6 addresses, these are tried in turn, until
+one is successful. If your host lacks IPv6, this form is
+non-functional. If you must use IPv4 use
+@option{-fmodule-mapper='|ncat @var{ipv4host} @var{port}'}.
+
+@item =@var{socket}@r{[}?@var{ident}@r{]}
+A local domain socket. If your host lacks local domain sockets, this
+form is non-functional.
+
+@item |@var{program}@r{[}?@var{ident}@r{]} @r{[}@var{args...}@r{]}
+A program to spawn, and communicate with on its stdin/stdout streams.
+Your @var{PATH} environment variable is searched for the program.
+Arguments are separated by space characters, (it is not possible for
+one of the arguments delivered to the program to contain a space). An
+exception is if @var{program} begins with @@. In that case
+@var{program} (sans @@) is looked for in the compiler's internal
+binary directory. Thus the sample mapper-server can be specified
+with @code{@@g++-mapper-server}.
+
+@item <>@r{[}?@var{ident}@r{]}
+@item <>@var{fdinout}@r{[}?@var{ident}@r{]}
+@item <@var{fdin}>@var{fdout}@r{[}?@var{ident}@r{]}
+File descriptors to communicate over. The first form, @option{<>},
+communicates over stdin and stdout. The second form specifies a
+bidirectional file descriptor and the last form allows specifying
+two independent descriptors. Note that other compiler options might
+cause the compiler to read stdin or write stdout.
+
+@item @var{file}@r{[}?@var{ident}@r{]}
+A mapping file consisting of space-separated module-name, filename
+pairs, one per line. Only the mappings for the direct imports and any
+module export name need be provided. If other mappings are provided,
+they override those stored in any imported CMI files. A repository
+root may be specified in the mapping file by using @samp{$root} as the
+module name in the first active line.
+
+@end table
+
+As shown, an optional @var{ident} may suffix the first word of the
+option, indicated by a @samp{?} prefix. The value is used in the
+initial handshake with the module server, or to specify a prefix on
+mapping file lines. In the server case, the main source file name is
+used if no @var{ident} is specified. In the file case, all non-blank
+lines are significant, unless a value is specified, in which case only
+lines beginning with @var{ident} are significant. The @var{ident}
+must be separated by whitespace from the module name. Be aware that
+@samp{<}, @samp{>}, @samp{?}, and @samp{|} characters are often
+significant to the shell, and therefore may need quoting.
+
+The mapper is connected to or loaded lazily, when the first module
+mapping is required. The networking protocols are only supported on
+hosts that provide networking. If no mapper is specified a default is
+provided.
+
+A project-specific mapper is expected to be provided by the build
+system that invokes the compiler. It is not expected that a
+general-purpose server is provided for all compilations. As such, the
+server will know the build configuration, the compiler it invoked, and
+the environment (such as working directory) in which that is
+operating. As it may parallelize builds, several compilations may
+connect to the same socket.
+
+The default mapper generates CMI files in a @samp{gcm.cache}
+directory. CMI files have a @samp{.gcm} suffix. The module unit name
+is used directly to provide the basename. Header units construct a
+relative path using the underlying header file name. If the path is
+already relative, a @samp{,} directory is prepended. Internal
+@samp{..} components are translated to @samp{,,}. No attempt is made
+to canonicalize these filenames beyond that done by the preprocessor's
+include search algorithm, as in general it is ambiguous when symbolic
+links are present.
+
+The mapper protocol was published as ``A Module Mapper''
+@uref{https://wg21.link/p1184}. The implementation is provided by
+@command{libcody}, @uref{https://www.github.com/urnathan/libcody},
+which specifies the canonical protocol definition. A proof of concept
+server implementation embedded in @command{make} was described in
+''Make Me A Module'', @uref{https://wg21.link/p1602}.
+
+@node C++ Module Preprocessing
+@subsection Module Preprocessing
+@cindex C++ Module Preprocessing
+
+Modules affect preprocessing because of header units and include
+translation. Some uses of the preprocessor as a separate step will
+either not produce a correct output, or require CMIs to be available.
+
+Header units import macros. These macros can affect later conditional
+inclusion, which therefore can cascade to differing import sets. When
+preprocessing, it is necessary to load the CMI. If a header unit is
+unavailable, the preprocessor will issue a warning and continue (when
+not just preprocessing, an error is emitted). Detecting such imports
+requires preprocessor tokenization of the input stream to phase 4
+(macro expansion).
+
+Include translation converts @code{#include}, @code{#include_next} and
+@code{#import} directives to internal @code{import} declarations.
+Whether a particular directive is translated is controlled by the
+module mapper. Header unit names are canonicalized during
+preprocessing.
+
+Dependency information can be emitted for macro import, extending the
+functionality of @option{-MD} and @option{-MMD} options. Detection of
+import declarations also requires phase 4 preprocessing, and thus
+requires full preprocessing (or compilation).
+
+The @option{-M}, @option{-MM} and @option{-E -fdirectives-only} options halt
+preprocessing before phase 4.
+
+The @option{-save-temps} option will use @option{-fdirectives-only}
+for preprocessing, and preserve the macro definitions in the
+preprocessed output. Usually you will also want to use this option
+when explicitly preprocessing a header-unit, or consuming such
+preprocessed output:
+
+@smallexample
+g++ -fmodules-ts -E -fdirectives-only my-header.hh -o my-header.ii
+g++ -x c++-header -fmodules-ts -fpreprocessed -fdirectives-only my-header.ii
+@end smallexample
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Modules doc
2020-11-20 15:19 Modules doc Nathan Sidwell
@ 2020-11-20 16:45 ` Marek Polacek
2020-11-20 17:12 ` Nathan Sidwell
2020-11-24 7:11 ` Boris Kolpackov
0 siblings, 2 replies; 6+ messages in thread
From: Marek Polacek @ 2020-11-20 16:45 UTC (permalink / raw)
To: Nathan Sidwell; +Cc: GCC Patches, Sandra Loosemore
On Fri, Nov 20, 2020 at 10:19:55AM -0500, Nathan Sidwell wrote:
> Here is an update c++ modules documentation patch. I'd be grateful for
> review. Especially checking I'm not using too much implementor-speak
>
> nathan
> --
> Nathan Sidwell
> diff --git c/gcc/doc/cppopts.texi w/gcc/doc/cppopts.texi
> index 7f1849d841f..e5ece92487b 100644
> --- c/gcc/doc/cppopts.texi
> +++ w/gcc/doc/cppopts.texi
> @@ -139,6 +139,10 @@ this useless.
>
> This feature is used in automatic updating of makefiles.
>
> +@item -Mno-modules
> +@opindex Mno-modules
> +Disable dependency generation for compiled module interfaces.
> +
> @item -MP
> @opindex MP
> This option instructs CPP to add a phony target for each dependency
> diff --git c/gcc/doc/invoke.texi w/gcc/doc/invoke.texi
> index 02abac39de8..29ae36861ad 100644
> --- c/gcc/doc/invoke.texi
> +++ w/gcc/doc/invoke.texi
> @@ -172,6 +172,7 @@ listing and explanation of the binary and decimal byte size prefixes.
> * Spec Files:: How to pass switches to sub-processes.
> * Environment Variables:: Env vars that affect GCC.
> * Precompiled Headers:: Compiling a header once, and using it many times.
> +* C++ Modules:: Experimental C++20 module system.
> @end menu
>
> @c man begin OPTIONS
> @@ -214,14 +215,21 @@ in the following sections.
> -faligned-new=@var{n} -fargs-in-order=@var{n} -fchar8_t -fcheck-new @gol
> -fconstexpr-depth=@var{n} -fconstexpr-cache-depth=@var{n} @gol
> -fconstexpr-loop-limit=@var{n} -fconstexpr-ops-limit=@var{n} @gol
> +-fmodule-header@r{[}=@var{kind}@r{]} -fmodule-only -fmodules-ts @gol
> +-fmodule-implicit-inline @gol
> +-fmodule-mapper=@var{specification} @gol
> +-fmodule-version-ignore @gol
> -fno-elide-constructors @gol
> -fno-enforce-eh-specs @gol
> -fno-gnu-keywords @gol
> -fno-implicit-templates @gol
> -fno-implicit-inline-templates @gol
> --fno-implement-inlines -fms-extensions @gol
> +-fno-implement-inlines @gol
> +-fno-module-lazy @gol
> +-fms-extensions @gol
> -fnew-inheriting-ctors @gol
> -fnew-ttp-matching @gol
> +-fno-module-lazy @gol
> -fno-nonansi-builtins -fnothrow-opt -fno-operator-names @gol
> -fno-optional-diags -fpermissive @gol
> -fno-pretty-templates @gol
> @@ -233,12 +241,14 @@ in the following sections.
> -fvisibility-inlines-hidden @gol
> -fvisibility-ms-compat @gol
> -fext-numeric-literals @gol
> +-flang-info-include-translate@r{[}=@var{name}@r{]} @gol
> -Wabi-tag -Wcatch-value -Wcatch-value=@var{n} @gol
> -Wno-class-conversion -Wclass-memaccess @gol
> -Wcomma-subscript -Wconditionally-supported @gol
> -Wno-conversion-null -Wctad-maybe-unsupported @gol
> -Wctor-dtor-privacy -Wno-delete-incomplete @gol
> --Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
> +-Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
> +-Winvalid-imported-macros @gol
> -Wno-deprecated-enum-enum-conversion -Wno-deprecated-enum-float-conversion @gol
> -Weffc++ -Wno-exceptions -Wextra-semi -Wno-inaccessible-base @gol
> -Wno-inherited-variadic-ctor -Wno-init-list-lifetime @gol
> @@ -599,7 +609,7 @@ Objective-C and Objective-C++ Dialects}.
> -fpreprocessed -ftabstop=@var{width} -ftrack-macro-expansion @gol
> -fwide-exec-charset=@var{charset} -fworking-directory @gol
> -H -imacros @var{file} -include @var{file} @gol
> --M -MD -MF -MG -MM -MMD -MP -MQ -MT @gol
> +-M -MD -MF -MG -MM -MMD -MP -Mno-modules -MQ -MT @gol
> -no-integrated-cpp -P -pthread -remap @gol
> -traditional -traditional-cpp -trigraphs @gol
> -U@var{macro} -undef @gol
> @@ -1571,7 +1581,7 @@ name suffix). This option applies to all following input files until
> the next @option{-x} option. Possible values for @var{language} are:
> @smallexample
> c c-header cpp-output
> -c++ c++-header c++-cpp-output
> +c++ c++-header c++-system-header c++-user-header c++-cpp-output
> objective-c objective-c-header objective-c-cpp-output
> objective-c++ objective-c++-header objective-c++-cpp-output
> assembler assembler-with-cpp
> @@ -3056,6 +3066,53 @@ To save space, do not emit out-of-line copies of inline functions
> controlled by @code{#pragma implementation}. This causes linker
> errors if these functions are not inlined everywhere they are called.
>
> +@item -fmodules-ts
> +@itemx -fno-modules-ts
> +@opindex fmodules-ts
> +@opindex fno-modules-ts
> +Enable support for C++ 20 modules. The @option{-fno-modules-ts} is
We should be consistent wrt "C++ 20" and "C++20", so let's go with the
latter?
> +usually not needed, as that is the default. Even though this is a
> +C++20 feature, it is not currently implicitly enabled by selecting
> +that standard version.
> +
> +@item -fmodule-header
> +@itemx -fmodule-header=user
> +@itemx -fmodule-header=system
> +@opindex fmodule-header
> +Compile as a header unit.
Not sure if everyone knows what a header unit is.
> +
> +@item -fmodule-implicit-inline
> +@opindex fmodule-implicit-inline
> +Memmber functions defined in their class definitions are not
"Member"
> +implicitly inline for modular code. This is different to traditional
> +C++ behaviour, for good reasons. However, it may result in a
"behavior" ;)
> +difficulty during code porting. This option will make such function
> +definitions implicitly inline. It does however generate an ABI
> +incompatibility, so you must use it everywhere or nowhere. (Such
> +definitions outside of a named module remain implicitly inline,
> +regardless.)
> +
> +@item -fno-module-lazy
> +@opindex fno-module-lazy
> +@opindex fmodule-lazy
> +Disable lazy module importing and module mapper creation.
> +
> +@item -fmodule-mapper=@r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
> +@itemx -fmodule-mapper=|@var{program}@r{[}?@var{ident}@r{]} @var{args...}
> +@itemx -fmodule-mapper==@var{socket}@r{[}?@var{ident}@r{]}
> +@itemx -fmodule-mapper=<>@r{[}@var{fdinout}@r{]}@r{[}?@var{ident}@r{]}
> +@itemx -fmodule-mapper=<@var{fdin}>@var{fdout}@r{[}?@var{ident}@r{]}
> +@itemx -fmodule-mapper=@var{file}@r{[}?@var{ident}@r{]}
> +@vindex CXX_MODULE_MAPPER @r{environment variable}
> +@opindex fmodule-mapper
> +An oracle to query for module name to filename mappings. If
> +unspecified the @env{CXX_MODULE_MAPPER} environment variable is used,
> +and if that is unset, an in-process default is provided.
> +
> +@item -fmodule-only
> +@opindex fmodule-only
> +Only emit the module CMI, inhibiting any object file.
Maybe say here that CMI is Compiled Module Interface.
> @item -fms-extensions
> @opindex fms-extensions
> Disable Wpedantic warnings about constructs used in MFC, such as implicit
> @@ -3303,6 +3360,12 @@ for ISO C++11 onwards (@option{-std=c++11}, ...).
> Do not search for header files in the standard directories specific to
> C++, but do still search the other standard directories. (This option
> is used when building the C++ library.)
> +
> +@item -flang-info-include-translate
> +@itemx -flang-info-include-translate=@var{header}
> +@opindex flang-info-include-translate
> +Note include translation events.
This took me a little while. "Notes include translation events."?
> @end table
>
> In addition, these warning options have meanings only for C++ programs:
> @@ -3460,6 +3523,13 @@ the variable declaration statement.
>
> @end itemize
>
> +@item -Winvalid-imported-macros
> +@opindex Winvalid-imported-macros
> +@opindex Wno-invalid-imported-macros
> +Verify all imported macro definitions are valid at end of
"at the"?
> +compilation. This is not enabled by default, as it requires
> +additional processing to determine.
> +
> @item -Wno-literal-suffix @r{(C++ and Objective-C++ only)}
> @opindex Wliteral-suffix
> @opindex Wno-literal-suffix
> @@ -16728,6 +16798,11 @@ By default, the dump will contain messages about successful
> optimizations (equivalent to @option{-optimized}) together with
> low-level details about the analysis.
>
> +@item -fdump-lang
> +@opindex fdump-lang
> +Dump language-specific information. The file name is made by appending
> +@file{.lang} to the source file name.
> +
> @item -fdump-lang-all
> @itemx -fdump-lang-@var{switch}
> @itemx -fdump-lang-@var{switch}-@var{options}
> @@ -16748,6 +16823,14 @@ Enable all language-specific dumps.
> Dump class hierarchy information. Virtual table information is emitted
> unless '@option{slim}' is specified. This option is applicable to C++ only.
>
> +@item module
> +Dump module information. Options @option{lineno} (locations),
> +@option{graph} (reachability), @option{blocks} (clusters),
> +@option{uid} (serialization), @option{alias} (mergeable),
> +@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops}
> +(macros) may provide additional information. This option is
> +applicable to C++ only.
> +
> @item raw
> Dump the raw internal tree data. This option is applicable to C++ only.
>
> @@ -32492,3 +32575,275 @@ precompiled header, the actual behavior is a mixture of the
> behavior for the options. For instance, if you use @option{-g} to
> generate the precompiled header but not when using it, you may or may
> not get debugging information for routines in the precompiled header.
> +
> +@node C++ Modules
> +@section C++ Modules
> +@cindex speed of compilation
> +
> +Modules are a C++ 20 language feature. As the name suggests, it
> +provides a modular compilation system, intending to provide both
> +faster builds and better library isolation. The ``Merging Modules''
> +paper @uref{https://wg21.link/p1103}, provides the easiest to read set
> +of changes to the standard, although it does not capture later
> +changes. That specification is now part of C++20,
> +@uref{git@@github.com:cplusplus/draft.git}, it is considered complete
> +(there may be defect reports to come).
> +
> +@emph{G++'s modules support is not complete.} Other than bugs, the
> +missing pieces are:
> +
> +@table @emph
> +
> +@item Private Module Fragment
> +The Private Module Fragment is recognized, but an error is emitted.
> +
> +@item Partition definition visibility rules
> +Entities may be defined in implementation partitions, and those
> +definitions are not available outside of the module. This is not
> +implemented.
> +
> +@item Textual merging of reachable GM entities
> +Entitites may be multiply defined across different header-units.
"Entities"
> +These must be de-duplicated, and this is implemented across imports,
> +or when an import redefines a textually-defined entity. However the
> +reverse is not implemented -- textually redefining an entity that has
> +been defined in an imported header-unit. A redefinition error will be
> +emitted.
> +
> +@item Translation-Unit local referencing rules
> +Papers p1815 (@uref{https://wg21.link/p1815}) and p2003
> +(@uref{https://wg21.link/p2003} adds limitations on which entities an
"add"?
Othewise I think it's a good start. Thanks for putting all of this together!
Marek
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Modules doc
2020-11-20 16:45 ` Marek Polacek
@ 2020-11-20 17:12 ` Nathan Sidwell
2020-11-30 6:33 ` Sandra Loosemore
2020-11-24 7:11 ` Boris Kolpackov
1 sibling, 1 reply; 6+ messages in thread
From: Nathan Sidwell @ 2020-11-20 17:12 UTC (permalink / raw)
To: Marek Polacek; +Cc: GCC Patches, Sandra Loosemore
[-- Attachment #1: Type: text/plain, Size: 204 bytes --]
thanks for taking a look, I hope this is better -- I add a forward
reference from -fmodules-ts option description, so as to not have to
explain C++ terms of art just there :)
nathan
--
Nathan Sidwell
[-- Attachment #2: 12b-doc.diff --]
[-- Type: text/x-patch, Size: 22200 bytes --]
diff --git c/gcc/doc/cppopts.texi w/gcc/doc/cppopts.texi
index 7f1849d841f..e5ece92487b 100644
--- c/gcc/doc/cppopts.texi
+++ w/gcc/doc/cppopts.texi
@@ -139,6 +139,10 @@ this useless.
This feature is used in automatic updating of makefiles.
+@item -Mno-modules
+@opindex Mno-modules
+Disable dependency generation for compiled module interfaces.
+
@item -MP
@opindex MP
This option instructs CPP to add a phony target for each dependency
diff --git c/gcc/doc/invoke.texi w/gcc/doc/invoke.texi
index 02abac39de8..1857e16e475 100644
--- c/gcc/doc/invoke.texi
+++ w/gcc/doc/invoke.texi
@@ -172,6 +172,7 @@ listing and explanation of the binary and decimal byte size prefixes.
* Spec Files:: How to pass switches to sub-processes.
* Environment Variables:: Env vars that affect GCC.
* Precompiled Headers:: Compiling a header once, and using it many times.
+* C++ Modules:: Experimental C++20 module system.
@end menu
@c man begin OPTIONS
@@ -214,14 +215,21 @@ in the following sections.
-faligned-new=@var{n} -fargs-in-order=@var{n} -fchar8_t -fcheck-new @gol
-fconstexpr-depth=@var{n} -fconstexpr-cache-depth=@var{n} @gol
-fconstexpr-loop-limit=@var{n} -fconstexpr-ops-limit=@var{n} @gol
+-fmodule-header@r{[}=@var{kind}@r{]} -fmodule-only -fmodules-ts @gol
+-fmodule-implicit-inline @gol
+-fmodule-mapper=@var{specification} @gol
+-fmodule-version-ignore @gol
-fno-elide-constructors @gol
-fno-enforce-eh-specs @gol
-fno-gnu-keywords @gol
-fno-implicit-templates @gol
-fno-implicit-inline-templates @gol
--fno-implement-inlines -fms-extensions @gol
+-fno-implement-inlines @gol
+-fno-module-lazy @gol
+-fms-extensions @gol
-fnew-inheriting-ctors @gol
-fnew-ttp-matching @gol
+-fno-module-lazy @gol
-fno-nonansi-builtins -fnothrow-opt -fno-operator-names @gol
-fno-optional-diags -fpermissive @gol
-fno-pretty-templates @gol
@@ -233,12 +241,14 @@ in the following sections.
-fvisibility-inlines-hidden @gol
-fvisibility-ms-compat @gol
-fext-numeric-literals @gol
+-flang-info-include-translate@r{[}=@var{name}@r{]} @gol
-Wabi-tag -Wcatch-value -Wcatch-value=@var{n} @gol
-Wno-class-conversion -Wclass-memaccess @gol
-Wcomma-subscript -Wconditionally-supported @gol
-Wno-conversion-null -Wctad-maybe-unsupported @gol
-Wctor-dtor-privacy -Wno-delete-incomplete @gol
--Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
+-Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
+-Winvalid-imported-macros @gol
-Wno-deprecated-enum-enum-conversion -Wno-deprecated-enum-float-conversion @gol
-Weffc++ -Wno-exceptions -Wextra-semi -Wno-inaccessible-base @gol
-Wno-inherited-variadic-ctor -Wno-init-list-lifetime @gol
@@ -599,7 +609,7 @@ Objective-C and Objective-C++ Dialects}.
-fpreprocessed -ftabstop=@var{width} -ftrack-macro-expansion @gol
-fwide-exec-charset=@var{charset} -fworking-directory @gol
-H -imacros @var{file} -include @var{file} @gol
--M -MD -MF -MG -MM -MMD -MP -MQ -MT @gol
+-M -MD -MF -MG -MM -MMD -MP -Mno-modules -MQ -MT @gol
-no-integrated-cpp -P -pthread -remap @gol
-traditional -traditional-cpp -trigraphs @gol
-U@var{macro} -undef @gol
@@ -1571,7 +1581,7 @@ name suffix). This option applies to all following input files until
the next @option{-x} option. Possible values for @var{language} are:
@smallexample
c c-header cpp-output
-c++ c++-header c++-cpp-output
+c++ c++-header c++-system-header c++-user-header c++-cpp-output
objective-c objective-c-header objective-c-cpp-output
objective-c++ objective-c++-header objective-c++-cpp-output
assembler assembler-with-cpp
@@ -3056,6 +3066,52 @@ To save space, do not emit out-of-line copies of inline functions
controlled by @code{#pragma implementation}. This causes linker
errors if these functions are not inlined everywhere they are called.
+@item -fmodules-ts
+@itemx -fno-modules-ts
+@opindex fmodules-ts
+@opindex fno-modules-ts
+Enable support for C++20 modules (@xref{C++ Modules}). The
+@option{-fno-modules-ts} is usually not needed, as that is the
+default. Even though this is a C++20 feature, it is not currently
+implicitly enabled by selecting that standard version.
+
+@item -fmodule-header
+@itemx -fmodule-header=user
+@itemx -fmodule-header=system
+@opindex fmodule-header
+Compile a header file to create an importableheader unit.
+
+@item -fmodule-implicit-inline
+@opindex fmodule-implicit-inline
+Member functions defined in their class definitions are not implicitly
+inline for modular code. This is different to traditional C++
+behavior, for good reasons. However, it may result in a difficulty
+during code porting. This option will make such function definitions
+implicitly inline. It does however generate an ABI incompatibility,
+so you must use it everywhere or nowhere. (Such definitions outside
+of a named module remain implicitly inline, regardless.)
+
+@item -fno-module-lazy
+@opindex fno-module-lazy
+@opindex fmodule-lazy
+Disable lazy module importing and module mapper creation.
+
+@item -fmodule-mapper=@r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=|@var{program}@r{[}?@var{ident}@r{]} @var{args...}
+@itemx -fmodule-mapper==@var{socket}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=<>@r{[}@var{fdinout}@r{]}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=<@var{fdin}>@var{fdout}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=@var{file}@r{[}?@var{ident}@r{]}
+@vindex CXX_MODULE_MAPPER @r{environment variable}
+@opindex fmodule-mapper
+An oracle to query for module name to filename mappings. If
+unspecified the @env{CXX_MODULE_MAPPER} environment variable is used,
+and if that is unset, an in-process default is provided.
+
+@item -fmodule-only
+@opindex fmodule-only
+Only emit the Compiled Module Interface, inhibiting any object file.
+
@item -fms-extensions
@opindex fms-extensions
Disable Wpedantic warnings about constructs used in MFC, such as implicit
@@ -3303,6 +3359,12 @@ for ISO C++11 onwards (@option{-std=c++11}, ...).
Do not search for header files in the standard directories specific to
C++, but do still search the other standard directories. (This option
is used when building the C++ library.)
+
+@item -flang-info-include-translate
+@itemx -flang-info-include-translate=@var{header}
+@opindex flang-info-include-translate
+Give notice of include translation events.
+
@end table
In addition, these warning options have meanings only for C++ programs:
@@ -3460,6 +3522,14 @@ the variable declaration statement.
@end itemize
+@item -Winvalid-imported-macros
+@opindex Winvalid-imported-macros
+@opindex Wno-invalid-imported-macros
+Verify all imported macro definitions are valid at the end of
+compilation. This is not enabled by default, as it requires
+additional processing to determine. It may be useful when preparing
+sets of header-units to ensure consistent macros.
+
@item -Wno-literal-suffix @r{(C++ and Objective-C++ only)}
@opindex Wliteral-suffix
@opindex Wno-literal-suffix
@@ -16728,6 +16798,11 @@ By default, the dump will contain messages about successful
optimizations (equivalent to @option{-optimized}) together with
low-level details about the analysis.
+@item -fdump-lang
+@opindex fdump-lang
+Dump language-specific information. The file name is made by appending
+@file{.lang} to the source file name.
+
@item -fdump-lang-all
@itemx -fdump-lang-@var{switch}
@itemx -fdump-lang-@var{switch}-@var{options}
@@ -16748,6 +16823,14 @@ Enable all language-specific dumps.
Dump class hierarchy information. Virtual table information is emitted
unless '@option{slim}' is specified. This option is applicable to C++ only.
+@item module
+Dump module information. Options @option{lineno} (locations),
+@option{graph} (reachability), @option{blocks} (clusters),
+@option{uid} (serialization), @option{alias} (mergeable),
+@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops}
+(macros) may provide additional information. This option is
+applicable to C++ only.
+
@item raw
Dump the raw internal tree data. This option is applicable to C++ only.
@@ -31932,7 +32015,7 @@ usage:
@item @code{sanitize}
The @code{sanitize} spec function takes no arguments. It returns non-NULL if
-any address, thread or undefined behaviour sanitizers are active.
+any address, thread or undefined behavior sanitizers are active.
@smallexample
%@{%:sanitize(address):-funwind-tables@}
@@ -32492,3 +32575,276 @@ precompiled header, the actual behavior is a mixture of the
behavior for the options. For instance, if you use @option{-g} to
generate the precompiled header but not when using it, you may or may
not get debugging information for routines in the precompiled header.
+
+@node C++ Modules
+@section C++ Modules
+@cindex speed of compilation
+
+Modules are a C++ 20 language feature. As the name suggests, it
+provides a modular compilation system, intending to provide both
+faster builds and better library isolation. The ``Merging Modules''
+paper @uref{https://wg21.link/p1103}, provides the easiest to read set
+of changes to the standard, although it does not capture later
+changes. That specification is now part of C++20,
+@uref{git@@github.com:cplusplus/draft.git}, it is considered complete
+(there may be defect reports to come).
+
+@emph{G++'s modules support is not complete.} Other than bugs, the
+known missing pieces are:
+
+@table @emph
+
+@item Private Module Fragment
+The Private Module Fragment is recognized, but an error is emitted.
+
+@item Partition definition visibility rules
+Entities may be defined in implementation partitions, and those
+definitions are not available outside of the module. This is not
+implemented, and the definitions are available to extra-module use.
+
+@item Textual merging of reachable GM entities
+Entities may be multiply defined across different header-units.
+These must be de-duplicated, and this is implemented across imports,
+or when an import redefines a textually-defined entity. However the
+reverse is not implemented -- textually redefining an entity that has
+been defined in an imported header-unit. A redefinition error will be
+emitted.
+
+@item Translation-Unit local referencing rules
+Papers p1815 (@uref{https://wg21.link/p1815}) and p2003
+(@uref{https://wg21.link/p2003} add limitations on which entities an
+exported region may reference (for instance, the entities an exported
+template definition may reference). These are not fully implemented.
+
+@end table
+
+Modular compilation is @emph{not} enabled with just the
+@option{-std=c++20} option. You must explicitly enable it with the
+@option{-fmodules-ts} option. It is independent of the language
+version selected, although in pre-C++20 versions, it is of course an
+extension.
+
+No new source file suffixes are required or supported. If you wish to
+use a non-standard suffix (@xref{Overall Options}), you will also need
+to provide a @option{-x c++} option too.@footnote{Some users like to
+distinguish module interface files with a new suffix, such as naming
+the source @code{module.cppm}, which involves
+teaching all tools about the new suffix. A different scheme, such as
+naming @code{module-m.cpp} would be less invasive.}
+
+Compiling a module interface unit produces an additional output (to
+the assembly or object file), called a Compiled Module Interface
+(CMI). This encodes the exported declarations of the module.
+Importing a module reads in the CMI. The import graph is a Directed
+Acyclic Graph (DAG). You must build imports before the importer.
+
+Header files may themselves be compiled to header units, which are a
+transitional ability aiming at faster compilation. The
+@option{-fmodule-header} option is used to enable this, and implies
+the @option{-fmodules-ts} option. These CMIs are named by the fully
+resolved underlying header file, and thus may be a complete pathname
+containing subdirectories. If the header file is found at an absolute
+pathname, the CMI location is still relative to a CMI root directory.
+
+As header files often have no suffix, you commonly have to specify a
+@option{-x} option to tell the compiler the source is a header file.
+You may use @option{-x c++-header}, @option{-x c++-user-header} or
+@option{-x c++-system-header}. When used in conjunction with
+@option{-fmodules-ts}, these all imply an appropriate
+@option{-fmodule-header} option. The latter two variants will use the
+user or system include path to search for the file specified. This
+allows you to, for instance, compile standard library header files as
+header units, without needing to know exactly where they are
+installed. Specifying the language as one of these variants also
+inhibits output of the object file, as header files have no associated
+object file.
+
+When creating an output CMI, any missing directory components are
+created in a manner that is safe for concurrent builds creating
+multiple, different, CMIs within a common subdirectory tree.
+
+CMI contents are written to a temporary file, which is then atomically
+renamed. Observers will either see old contents (if there is an
+existing file), or complete new contents. They will not observe the
+CMI during its creation. This is unlike object file writing, which
+may be observed by an external process.
+
+CMIs are read in lazily, if the host OS provides @code{mmap}
+functionality. Generally blocks are read when name lookup or template
+instantiation occurs. To inhibit this, the @option{-fno-module-lazy}
+option may be used.
+
+The @option{-fmodule-only} option disables generation of the
+associated object file for compiling a module interface. Only the CMI
+is generated. This option is implied when using the
+@option{-fmodule-header} option.
+
+The @option{--param lazy-modules=@var{n}} parameter controls the limit
+on the number of concurrently open module files during lazy loading.
+Should more modules be imported, an LRU algorithm is used to determine
+which files to close -- until that file is needed again. This limit
+may be exceeded with deep module dependency hierarchies. With large
+code bases there may be more imports than the process limit of file
+descriptors. By default, the limit is a few less than the per-process
+file descriptor hard limit, if that is determinable.@footnote{Where
+applicable the soft limit is incremented as needed towards the hard limit.}
+
+The @option{-flang-info-include-translate} option notes whether
+include translation occurs. With no argument, all include translation
+is noted. Otherwise, queries about include translation of a specific
+header file is noted. The latter form may be repeated. This option
+may be helpful in determining whether include translation is
+happenning -- if it is working correctly, it'll behave as if it wasn't
+there at all.
+
+The @option{-Winvalid-imported-macros} option causes all imported macros
+to be resolved at the end of compilation. Without this, imported
+macros are only resolved when expanded or (re)defined. This option
+will detect conflicting import definitions for all macros.
+
+@xref{C++ Module Mapper} for details of the @option{-fmodule-mapper}
+family of options.
+
+@menu
+* C++ Module Mapper:: Module Mapper
+* C++ Module Preprocessing:: Module Preprocessing
+@end menu
+
+@node C++ Module Mapper
+@subsection Module Mapper
+@cindex C++ Module Mapper
+
+A module mapper provides a server or file that the compiler queries to
+determine the mapping between module names and CMI files. It is also
+used to build CMIs on demand. @emph{Mapper functionality is in its
+infancy and is intended for experimentation with build system
+interactions.}
+
+A mapper may be specified with the @option{-fmodule-mapper=@var{val}}
+option or @env{CXX_MODULE_MAPPER} environment variable. The value may
+have one of the following forms:
+
+@table @gcctabopt
+
+@item @r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
+An optional hostname and a numeric port number to connect to. If the
+hostname is omitted, the loopback address is used. If the hostname
+corresponds to multiple IPV6 addresses, these are tried in turn, until
+one is successful. If your host lacks IPv6, this form is
+non-functional. If you must use IPv4 use
+@option{-fmodule-mapper='|ncat @var{ipv4host} @var{port}'}.
+
+@item =@var{socket}@r{[}?@var{ident}@r{]}
+A local domain socket. If your host lacks local domain sockets, this
+form is non-functional.
+
+@item |@var{program}@r{[}?@var{ident}@r{]} @r{[}@var{args...}@r{]}
+A program to spawn, and communicate with on its stdin/stdout streams.
+Your @var{PATH} environment variable is searched for the program.
+Arguments are separated by space characters, (it is not possible for
+one of the arguments delivered to the program to contain a space). An
+exception is if @var{program} begins with @@. In that case
+@var{program} (sans @@) is looked for in the compiler's internal
+binary directory. Thus the sample mapper-server can be specified
+with @code{@@g++-mapper-server}.
+
+@item <>@r{[}?@var{ident}@r{]}
+@item <>@var{fdinout}@r{[}?@var{ident}@r{]}
+@item <@var{fdin}>@var{fdout}@r{[}?@var{ident}@r{]}
+File descriptors to communicate over. The first form, @option{<>},
+communicates over stdin and stdout. The second form specifies a
+bidirectional file descriptor and the last form allows specifying
+two independent descriptors. Note that other compiler options might
+cause the compiler to read stdin or write stdout.
+
+@item @var{file}@r{[}?@var{ident}@r{]}
+A mapping file consisting of space-separated module-name, filename
+pairs, one per line. Only the mappings for the direct imports and any
+module export name need be provided. If other mappings are provided,
+they override those stored in any imported CMI files. A repository
+root may be specified in the mapping file by using @samp{$root} as the
+module name in the first active line.
+
+@end table
+
+As shown, an optional @var{ident} may suffix the first word of the
+option, indicated by a @samp{?} prefix. The value is used in the
+initial handshake with the module server, or to specify a prefix on
+mapping file lines. In the server case, the main source file name is
+used if no @var{ident} is specified. In the file case, all non-blank
+lines are significant, unless a value is specified, in which case only
+lines beginning with @var{ident} are significant. The @var{ident}
+must be separated by whitespace from the module name. Be aware that
+@samp{<}, @samp{>}, @samp{?}, and @samp{|} characters are often
+significant to the shell, and therefore may need quoting.
+
+The mapper is connected to or loaded lazily, when the first module
+mapping is required. The networking protocols are only supported on
+hosts that provide networking. If no mapper is specified a default is
+provided.
+
+A project-specific mapper is expected to be provided by the build
+system that invokes the compiler. It is not expected that a
+general-purpose server is provided for all compilations. As such, the
+server will know the build configuration, the compiler it invoked, and
+the environment (such as working directory) in which that is
+operating. As it may parallelize builds, several compilations may
+connect to the same socket.
+
+The default mapper generates CMI files in a @samp{gcm.cache}
+directory. CMI files have a @samp{.gcm} suffix. The module unit name
+is used directly to provide the basename. Header units construct a
+relative path using the underlying header file name. If the path is
+already relative, a @samp{,} directory is prepended. Internal
+@samp{..} components are translated to @samp{,,}. No attempt is made
+to canonicalize these filenames beyond that done by the preprocessor's
+include search algorithm, as in general it is ambiguous when symbolic
+links are present.
+
+The mapper protocol was published as ``A Module Mapper''
+@uref{https://wg21.link/p1184}. The implementation is provided by
+@command{libcody}, @uref{https://www.github.com/urnathan/libcody},
+which specifies the canonical protocol definition. A proof of concept
+server implementation embedded in @command{make} was described in
+''Make Me A Module'', @uref{https://wg21.link/p1602}.
+
+@node C++ Module Preprocessing
+@subsection Module Preprocessing
+@cindex C++ Module Preprocessing
+
+Modules affect preprocessing because of header units and include
+translation. Some uses of the preprocessor as a separate step will
+either not produce a correct output, or require CMIs to be available.
+
+Header units import macros. These macros can affect later conditional
+inclusion, which therefore can cascade to differing import sets. When
+preprocessing, it is necessary to load the CMI. If a header unit is
+unavailable, the preprocessor will issue a warning and continue (when
+not just preprocessing, an error is emitted). Detecting such imports
+requires preprocessor tokenization of the input stream to phase 4
+(macro expansion).
+
+Include translation converts @code{#include}, @code{#include_next} and
+@code{#import} directives to internal @code{import} declarations.
+Whether a particular directive is translated is controlled by the
+module mapper. Header unit names are canonicalized during
+preprocessing.
+
+Dependency information can be emitted for macro import, extending the
+functionality of @option{-MD} and @option{-MMD} options. Detection of
+import declarations also requires phase 4 preprocessing, and thus
+requires full preprocessing (or compilation).
+
+The @option{-M}, @option{-MM} and @option{-E -fdirectives-only} options halt
+preprocessing before phase 4.
+
+The @option{-save-temps} option will use @option{-fdirectives-only}
+for preprocessing, and preserve the macro definitions in the
+preprocessed output. Usually you will also want to use this option
+when explicitly preprocessing a header-unit, or consuming such
+preprocessed output:
+
+@smallexample
+g++ -fmodules-ts -E -fdirectives-only my-header.hh -o my-header.ii
+g++ -x c++-header -fmodules-ts -fpreprocessed -fdirectives-only my-header.ii
+@end smallexample
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Modules doc
2020-11-20 16:45 ` Marek Polacek
2020-11-20 17:12 ` Nathan Sidwell
@ 2020-11-24 7:11 ` Boris Kolpackov
1 sibling, 0 replies; 6+ messages in thread
From: Boris Kolpackov @ 2020-11-24 7:11 UTC (permalink / raw)
To: gcc-patches
Marek Polacek <polacek@redhat.com> writes:
> > +Only emit the module CMI, inhibiting any object file.
>
> Maybe say here that CMI is Compiled Module Interface.
FYI, SG15 (WG21 study group on tooling) seems to have settled
on BMI ("built module interface"):
https://github.com/cplusplus/modules-ecosystem-tr/blob/master/definitions.tex
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Modules doc
2020-11-20 17:12 ` Nathan Sidwell
@ 2020-11-30 6:33 ` Sandra Loosemore
2020-11-30 13:14 ` Nathan Sidwell
0 siblings, 1 reply; 6+ messages in thread
From: Sandra Loosemore @ 2020-11-30 6:33 UTC (permalink / raw)
To: Nathan Sidwell, Marek Polacek; +Cc: GCC Patches
On 11/20/20 10:12 AM, Nathan Sidwell wrote:
> @@ -214,14 +215,21 @@ in the following sections.
> -faligned-new=@var{n} -fargs-in-order=@var{n} -fchar8_t -fcheck-new @gol
> -fconstexpr-depth=@var{n} -fconstexpr-cache-depth=@var{n} @gol
> -fconstexpr-loop-limit=@var{n} -fconstexpr-ops-limit=@var{n} @gol
> +-fmodule-header@r{[}=@var{kind}@r{]} -fmodule-only -fmodules-ts @gol
> +-fmodule-implicit-inline @gol
> +-fmodule-mapper=@var{specification} @gol
> +-fmodule-version-ignore @gol
> -fno-elide-constructors @gol
> -fno-enforce-eh-specs @gol
> -fno-gnu-keywords @gol
> -fno-implicit-templates @gol
> -fno-implicit-inline-templates @gol
> --fno-implement-inlines -fms-extensions @gol
> +-fno-implement-inlines @gol
> +-fno-module-lazy @gol
> +-fms-extensions @gol
> -fnew-inheriting-ctors @gol
> -fnew-ttp-matching @gol
> +-fno-module-lazy @gol
> -fno-nonansi-builtins -fnothrow-opt -fno-operator-names @gol
> -fno-optional-diags -fpermissive @gol
> -fno-pretty-templates @gol
It looks to me like this table is currently alphabetized ignoring "no-"
prefixes. Your additions don't match that convention.
> @@ -233,12 +241,14 @@ in the following sections.
> -fvisibility-inlines-hidden @gol
> -fvisibility-ms-compat @gol
> -fext-numeric-literals @gol
> +-flang-info-include-translate@r{[}=@var{name}@r{]} @gol
> -Wabi-tag -Wcatch-value -Wcatch-value=@var{n} @gol
> -Wno-class-conversion -Wclass-memaccess @gol
> -Wcomma-subscript -Wconditionally-supported @gol
> -Wno-conversion-null -Wctad-maybe-unsupported @gol
> -Wctor-dtor-privacy -Wno-delete-incomplete @gol
> --Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
> +-Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
> +-Winvalid-imported-macros @gol
> -Wno-deprecated-enum-enum-conversion -Wno-deprecated-enum-float-conversion @gol
> -Weffc++ -Wno-exceptions -Wextra-semi -Wno-inaccessible-base @gol
> -Wno-inherited-variadic-ctor -Wno-init-list-lifetime @gol
Ditto here.
> @@ -599,7 +609,7 @@ Objective-C and Objective-C++ Dialects}.
> -fpreprocessed -ftabstop=@var{width} -ftrack-macro-expansion @gol
> -fwide-exec-charset=@var{charset} -fworking-directory @gol
> -H -imacros @var{file} -include @var{file} @gol
> --M -MD -MF -MG -MM -MMD -MP -MQ -MT @gol
> +-M -MD -MF -MG -MM -MMD -MP -Mno-modules -MQ -MT @gol
> -no-integrated-cpp -P -pthread -remap @gol
> -traditional -traditional-cpp -trigraphs @gol
> -U@var{macro} -undef @gol
And this seems like a totally random place to insert the new option...
> +@item -fmodule-header
> +@itemx -fmodule-header=user
> +@itemx -fmodule-header=system
> +@opindex fmodule-header
> +Compile a header file to create an importableheader unit.
Is that a typo for "importable header", or some jargon?
> +@item -fmodule-implicit-inline
> +@opindex fmodule-implicit-inline
> +Member functions defined in their class definitions are not implicitly
> +inline for modular code. This is different to traditional C++
> +behavior, for good reasons. However, it may result in a difficulty
> +during code porting. This option will make such function definitions
s/will make/makes/
> @@ -3303,6 +3359,12 @@ for ISO C++11 onwards (@option{-std=c++11}, ...).
> Do not search for header files in the standard directories specific to
> C++, but do still search the other standard directories. (This option
> is used when building the C++ library.)
> +
> +@item -flang-info-include-translate
> +@itemx -flang-info-include-translate=@var{header}
> +@opindex flang-info-include-translate
> +Give notice of include translation events.
> +
What does "give notice" mean? I don't see that term used elsewhere in
the documentation.
> +@item Textual merging of reachable GM entities
> +Entities may be multiply defined across different header-units.
> +These must be de-duplicated, and this is implemented across imports,
> +or when an import redefines a textually-defined entity. However the
> +reverse is not implemented -- textually redefining an entity that has
> +been defined in an imported header-unit. A redefinition error will be
> +emitted.
In Texinfo an em-dash is represented by "---" without spaces on either side.
Also, s/will be/is/, unless you are explicitly talking about something
that will happen when the implementation is finished and not current
behavior.
> +No new source file suffixes are required or supported. If you wish to
> +use a non-standard suffix (@xref{Overall Options}), you will also need
s/will //
> +As header files often have no suffix, you commonly have to specify a
> +@option{-x} option to tell the compiler the source is a header file.
> +You may use @option{-x c++-header}, @option{-x c++-user-header} or
> +@option{-x c++-system-header}. When used in conjunction with
> +@option{-fmodules-ts}, these all imply an appropriate
> +@option{-fmodule-header} option. The latter two variants will use the
Here too.
> +CMI contents are written to a temporary file, which is then atomically
> +renamed. Observers will either see old contents (if there is an
> +existing file), or complete new contents. They will not observe the
> +CMI during its creation. This is unlike object file writing, which
> +may be observed by an external process.
I think both instances here, too, since this appears to be talking about
something that happens concurrently with compilation and not at some
point in the future.
> +The @option{--param lazy-modules=@var{n}} parameter controls the limit
> +on the number of concurrently open module files during lazy loading.
> +Should more modules be imported, an LRU algorithm is used to determine
> +which files to close -- until that file is needed again. This limit
Em-dash syntax again.
> +The @option{-flang-info-include-translate} option notes whether
> +include translation occurs. With no argument, all include translation
> +is noted. Otherwise, queries about include translation of a specific
> +header file is noted. The latter form may be repeated. This option
> +may be helpful in determining whether include translation is
> +happenning -- if it is working correctly, it'll behave as if it wasn't
> +there at all.
Here too, plus s/happenning/happening/
> +The @option{-Winvalid-imported-macros} option causes all imported macros
> +to be resolved at the end of compilation. Without this, imported
> +macros are only resolved when expanded or (re)defined. This option
> +will detect conflicting import definitions for all macros.
s/will detect/detects/
> +A mapper may be specified with the @option{-fmodule-mapper=@var{val}}
> +option or @env{CXX_MODULE_MAPPER} environment variable. The value may
> +have one of the following forms:
Eh, let's put this in an active voice. "You can specify a mapper...."
> +Modules affect preprocessing because of header units and include
> +translation. Some uses of the preprocessor as a separate step will
> +either not produce a correct output, or require CMIs to be available.
...separate step either do not... or require....
> +Header units import macros. These macros can affect later conditional
> +inclusion, which therefore can cascade to differing import sets. When
> +preprocessing, it is necessary to load the CMI. If a header unit is
> +unavailable, the preprocessor will issue a warning and continue (when
s/will issue/issues/, unless this is not implemented yet
> +The @option{-save-temps} option will use @option{-fdirectives-only}
Similar problem here.
> +for preprocessing, and preserve the macro definitions in the
> +preprocessed output. Usually you will also want to use this option
And here.
This is all nit-picky copy-editing stuff.... I haven't made any real
effort to understand the features being documented here, as my C++
knowledge has been swapped out for Fortran lately. :-(
-Sandra
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: Modules doc
2020-11-30 6:33 ` Sandra Loosemore
@ 2020-11-30 13:14 ` Nathan Sidwell
0 siblings, 0 replies; 6+ messages in thread
From: Nathan Sidwell @ 2020-11-30 13:14 UTC (permalink / raw)
To: Sandra Loosemore, Marek Polacek; +Cc: GCC Patches
[-- Attachment #1: Type: text/plain, Size: 1286 bytes --]
Sandra,
thanks for the review, I believe I've addressed all the nits you found
except for ...
On 11/30/20 1:33 AM, Sandra Loosemore wrote:
> On 11/20/20 10:12 AM, Nathan Sidwell wrote:
>> @@ -599,7 +609,7 @@ Objective-C and Objective-C++ Dialects}.
>> -fpreprocessed -ftabstop=@var{width} -ftrack-macro-expansion @gol
>> -fwide-exec-charset=@var{charset} -fworking-directory @gol
>> -H -imacros @var{file} -include @var{file} @gol
>> --M -MD -MF -MG -MM -MMD -MP -MQ -MT @gol
>> +-M -MD -MF -MG -MM -MMD -MP -Mno-modules -MQ -MT @gol
>> -no-integrated-cpp -P -pthread -remap @gol
>> -traditional -traditional-cpp -trigraphs @gol
>> -U@var{macro} -undef @gol
>
> And this seems like a totally random place to insert the new option...
This is a preprocessor option to not emit dependency information about
modules (added to cppopt.texi). The -M$LETTER idiom seems to be what we
use for that set of options, and rather than grab another letter I chose
a word. There was a brief IRC #gcc conversation about the best way to
go there.
I did move it to be case-sensitive collated ignoring the 'no-' prefix
though.
FWIW, we may independently grow -Mjson and -Mmake in the same way.
nathan
--
Nathan Sidwell
[-- Attachment #2: 12b-core-doc.diff --]
[-- Type: text/x-patch, Size: 27691 bytes --]
diff --git c/gcc/doc/cppopts.texi w/gcc/doc/cppopts.texi
index 7f1849d841f..e5ece92487b 100644
--- c/gcc/doc/cppopts.texi
+++ w/gcc/doc/cppopts.texi
@@ -139,6 +139,10 @@ this useless.
This feature is used in automatic updating of makefiles.
+@item -Mno-modules
+@opindex Mno-modules
+Disable dependency generation for compiled module interfaces.
+
@item -MP
@opindex MP
This option instructs CPP to add a phony target for each dependency
diff --git c/gcc/doc/extend.texi w/gcc/doc/extend.texi
index 23ede966bae..f0269422ca2 100644
--- c/gcc/doc/extend.texi
+++ w/gcc/doc/extend.texi
@@ -7426,23 +7426,9 @@ The @code{weak} attribute is described in
@cindex @code{noinit} variable attribute
Any data with the @code{noinit} attribute will not be initialized by
the C runtime startup code, or the program loader. Not initializing
-data in this way can reduce program startup times.
-
-This attribute is specific to ELF targets and relies on the linker
-script to place sections with the @code{.noinit} prefix in the right
-location.
-
-@item persistent
-@cindex @code{persistent} variable attribute
-Any data with the @code{persistent} attribute will not be initialized by
-the C runtime startup code, but will be initialized by the program
-loader. This enables the value of the variable to @samp{persist}
-between processor resets.
-
-This attribute is specific to ELF targets and relies on the linker
-script to place the sections with the @code{.persistent} prefix in the
-right location. Specifically, some type of non-volatile, writeable
-memory is required.
+data in this way can reduce program startup times. This attribute is
+specific to ELF targets and relies on the linker to place such data in
+the right location
@item objc_nullability (@var{nullability kind}) @r{(Objective-C and Objective-C++ only)}
@cindex @code{objc_nullability} variable attribute
@@ -7863,6 +7849,23 @@ The @code{shared} attribute is only available on Microsoft Windows@.
@subsection MSP430 Variable Attributes
@table @code
+@item noinit
+@cindex @code{noinit} variable attribute, MSP430
+Any data with the @code{noinit} attribute will not be initialised by
+the C runtime startup code, or the program loader. Not initialising
+data in this way can reduce program startup times.
+
+@item persistent
+@cindex @code{persistent} variable attribute, MSP430
+Any variable with the @code{persistent} attribute will not be
+initialised by the C runtime startup code. Instead its value will be
+set once, when the application is loaded, and then never initialised
+again, even if the processor is reset or the program restarts.
+Persistent data is intended to be placed into FLASH RAM, where its
+value will be retained across resets. The linker script being used to
+create the application should ensure that persistent data is correctly
+placed.
+
@item upper
@itemx either
@cindex @code{upper} variable attribute, MSP430
diff --git c/gcc/doc/install.texi w/gcc/doc/install.texi
index 8c55da373f8..297831fda55 100644
--- c/gcc/doc/install.texi
+++ w/gcc/doc/install.texi
@@ -464,9 +464,6 @@ Necessary when modifying @command{gperf} input files, e.g.@:
@item DejaGnu 1.4.4
@itemx Expect
@itemx Tcl
-@c Once Tcl 8.5 or higher is required, remove any obsolete
-@c compatibility workarounds:
-@c git grep 'compatibility with earlier Tcl releases'
Necessary to run the GCC testsuite; see the section on testing for
details.
@@ -2801,10 +2798,6 @@ Arranges for the run time of each program started by the GCC driver,
built in any stage, to be logged to @file{time.log}, in the top level of
the build tree.
-@item @samp{bootstrap-asan}
-Compiles GCC itself using Address Sanitization in order to catch invalid memory
-accesses within the GCC code.
-
@end table
@section Building a cross compiler
diff --git c/gcc/doc/invoke.texi w/gcc/doc/invoke.texi
index 896a3081a8b..d882b1827bb 100644
--- c/gcc/doc/invoke.texi
+++ w/gcc/doc/invoke.texi
@@ -172,6 +172,7 @@ listing and explanation of the binary and decimal byte size prefixes.
* Spec Files:: How to pass switches to sub-processes.
* Environment Variables:: Env vars that affect GCC.
* Precompiled Headers:: Compiling a header once, and using it many times.
+* C++ Modules:: Experimental C++20 module system.
@end menu
@c man begin OPTIONS
@@ -219,7 +220,13 @@ in the following sections.
-fno-gnu-keywords @gol
-fno-implicit-templates @gol
-fno-implicit-inline-templates @gol
--fno-implement-inlines -fms-extensions @gol
+-fno-implement-inlines @gol
+-fmodule-header@r{[}=@var{kind}@r{]} -fmodule-only -fmodules-ts @gol
+-fmodule-implicit-inline @gol
+-fno-module-lazy @gol
+-fmodule-mapper=@var{specification} @gol
+-fmodule-version-ignore @gol
+-fms-extensions @gol
-fnew-inheriting-ctors @gol
-fnew-ttp-matching @gol
-fno-nonansi-builtins -fnothrow-opt -fno-operator-names @gol
@@ -233,15 +240,18 @@ in the following sections.
-fvisibility-inlines-hidden @gol
-fvisibility-ms-compat @gol
-fext-numeric-literals @gol
+-flang-info-include-translate@r{[}=@var{name}@r{]} @gol
+-flang-info-include-translate-not @gol
-Wabi-tag -Wcatch-value -Wcatch-value=@var{n} @gol
-Wno-class-conversion -Wclass-memaccess @gol
-Wcomma-subscript -Wconditionally-supported @gol
-Wno-conversion-null -Wctad-maybe-unsupported @gol
-Wctor-dtor-privacy -Wno-delete-incomplete @gol
--Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
+-Wdelete-non-virtual-dtor -Wdeprecated-copy -Wdeprecated-copy-dtor @gol
-Wno-deprecated-enum-enum-conversion -Wno-deprecated-enum-float-conversion @gol
-Weffc++ -Wno-exceptions -Wextra-semi -Wno-inaccessible-base @gol
-Wno-inherited-variadic-ctor -Wno-init-list-lifetime @gol
+-Winvalid-imported-macros @gol
-Wno-invalid-offsetof -Wno-literal-suffix -Wmismatched-tags @gol
-Wmultiple-inheritance -Wnamespaces -Wnarrowing @gol
-Wnoexcept -Wnoexcept-type -Wnon-virtual-dtor @gol
@@ -599,7 +609,7 @@ Objective-C and Objective-C++ Dialects}.
-fpreprocessed -ftabstop=@var{width} -ftrack-macro-expansion @gol
-fwide-exec-charset=@var{charset} -fworking-directory @gol
-H -imacros @var{file} -include @var{file} @gol
--M -MD -MF -MG -MM -MMD -MP -MQ -MT @gol
+-M -MD -MF -MG -MM -MMD -MP -MQ -MT -Mno-modules @gol
-no-integrated-cpp -P -pthread -remap @gol
-traditional -traditional-cpp -trigraphs @gol
-U@var{macro} -undef @gol
@@ -1571,7 +1581,7 @@ name suffix). This option applies to all following input files until
the next @option{-x} option. Possible values for @var{language} are:
@smallexample
c c-header cpp-output
-c++ c++-header c++-cpp-output
+c++ c++-header c++-system-header c++-user-header c++-cpp-output
objective-c objective-c-header objective-c-cpp-output
objective-c++ objective-c++-header objective-c++-cpp-output
assembler assembler-with-cpp
@@ -3056,6 +3066,52 @@ To save space, do not emit out-of-line copies of inline functions
controlled by @code{#pragma implementation}. This causes linker
errors if these functions are not inlined everywhere they are called.
+@item -fmodules-ts
+@itemx -fno-modules-ts
+@opindex fmodules-ts
+@opindex fno-modules-ts
+Enable support for C++20 modules (@xref{C++ Modules}). The
+@option{-fno-modules-ts} is usually not needed, as that is the
+default. Even though this is a C++20 feature, it is not currently
+implicitly enabled by selecting that standard version.
+
+@item -fmodule-header
+@itemx -fmodule-header=user
+@itemx -fmodule-header=system
+@opindex fmodule-header
+Compile a header file to create an importable header unit.
+
+@item -fmodule-implicit-inline
+@opindex fmodule-implicit-inline
+Member functions defined in their class definitions are not implicitly
+inline for modular code. This is different to traditional C++
+behavior, for good reasons. However, it may result in a difficulty
+during code porting. This option makes such function definitions
+implicitly inline. It does however generate an ABI incompatibility,
+so you must use it everywhere or nowhere. (Such definitions outside
+of a named module remain implicitly inline, regardless.)
+
+@item -fno-module-lazy
+@opindex fno-module-lazy
+@opindex fmodule-lazy
+Disable lazy module importing and module mapper creation.
+
+@item -fmodule-mapper=@r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=|@var{program}@r{[}?@var{ident}@r{]} @var{args...}
+@itemx -fmodule-mapper==@var{socket}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=<>@r{[}@var{fdinout}@r{]}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=<@var{fdin}>@var{fdout}@r{[}?@var{ident}@r{]}
+@itemx -fmodule-mapper=@var{file}@r{[}?@var{ident}@r{]}
+@vindex CXX_MODULE_MAPPER @r{environment variable}
+@opindex fmodule-mapper
+An oracle to query for module name to filename mappings. If
+unspecified the @env{CXX_MODULE_MAPPER} environment variable is used,
+and if that is unset, an in-process default is provided.
+
+@item -fmodule-only
+@opindex fmodule-only
+Only emit the Compiled Module Interface, inhibiting any object file.
+
@item -fms-extensions
@opindex fms-extensions
Disable Wpedantic warnings about constructs used in MFC, such as implicit
@@ -3303,6 +3359,14 @@ for ISO C++11 onwards (@option{-std=c++11}, ...).
Do not search for header files in the standard directories specific to
C++, but do still search the other standard directories. (This option
is used when building the C++ library.)
+
+@item -flang-info-include-translate
+@itemx -flang-info-include-translate-not
+@itemx -flang-info-include-translate=@var{header}
+@opindex flang-info-include-translate
+@opindex flang-info-include-translate-not
+Diagnose include translation events.
+
@end table
In addition, these warning options have meanings only for C++ programs:
@@ -3460,6 +3524,14 @@ the variable declaration statement.
@end itemize
+@item -Winvalid-imported-macros
+@opindex Winvalid-imported-macros
+@opindex Wno-invalid-imported-macros
+Verify all imported macro definitions are valid at the end of
+compilation. This is not enabled by default, as it requires
+additional processing to determine. It may be useful when preparing
+sets of header-units to ensure consistent macros.
+
@item -Wno-literal-suffix @r{(C++ and Objective-C++ only)}
@opindex Wliteral-suffix
@opindex Wno-literal-suffix
@@ -3681,23 +3753,7 @@ void fn () @{
@end smallexample
It does not warn when the type being copied is a trivially-copyable type whose
-size is less than 64 bytes.
-
-This warning also warns when a loop variable in a range-based for-loop is
-initialized with a value of a different type resulting in a copy. For example:
-
-@smallexample
-void fn() @{
- int arr[10];
- for (const double &x : arr) @{ @dots{} @}
-@}
-@end smallexample
-
-In the example above, in every iteration of the loop a temporary value of
-type @code{double} is created and destroyed, to which the reference
-@code{const double &} is bound.
-
-This warning is enabled by @option{-Wall}.
+size is less than 64 bytes. This warning is enabled by @option{-Wall}.
@item -Wredundant-tags @r{(C++ and Objective-C++ only)}
@opindex Wredundant-tags
@@ -12342,10 +12398,10 @@ is unpredictable.
@opindex ffast-math
Sets the options @option{-fno-math-errno}, @option{-funsafe-math-optimizations},
@option{-ffinite-math-only}, @option{-fno-rounding-math},
-@option{-fcx-limited-range} and @option{-fexcess-precision=fast}.
+@option{-fno-signaling-nans}, @option{-fcx-limited-range} and
+@option{-fexcess-precision=fast}.
-Whenever all these options listed above are set to those values,
-the preprocessor macro @code{__FAST_MATH__} will be defined.
+This option causes the preprocessor macro @code{__FAST_MATH__} to be defined.
This option is not turned on by any @option{-O} option besides
@option{-Ofast} since it can result in incorrect output for programs
@@ -16744,6 +16800,11 @@ By default, the dump will contain messages about successful
optimizations (equivalent to @option{-optimized}) together with
low-level details about the analysis.
+@item -fdump-lang
+@opindex fdump-lang
+Dump language-specific information. The file name is made by appending
+@file{.lang} to the source file name.
+
@item -fdump-lang-all
@itemx -fdump-lang-@var{switch}
@itemx -fdump-lang-@var{switch}-@var{options}
@@ -16764,6 +16825,14 @@ Enable all language-specific dumps.
Dump class hierarchy information. Virtual table information is emitted
unless '@option{slim}' is specified. This option is applicable to C++ only.
+@item module
+Dump module information. Options @option{lineno} (locations),
+@option{graph} (reachability), @option{blocks} (clusters),
+@option{uid} (serialization), @option{alias} (mergeable),
+@option{asmname} (Elrond), @option{eh} (mapper) & @option{vops}
+(macros) may provide additional information. This option is
+applicable to C++ only.
+
@item raw
Dump the raw internal tree data. This option is applicable to C++ only.
@@ -31948,7 +32017,7 @@ usage:
@item @code{sanitize}
The @code{sanitize} spec function takes no arguments. It returns non-NULL if
-any address, thread or undefined behaviour sanitizers are active.
+any address, thread or undefined behavior sanitizers are active.
@smallexample
%@{%:sanitize(address):-funwind-tables@}
@@ -32508,3 +32577,279 @@ precompiled header, the actual behavior is a mixture of the
behavior for the options. For instance, if you use @option{-g} to
generate the precompiled header but not when using it, you may or may
not get debugging information for routines in the precompiled header.
+
+@node C++ Modules
+@section C++ Modules
+@cindex speed of compilation
+
+Modules are a C++ 20 language feature. As the name suggests, it
+provides a modular compilation system, intending to provide both
+faster builds and better library isolation. The ``Merging Modules''
+paper @uref{https://wg21.link/p1103}, provides the easiest to read set
+of changes to the standard, although it does not capture later
+changes. That specification is now part of C++20,
+@uref{git@@github.com:cplusplus/draft.git}, it is considered complete
+(there may be defect reports to come).
+
+@emph{G++'s modules support is not complete.} Other than bugs, the
+known missing pieces are:
+
+@table @emph
+
+@item Private Module Fragment
+The Private Module Fragment is recognized, but an error is emitted.
+
+@item Partition definition visibility rules
+Entities may be defined in implementation partitions, and those
+definitions are not available outside of the module. This is not
+implemented, and the definitions are available to extra-module use.
+
+@item Textual merging of reachable GM entities
+Entities may be multiply defined across different header-units.
+These must be de-duplicated, and this is implemented across imports,
+or when an import redefines a textually-defined entity. However the
+reverse is not implemented---textually redefining an entity that has
+been defined in an imported header-unit. A redefinition error is
+emitted.
+
+@item Translation-Unit local referencing rules
+Papers p1815 (@uref{https://wg21.link/p1815}) and p2003
+(@uref{https://wg21.link/p2003} add limitations on which entities an
+exported region may reference (for instance, the entities an exported
+template definition may reference). These are not fully implemented.
+
+@end table
+
+Modular compilation is @emph{not} enabled with just the
+@option{-std=c++20} option. You must explicitly enable it with the
+@option{-fmodules-ts} option. It is independent of the language
+version selected, although in pre-C++20 versions, it is of course an
+extension.
+
+No new source file suffixes are required or supported. If you wish to
+use a non-standard suffix (@xref{Overall Options}), you also need
+to provide a @option{-x c++} option too.@footnote{Some users like to
+distinguish module interface files with a new suffix, such as naming
+the source @code{module.cppm}, which involves
+teaching all tools about the new suffix. A different scheme, such as
+naming @code{module-m.cpp} would be less invasive.}
+
+Compiling a module interface unit produces an additional output (to
+the assembly or object file), called a Compiled Module Interface
+(CMI). This encodes the exported declarations of the module.
+Importing a module reads in the CMI. The import graph is a Directed
+Acyclic Graph (DAG). You must build imports before the importer.
+
+Header files may themselves be compiled to header units, which are a
+transitional ability aiming at faster compilation. The
+@option{-fmodule-header} option is used to enable this, and implies
+the @option{-fmodules-ts} option. These CMIs are named by the fully
+resolved underlying header file, and thus may be a complete pathname
+containing subdirectories. If the header file is found at an absolute
+pathname, the CMI location is still relative to a CMI root directory.
+
+As header files often have no suffix, you commonly have to specify a
+@option{-x} option to tell the compiler the source is a header file.
+You may use @option{-x c++-header}, @option{-x c++-user-header} or
+@option{-x c++-system-header}. When used in conjunction with
+@option{-fmodules-ts}, these all imply an appropriate
+@option{-fmodule-header} option. The latter two variants use the
+user or system include path to search for the file specified. This
+allows you to, for instance, compile standard library header files as
+header units, without needing to know exactly where they are
+installed. Specifying the language as one of these variants also
+inhibits output of the object file, as header files have no associated
+object file.
+
+When creating an output CMI, any missing directory components are
+created in a manner that is safe for concurrent builds creating
+multiple, different, CMIs within a common subdirectory tree.
+
+CMI contents are written to a temporary file, which is then atomically
+renamed. Observers either see old contents (if there is an
+existing file), or complete new contents. They do not observe the
+CMI during its creation. This is unlike object file writing, which
+may be observed by an external process.
+
+CMIs are read in lazily, if the host OS provides @code{mmap}
+functionality. Generally blocks are read when name lookup or template
+instantiation occurs. To inhibit this, the @option{-fno-module-lazy}
+option may be used.
+
+The @option{-fmodule-only} option disables generation of the
+associated object file for compiling a module interface. Only the CMI
+is generated. This option is implied when using the
+@option{-fmodule-header} option.
+
+The @option{--param lazy-modules=@var{n}} parameter controls the limit
+on the number of concurrently open module files during lazy loading.
+Should more modules be imported, an LRU algorithm is used to determine
+which files to close---until that file is needed again. This limit
+may be exceeded with deep module dependency hierarchies. With large
+code bases there may be more imports than the process limit of file
+descriptors. By default, the limit is a few less than the per-process
+file descriptor hard limit, if that is determinable.@footnote{Where
+applicable the soft limit is incremented as needed towards the hard limit.}
+
+The @option{-flang-info-include-translate} and
+@option{-flang-info-include-translate-not} options notes whether
+include translation occurs or not. With no argument, the first will
+note all include translation. The second will note all
+non-translations of include files not known to intentionally be
+textual. With an argument, queries about include translation of a
+header files with that particular trailing pathname are noted. You
+may repeat this form to cover several different header files. This
+option may be helpful in determining whether include translation is
+happening---if it is working correctly, it'll behave as if it wasn't
+there at all.
+
+The @option{-Winvalid-imported-macros} option causes all imported macros
+to be resolved at the end of compilation. Without this, imported
+macros are only resolved when expanded or (re)defined. This option
+detects conflicting import definitions for all macros.
+
+@xref{C++ Module Mapper} for details of the @option{-fmodule-mapper}
+family of options.
+
+@menu
+* C++ Module Mapper:: Module Mapper
+* C++ Module Preprocessing:: Module Preprocessing
+@end menu
+
+@node C++ Module Mapper
+@subsection Module Mapper
+@cindex C++ Module Mapper
+
+A module mapper provides a server or file that the compiler queries to
+determine the mapping between module names and CMI files. It is also
+used to build CMIs on demand. @emph{Mapper functionality is in its
+infancy and is intended for experimentation with build system
+interactions.}
+
+You can specify a mapper with the @option{-fmodule-mapper=@var{val}}
+option or @env{CXX_MODULE_MAPPER} environment variable. The value may
+have one of the following forms:
+
+@table @gcctabopt
+
+@item @r{[}@var{hostname}@r{]}:@var{port}@r{[}?@var{ident}@r{]}
+An optional hostname and a numeric port number to connect to. If the
+hostname is omitted, the loopback address is used. If the hostname
+corresponds to multiple IPV6 addresses, these are tried in turn, until
+one is successful. If your host lacks IPv6, this form is
+non-functional. If you must use IPv4 use
+@option{-fmodule-mapper='|ncat @var{ipv4host} @var{port}'}.
+
+@item =@var{socket}@r{[}?@var{ident}@r{]}
+A local domain socket. If your host lacks local domain sockets, this
+form is non-functional.
+
+@item |@var{program}@r{[}?@var{ident}@r{]} @r{[}@var{args...}@r{]}
+A program to spawn, and communicate with on its stdin/stdout streams.
+Your @var{PATH} environment variable is searched for the program.
+Arguments are separated by space characters, (it is not possible for
+one of the arguments delivered to the program to contain a space). An
+exception is if @var{program} begins with @@. In that case
+@var{program} (sans @@) is looked for in the compiler's internal
+binary directory. Thus the sample mapper-server can be specified
+with @code{@@g++-mapper-server}.
+
+@item <>@r{[}?@var{ident}@r{]}
+@item <>@var{fdinout}@r{[}?@var{ident}@r{]}
+@item <@var{fdin}>@var{fdout}@r{[}?@var{ident}@r{]}
+File descriptors to communicate over. The first form, @option{<>},
+communicates over stdin and stdout. The second form specifies a
+bidirectional file descriptor and the last form allows specifying
+two independent descriptors. Note that other compiler options might
+cause the compiler to read stdin or write stdout.
+
+@item @var{file}@r{[}?@var{ident}@r{]}
+A mapping file consisting of space-separated module-name, filename
+pairs, one per line. Only the mappings for the direct imports and any
+module export name need be provided. If other mappings are provided,
+they override those stored in any imported CMI files. A repository
+root may be specified in the mapping file by using @samp{$root} as the
+module name in the first active line.
+
+@end table
+
+As shown, an optional @var{ident} may suffix the first word of the
+option, indicated by a @samp{?} prefix. The value is used in the
+initial handshake with the module server, or to specify a prefix on
+mapping file lines. In the server case, the main source file name is
+used if no @var{ident} is specified. In the file case, all non-blank
+lines are significant, unless a value is specified, in which case only
+lines beginning with @var{ident} are significant. The @var{ident}
+must be separated by whitespace from the module name. Be aware that
+@samp{<}, @samp{>}, @samp{?}, and @samp{|} characters are often
+significant to the shell, and therefore may need quoting.
+
+The mapper is connected to or loaded lazily, when the first module
+mapping is required. The networking protocols are only supported on
+hosts that provide networking. If no mapper is specified a default is
+provided.
+
+A project-specific mapper is expected to be provided by the build
+system that invokes the compiler. It is not expected that a
+general-purpose server is provided for all compilations. As such, the
+server will know the build configuration, the compiler it invoked, and
+the environment (such as working directory) in which that is
+operating. As it may parallelize builds, several compilations may
+connect to the same socket.
+
+The default mapper generates CMI files in a @samp{gcm.cache}
+directory. CMI files have a @samp{.gcm} suffix. The module unit name
+is used directly to provide the basename. Header units construct a
+relative path using the underlying header file name. If the path is
+already relative, a @samp{,} directory is prepended. Internal
+@samp{..} components are translated to @samp{,,}. No attempt is made
+to canonicalize these filenames beyond that done by the preprocessor's
+include search algorithm, as in general it is ambiguous when symbolic
+links are present.
+
+The mapper protocol was published as ``A Module Mapper''
+@uref{https://wg21.link/p1184}. The implementation is provided by
+@command{libcody}, @uref{https://www.github.com/urnathan/libcody},
+which specifies the canonical protocol definition. A proof of concept
+server implementation embedded in @command{make} was described in
+''Make Me A Module'', @uref{https://wg21.link/p1602}.
+
+@node C++ Module Preprocessing
+@subsection Module Preprocessing
+@cindex C++ Module Preprocessing
+
+Modules affect preprocessing because of header units and include
+translation. Some uses of the preprocessor as a separate step either
+do not produce a correct output, or require CMIs to be available.
+
+Header units import macros. These macros can affect later conditional
+inclusion, which therefore can cascade to differing import sets. When
+preprocessing, it is necessary to load the CMI. If a header unit is
+unavailable, the preprocessor issues a warning and continue (when
+not just preprocessing, an error is emitted). Detecting such imports
+requires preprocessor tokenization of the input stream to phase 4
+(macro expansion).
+
+Include translation converts @code{#include}, @code{#include_next} and
+@code{#import} directives to internal @code{import} declarations.
+Whether a particular directive is translated is controlled by the
+module mapper. Header unit names are canonicalized during
+preprocessing.
+
+Dependency information can be emitted for macro import, extending the
+functionality of @option{-MD} and @option{-MMD} options. Detection of
+import declarations also requires phase 4 preprocessing, and thus
+requires full preprocessing (or compilation).
+
+The @option{-M}, @option{-MM} and @option{-E -fdirectives-only} options halt
+preprocessing before phase 4.
+
+The @option{-save-temps} option uses @option{-fdirectives-only} for
+preprocessing, and preserve the macro definitions in the preprocessed
+output. Usually you also want to use this option when explicitly
+preprocessing a header-unit, or consuming such preprocessed output:
+
+@smallexample
+g++ -fmodules-ts -E -fdirectives-only my-header.hh -o my-header.ii
+g++ -x c++-header -fmodules-ts -fpreprocessed -fdirectives-only my-header.ii
+@end smallexample
diff --git c/gcc/doc/sourcebuild.texi w/gcc/doc/sourcebuild.texi
index 852eaa2e676..566fda02c30 100644
--- c/gcc/doc/sourcebuild.texi
+++ w/gcc/doc/sourcebuild.texi
@@ -2548,9 +2548,6 @@ Target does not generate PIC by default.
@item offload_gcn
Target has been configured for OpenACC/OpenMP offloading on AMD GCN.
-@item persistent
-Target supports the @code{persistent} variable attribute.
-
@item pie_enabled
Target generates PIE by default.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-11-30 13:14 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-20 15:19 Modules doc Nathan Sidwell
2020-11-20 16:45 ` Marek Polacek
2020-11-20 17:12 ` Nathan Sidwell
2020-11-30 6:33 ` Sandra Loosemore
2020-11-30 13:14 ` Nathan Sidwell
2020-11-24 7:11 ` Boris Kolpackov
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).