From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [63.128.21.124]) by sourceware.org (Postfix) with ESMTP id 3D9C43851C17 for ; Fri, 20 Nov 2020 16:45:24 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.3.2 sourceware.org 3D9C43851C17 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-156-USaToJRZMKSrRNWFWeTw6w-1; Fri, 20 Nov 2020 11:45:20 -0500 X-MC-Unique: USaToJRZMKSrRNWFWeTw6w-1 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 803F6100A60B; Fri, 20 Nov 2020 16:45:19 +0000 (UTC) Received: from redhat.com (ovpn-117-202.rdu2.redhat.com [10.10.117.202]) by smtp.corp.redhat.com (Postfix) with ESMTPS id B7E9960853; Fri, 20 Nov 2020 16:45:18 +0000 (UTC) Date: Fri, 20 Nov 2020 11:45:16 -0500 From: Marek Polacek To: Nathan Sidwell Cc: GCC Patches , Sandra Loosemore Subject: Re: Modules doc Message-ID: <20201120164516.GB3996@redhat.com> References: <9c066876-dfe5-778d-aaa4-dd343afe5d35@acm.org> MIME-Version: 1.0 In-Reply-To: <9c066876-dfe5-778d-aaa4-dd343afe5d35@acm.org> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset=us-ascii Content-Disposition: inline X-Spam-Status: No, score=-14.4 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_SHORT, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H4, RCVD_IN_MSPIKE_WL, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.2 X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 20 Nov 2020 16:45:26 -0000 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