Modules doc

Marek Polacek polacek@redhat.com
Fri Nov 20 16:45:16 GMT 2020


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



More information about the Gcc-patches mailing list