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