* 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 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
* 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
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).