r309975 - Don't emit undefined-internal warnings for CXXDeductionGuideDecls.

[Richard Smith via cfe-commits]

Author: rsmith
Date: Thu Aug  3 12:24:27 2017
New Revision: 309975

URL: http://llvm.org/viewvc/llvm-project?rev=309975&view=rev
Log:
Don't emit undefined-internal warnings for CXXDeductionGuideDecls.

Patch by ~paul (cynecx on phabricator)! Some test massaging by me.

Added:
    cfe/trunk/docs/ModuleMaps.rst
      - copied, changed from r307115, cfe/trunk/docs/Modules.rst
    cfe/trunk/docs/ModulesTS.rst
Modified:
    cfe/trunk/docs/Modules.rst
    cfe/trunk/lib/Sema/Sema.cpp
    cfe/trunk/test/SemaCXX/cxx1z-class-template-argument-deduction.cpp

Copied: cfe/trunk/docs/ModuleMaps.rst (from r307115, cfe/trunk/docs/Modules.rst)
URL: 
http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ModuleMaps.rst?p2=cfe/trunk/docs/ModuleMaps.rst&p1=cfe/trunk/docs/Modules.rst&r1=307115&r2=309975&rev=309975&view=diff
==============================================================================
--- cfe/trunk/docs/Modules.rst (original)
+++ cfe/trunk/docs/ModuleMaps.rst Thu Aug  3 12:24:27 2017
@@ -169,6 +169,8 @@ The binary representation of modules is
 
 Modules maintain references to each of the headers that were part of the 
module build. If any of those headers changes, or if any of the modules on 
which a module depends change, then the module will be (automatically) 
recompiled. The process should never require any user intervention.
 
+.. _modules-command-line-parameters:
+
 Command-line parameters
 -----------------------
 ``-fmodules``

Modified: cfe/trunk/docs/Modules.rst
URL: 
http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/Modules.rst?rev=309975&r1=309974&r2=309975&view=diff
==============================================================================
--- cfe/trunk/docs/Modules.rst (original)
+++ cfe/trunk/docs/Modules.rst Thu Aug  3 12:24:27 2017
@@ -98,11 +98,24 @@ Many programming languages have a module
 
 * **Binary distribution of modules**: Headers (particularly C++ headers) 
expose the full complexity of the language. Maintaining a stable binary module 
format across architectures, compiler versions, and compiler vendors is 
technically infeasible.
 
-Using Modules
-=============
-To enable modules, pass the command-line flag ``-fmodules``. This will make 
any modules-enabled software libraries available as modules as well as 
introducing any modules-specific syntax. Additional `command-line parameters`_ 
are described in a separate section later.
+Supported syntaxes
+==================
 
-Objective-C Import declaration
+Clang supports four different source-level syntaxes for modules, with full
+interoperability between the different syntaxes. They are:
+
+ * :ref:`Objective-C import declaration`\s
+ * :ref:`C++ Modules TS syntax`
+ * :ref:`#include translation <includes-as-imports>`
+ * :ref:`#pragma syntax <module pragmas>`
+
+All syntaxes other than the Modules TS syntax are enabled by ``-fmodules``.
+The C++ Modules TS syntax is enabled by ``-fmodules-ts``.
+Additional `command-line parameters`_ are described in a separate section 
later.
+
+At present, there is no first-class C syntax for import declarations.
+
+Objective-C import declaration
 ------------------------------
 Objective-C provides syntax for importing a module via an *@import 
declaration*, which imports the named module:
 
@@ -118,13 +131,39 @@ The ``@import`` declaration above import
 
 Redundant import declarations are ignored, and one is free to import modules 
at any point within the translation unit, so long as the import declaration is 
at global scope.
 
-At present, there is no C or C++ syntax for import declarations. Clang
-will track the modules proposal in the C++ committee. See the section
-`Includes as imports`_ to see how modules get imported today.
+C++ Modules TS syntax
+---------------------
+Clang supports the module syntax described in the draft C++ Technical
+Specification for Modules. Modules can be imported using the syntax:
+
+.. parsed-literal::
+
+  import std;
+
+.. warning::
+
+  The C++ Modules TS and Clang's other supported module systems use two
+  different naming systems for modules. Outside the Modules TS, a module
+  name ``foo.bar.baz`` describes the ``bar.baz`` submodule of the ``foo``
+  ("top-level") module, where a top-level module is a single compiled entity
+  that is intended to represent the interface of a complete library, and
+  submodules describe partitions of the module whose visibility can be
+  separately controlled through ``import``\s.
+  Within the Modules TS, there is no support for subdividing or grouping the
+  interface of a library, and the name ``foo.bar.baz`` is effectively a
+  top-level module name, naming a module that has no relation to modules
+  ``foo`` or ``foo.bar`` (if such modules exist).
+
+  This means there are two different ways to interpret a declaration such
+  as ``import std.io;`` if the Modules TS is enabled: as either the submodule
+  ``io`` of the top-level module ``std``, or as the top-level module
+  ``std.io``. Clang currently only considers the Modules TS interpretation
+  when using the Modules TS import syntax, so can only import top-level
+  modules. This is subject to change.
 
 Includes as imports
 -------------------
-The primary user-level feature of modules is the import operation, which 
provides access to the API of software libraries. However, today's programs 
make extensive use of ``#include``, and it is unrealistic to assume that all of 
this code will change overnight. Instead, modules automatically translate 
``#include`` directives into the corresponding module import. For example, the 
include directive
+The primary user-level feature of modules is the import operation, which 
provides access to the API of software libraries. However, today's programs 
make extensive use of ``#include``, and it is unrealistic to assume that all of 
this code will change overnight. Instead, modules can automatically translate 
``#include`` directives into the corresponding module import. For example, the 
include directive
 
 .. code-block:: c
 
@@ -132,10 +171,6 @@ The primary user-level feature of module
 
 will be automatically mapped to an import of the module ``std.io``. Even with 
specific ``import`` syntax in the language, this particular feature is 
important for both adoption and backward compatibility: automatic translation 
of ``#include`` to ``import`` allows an application to get the benefits of 
modules (for all modules-enabled libraries) without any changes to the 
application itself. Thus, users can easily use modules with one compiler while 
falling back to the preprocessor-inclusion mechanism with other compilers.
 
-.. note::
-
-  The automatic mapping of ``#include`` to ``import`` also solves an 
implementation problem: importing a module with a definition of some entity 
(say, a ``struct Point``) and then parsing a header containing another 
definition of ``struct Point`` would cause a redefinition error, even if it is 
the same ``struct Point``. By mapping ``#include`` to ``import``, the compiler 
can guarantee that it always sees just the already-parsed definition from the 
module.
-
 While building a module, ``#include_next`` is also supported, with one caveat.
 The usual behavior of ``#include_next`` is to search for the specified filename
 in the list of include paths, starting from the path *after* the one
@@ -147,762 +182,106 @@ first include path that would refer to t
 interpreted as if the current file had been found in that path.
 If this search finds a file named by a module map, the ``#include_next``
 directive is translated into an import, just like for a ``#include``
-directive.``
+directive.
 
-Module maps
------------
-The crucial link between modules and headers is described by a *module map*, 
which describes how a collection of existing headers maps on to the (logical) 
structure of a module. For example, one could imagine a module ``std`` covering 
the C standard library. Each of the C standard library headers (``<stdio.h>``, 
``<stdlib.h>``, ``<math.h>``, etc.) would contribute to the ``std`` module, by 
placing their respective APIs into the corresponding submodule (``std.io``, 
``std.lib``, ``std.math``, etc.). Having a list of the headers that are part of 
the ``std`` module allows the compiler to build the ``std`` module as a 
standalone entity, and having the mapping from header names to (sub)modules 
allows the automatic translation of ``#include`` directives to module imports.
+``#include``\s are mapped to module imports using :doc:`module maps 
<ModuleMaps>`.
 
-Module maps are specified as separate files (each named ``module.modulemap``) 
alongside the headers they describe, which allows them to be added to existing 
software libraries without having to change the library headers themselves (in 
most cases [#]_). The actual `Module map language`_ is described in a later 
section.
+Compilation models
+==================
 
-.. note::
+Modules can be built implicitly (on demand), or explicitly, as described below.
+Implicit module builds integrate more smoothly into existing build systems, but
+are not well-suited to distributed compilation or highly-parallel builds.
+Explicit module builds are more flexible but require more work to configure.
 
-  To actually see any benefits from modules, one first has to introduce module 
maps for the underlying C standard library and the libraries and headers on 
which it depends. The section `Modularizing a Platform`_ describes the steps 
one must take to write these module maps.
-  
-One can use module maps without modules to check the integrity of the use of 
header files. To do this, use the ``-fimplicit-module-maps`` option instead of 
the ``-fmodules`` option, or use ``-fmodule-map-file=`` option to explicitly 
specify the module map files to load.
-
-Compilation model
------------------
+Implicit module builds
+----------------------
 The binary representation of modules is automatically generated by the 
compiler on an as-needed basis. When a module is imported (e.g., by an 
``#include`` of one of the module's headers), the compiler will spawn a second 
instance of itself [#]_, with a fresh preprocessing context [#]_, to parse just 
the headers in that module. The resulting Abstract Syntax Tree (AST) is then 
persisted into the binary representation of the module that is then loaded into 
translation unit where the module import was encountered.
 
 The binary representation of modules is persisted in the *module cache*. 
Imports of a module will first query the module cache and, if a binary 
representation of the required module is already available, will load that 
representation directly. Thus, a module's headers will only be parsed once per 
language configuration, rather than once per translation unit that uses the 
module.
 
 Modules maintain references to each of the headers that were part of the 
module build. If any of those headers changes, or if any of the modules on 
which a module depends change, then the module will be (automatically) 
recompiled. The process should never require any user intervention.
 
-Command-line parameters
------------------------
-``-fmodules``
-  Enable the modules feature.
+Implicit module builds are currently only supported for modules described by 
:doc:`module maps <ModuleMaps>`, and not for :doc:`C++ Modules TS modules 
<ModulesTS>`.
 
-``-fbuiltin-module-map``
-  Load the Clang builtins module map file. (Equivalent to 
``-fmodule-map-file=<resource dir>/include/module.modulemap``)
+Explicit module builds
+----------------------
+The compilation action that implicit module builds invoke to compile a module 
can also be invoked explicitly. The module map or module interface unit is 
provided as an input to the compilation action, and the ``--precompile`` flag 
is used to indicate that compilation should stop after producing the AST. As 
with an implicit module build, the output file is a serialized form of the 
compiled AST.
 
-``-fimplicit-module-maps``
-  Enable implicit search for module map files named ``module.modulemap`` and 
similar. This option is implied by ``-fmodules``. If this is disabled with 
``-fno-implicit-module-maps``, module map files will only be loaded if they are 
explicitly specified via ``-fmodule-map-file`` or transitively used by another 
module map file.
+In this model, there is no module cache, so compiled module files must be 
passed to downstream compilations in another way. Typically, this is achieved 
by use of either the ``-fmodule-file=`` parameter or the 
``-fprebuit-module-path=`` parameter, which are described below.
 
-``-fmodules-cache-path=<directory>``
-  Specify the path to the modules cache. If not provided, Clang will select a 
system-appropriate default.
+Unlike for implicit module builds, explicitly compiled modules are not rebuilt 
automatically if their inputs change; instead, an attempt to use a module that 
is out of date will result in an error. However, some differences between 
configuration are permitted between the build of an explicitly-built module and 
the use of the module -- for example, different warning settings and macro 
definitions are allowed, as are changes to some minor language settings. The 
settings in force when a module was compiled govern its behavior.
 
-``-fno-autolink``
-  Disable automatic linking against the libraries associated with imported 
modules.
+.. warning::
 
-``-fmodules-ignore-macro=macroname``
-  Instruct modules to ignore the named macro when selecting an appropriate 
module variant. Use this for macros defined on the command line that don't 
affect how modules are built, to improve sharing of compiled module files.
+  Explicitly compiling a module from a module map currently requires the use of
+  ``-cc1`` flags, which are intentionally undocumented and subject to change at
+  any time, because the "module map" input type is not currently exposed.
 
-``-fmodules-prune-interval=seconds``
-  Specify the minimum delay (in seconds) between attempts to prune the module 
cache. Module cache pruning attempts to clear out old, unused module files so 
that the module cache itself does not grow without bound. The default delay is 
large (604,800 seconds, or 7 days) because this is an expensive operation. Set 
this value to 0 to turn off pruning.
+.. _modules-command-line-parameters:
 
-``-fmodules-prune-after=seconds``
-  Specify the minimum time (in seconds) for which a file in the module cache 
must be unused (according to access time) before module pruning will remove it. 
The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive 
module rebuilding.
+Command-line parameters
+=======================
+``-fmodules``
+  Enable the modules feature. Implies ``-fimplicit-modules`` and 
``-fimplicit-module-maps``.
+
+``-fmodules-ts``
+  Enable support for the C++ Modules TS syntax and its semantic model.
 
 ``-module-file-info <module file name>``
   Debugging aid that prints information about a given module file (with a 
``.pcm`` extension), including the language and preprocessor options that 
particular module variant was built with.
 
-``-fmodules-decluse``
-  Enable checking of module ``use`` declarations.
+Parameters controlling module maps
+----------------------------------
 
-``-fmodule-name=module-id``
-  Consider a source file as a part of the given module.
+``-fimplicit-module-maps``
+  Enable implicit search for module map files named ``module.modulemap`` and 
similar. This option is implied by ``-fmodules``. If this is disabled with 
``-fno-implicit-module-maps``, module map files will only be loaded if they are 
explicitly specified via ``-fmodule-map-file`` or transitively used by another 
module map file.
 
 ``-fmodule-map-file=<file>``
   Load the given module map file if a header from its directory or one of its 
subdirectories is loaded.
 
-``-fmodules-search-all``
-  If a symbol is not found, search modules referenced in the current module 
maps but not imported for symbols, so the error message can reference the 
module by name.  Note that if the global module index has not been built 
before, this might take some time as it needs to build all the modules.  Note 
that this option doesn't apply in module builds, to avoid the recursion.
-
-``-fno-implicit-modules``
-  All modules used by the build must be specified with ``-fmodule-file``.
-
-``-fmodule-file=<file>``
-  Load the given precompiled module file.
-
-``-fprebuilt-module-path=<directory>``
-  Specify the path to the prebuilt modules. If specified, we will look for 
modules in this directory for a given top-level module name. We don't need a 
module map for loading prebuilt modules in this directory and the compiler will 
not try to rebuild these modules. This can be specified multiple times.
-
-Module Semantics
-================
-
-Modules are modeled as if each submodule were a separate translation unit, and 
a module import makes names from the other translation unit visible. Each 
submodule starts with a new preprocessor state and an empty translation unit.
-
-.. note::
-
-  This behavior is currently only approximated when building a module with 
submodules. Entities within a submodule that has already been built are visible 
when building later submodules in that module. This can lead to fragile modules 
that depend on the build order used for the submodules of the module, and 
should not be relied upon. This behavior is subject to change.
-
-As an example, in C, this implies that if two structs are defined in different 
submodules with the same name, those two types are distinct types (but may be 
*compatible* types if their definitions match). In C++, two structs defined 
with the same name in different submodules are the *same* type, and must be 
equivalent under C++'s One Definition Rule.
-
-.. note::
-
-  Clang currently only performs minimal checking for violations of the One 
Definition Rule.
-
-If any submodule of a module is imported into any part of a program, the 
entire top-level module is considered to be part of the program. As a 
consequence of this, Clang may diagnose conflicts between an entity declared in 
an unimported submodule and an entity declared in the current translation unit, 
and Clang may inline or devirtualize based on knowledge from unimported 
submodules.
-
-Macros
-------
-
-The C and C++ preprocessor assumes that the input text is a single linear 
buffer, but with modules this is not the case. It is possible to import two 
modules that have conflicting definitions for a macro (or where one 
``#define``\s a macro and the other ``#undef``\ines it). The rules for handling 
macro definitions in the presence of modules are as follows:
-
-* Each definition and undefinition of a macro is considered to be a distinct 
entity.
-* Such entities are *visible* if they are from the current submodule or 
translation unit, or if they were exported from a submodule that has been 
imported.
-* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of 
``X`` that are visible at the point of the directive.
-* A ``#define`` or ``#undef`` directive is *active* if it is visible and no 
visible directive overrides it.
-* A set of macro directives is *consistent* if it consists of only ``#undef`` 
directives, or if all ``#define`` directives in the set define the macro name 
to the same sequence of tokens (following the usual rules for macro 
redefinitions).
-* If a macro name is used and the set of active directives is not consistent, 
the program is ill-formed. Otherwise, the (unique) meaning of the macro name is 
used.
-
-For example, suppose:
-
-* ``<stdio.h>`` defines a macro ``getc`` (and exports its ``#define``)
-* ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and 
exports its ``#undef``)
-  
-The ``#undef`` overrides the ``#define``, and a source file that imports both 
modules *in any order* will not see ``getc`` defined as a macro.
-
-Module Map Language
-===================
-
-.. warning::
-
-  The module map language is not currently guaranteed to be stable between 
major revisions of Clang.
-
-The module map language describes the mapping from header files to the
-logical structure of modules. To enable support for using a library as
-a module, one must write a ``module.modulemap`` file for that library. The
-``module.modulemap`` file is placed alongside the header files themselves,
-and is written in the module map language described below.
-
-.. note::
-    For compatibility with previous releases, if a module map file named
-    ``module.modulemap`` is not found, Clang will also search for a file named
-    ``module.map``. This behavior is deprecated and we plan to eventually
-    remove it.
-
-As an example, the module map file for the C standard library might look a bit 
like this:
-
-.. parsed-literal::
-
-  module std [system] [extern_c] {
-    module assert {
-      textual header "assert.h"
-      header "bits/assert-decls.h"
-      export *
-    }
-
-    module complex {
-      header "complex.h"
-      export *
-    }
-
-    module ctype {
-      header "ctype.h"
-      export *
-    }
-
-    module errno {
-      header "errno.h"
-      header "sys/errno.h"
-      export *
-    }
-
-    module fenv {
-      header "fenv.h"
-      export *
-    }
-
-    // ...more headers follow...
-  }
-
-Here, the top-level module ``std`` encompasses the whole C standard library. 
It has a number of submodules containing different parts of the standard 
library: ``complex`` for complex numbers, ``ctype`` for character types, etc. 
Each submodule lists one of more headers that provide the contents for that 
submodule. Finally, the ``export *`` command specifies that anything included 
by that submodule will be automatically re-exported. 
-
-Lexical structure
------------------
-Module map files use a simplified form of the C99 lexer, with the same rules 
for identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The 
module map language has the following reserved words; all other C identifiers 
are valid identifiers.
-
-.. parsed-literal::
-
-  ``config_macros`` ``export``     ``private``
-  ``conflict``      ``framework``  ``requires``
-  ``exclude``       ``header``     ``textual``
-  ``explicit``      ``link``       ``umbrella``
-  ``extern``        ``module``     ``use``
-
-Module map file
----------------
-A module map file consists of a series of module declarations:
-
-.. parsed-literal::
-
-  *module-map-file*:
-    *module-declaration**
-
-Within a module map file, modules are referred to by a *module-id*, which uses 
periods to separate each part of a module's name:
-
-.. parsed-literal::
-
-  *module-id*:
-    *identifier* ('.' *identifier*)*
-
-Module declaration
-------------------
-A module declaration describes a module, including the headers that contribute 
to that module, its submodules, and other aspects of the module.
-
-.. parsed-literal::
-
-  *module-declaration*:
-    ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* 
*attributes*:sub:`opt` '{' *module-member** '}'
-    ``extern`` ``module`` *module-id* *string-literal*
-
-The *module-id* should consist of only a single *identifier*, which provides 
the name of the module being defined. Each module shall have a single 
definition.
-
-The ``explicit`` qualifier can only be applied to a submodule, i.e., a module 
that is nested within another module. The contents of explicit submodules are 
only made available when the submodule itself was explicitly named in an import 
declaration or was re-exported from an imported module.
-
-The ``framework`` qualifier specifies that this module corresponds to a 
Darwin-style framework. A Darwin-style framework (used primarily on Mac OS X 
and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` 
is the name of the framework (and, therefore, the name of the module). That 
directory has the following layout:
-
-.. parsed-literal::
-
-  Name.framework/
-    Modules/module.modulemap  Module map for the framework
-    Headers/                  Subdirectory containing framework headers
-    PrivateHeaders/           Subdirectory containing framework private headers
-    Frameworks/               Subdirectory containing embedded frameworks
-    Resources/                Subdirectory containing additional resources
-    Name                      Symbolic link to the shared library for the 
framework
-
-The ``system`` attribute specifies that the module is a system module. When a 
system module is rebuilt, all of the module's headers will be considered system 
headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC 
system_header`` in each of the module's headers. The form of attributes is 
described in the section Attributes_, below.
-
-The ``extern_c`` attribute specifies that the module contains C code that can 
be used from within C++. When such a module is built for use in C++ code, all 
of the module's headers will be treated as if they were contained within an 
implicit ``extern "C"`` block. An import for a module with this attribute can 
appear within an ``extern "C"`` block. No other restrictions are lifted, 
however: the module currently cannot be imported within an ``extern "C"`` block 
in a namespace.
-
-The ``no_undeclared_includes`` attribute specifies that the module can only 
reach non-modular headers and headers from used modules. Since some headers 
could be present in more than one search path and map to different modules in 
each path, this mechanism helps clang to find the right header, i.e., prefer 
the one for the current module or in a submodule instead of the first usual 
match in the search paths.
-
-Modules can have a number of different kinds of members, each of which is 
described below:
-
-.. parsed-literal::
-
-  *module-member*:
-    *requires-declaration*
-    *header-declaration*
-    *umbrella-dir-declaration*
-    *submodule-declaration*
-    *export-declaration*
-    *use-declaration*
-    *link-declaration*
-    *config-macros-declaration*
-    *conflict-declaration*
-
-An extern module references a module defined by the *module-id* in a file 
given by the *string-literal*. The file can be referenced either by an absolute 
path or by a path relative to the current map file.
-
-Requires declaration
-~~~~~~~~~~~~~~~~~~~~
-A *requires-declaration* specifies the requirements that an importing 
translation unit must satisfy to use the module.
-
-.. parsed-literal::
-
-  *requires-declaration*:
-    ``requires`` *feature-list*
-
-  *feature-list*:
-    *feature* (',' *feature*)*
-
-  *feature*:
-    ``!``:sub:`opt` *identifier*
-
-The requirements clause allows specific modules or submodules to specify that 
they are only accessible with certain language dialects or on certain 
platforms. The feature list is a set of identifiers, defined below. If any of 
the features is not available in a given translation unit, that translation 
unit shall not import the module. When building a module for use by a 
compilation, submodules requiring unavailable features are ignored. The 
optional ``!`` indicates that a feature is incompatible with the module.
-
-The following features are defined:
-
-altivec
-  The target supports AltiVec.
-
-blocks
-  The "blocks" language feature is available.
-
-coroutines
-  Support for the coroutines TS is available.
-
-cplusplus
-  C++ support is available.
-
-cplusplus11
-  C++11 support is available.
-
-freestanding
-  A freestanding environment is available.
-
-gnuinlineasm
-  GNU inline ASM is available.
-
-objc
-  Objective-C support is available.
-
-objc_arc
-  Objective-C Automatic Reference Counting (ARC) is available
-
-opencl
-  OpenCL is available
-
-tls
-  Thread local storage is available.
-
-*target feature*
-  A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
-
-
-**Example:** The ``std`` module can be extended to also include C++ and C++11 
headers using a *requires-declaration*:
-
-.. parsed-literal::
-
- module std {
-    // C standard library...
-
-    module vector {
-      requires cplusplus
-      header "vector"
-    }
-
-    module type_traits {
-      requires cplusplus11
-      header "type_traits"
-    }
-  }
-
-Header declaration
-~~~~~~~~~~~~~~~~~~
-A header declaration specifies that a particular header is associated with the 
enclosing module.
-
-.. parsed-literal::
-
-  *header-declaration*:
-    ``private``:sub:`opt` ``textual``:sub:`opt` ``header`` *string-literal* 
*header-attrs*:sub:`opt`
-    ``umbrella`` ``header`` *string-literal* *header-attrs*:sub:`opt`
-    ``exclude`` ``header`` *string-literal* *header-attrs*:sub:`opt`
-
-  *header-attrs*:
-    '{' *header-attr** '}'
-
-  *header-attr*:
-    ``size`` *integer-literal*
-    ``mtime`` *integer-literal*
-
-A header declaration that does not contain ``exclude`` nor ``textual`` 
specifies a header that contributes to the enclosing module. Specifically, when 
the module is built, the named header will be parsed and its declarations will 
be (logically) placed into the enclosing submodule.
-
-A header with the ``umbrella`` specifier is called an umbrella header. An 
umbrella header includes all of the headers within its directory (and any 
subdirectories), and is typically used (in the ``#include`` world) to easily 
access the full API provided by a particular library. With modules, an umbrella 
header is a convenient shortcut that eliminates the need to write out 
``header`` declarations for every library header. A given directory can only 
contain a single umbrella header.
-
-.. note::
-    Any headers not included by the umbrella header should have
-    explicit ``header`` declarations. Use the   
-    ``-Wincomplete-umbrella`` warning option to ask Clang to complain
-    about headers not covered by the umbrella header or the module map.
-
-A header with the ``private`` specifier may not be included from outside the 
module itself.
-
-A header with the ``textual`` specifier will not be compiled when the module is
-built, and will be textually included if it is named by a ``#include``
-directive. However, it is considered to be part of the module for the purpose
-of checking *use-declaration*\s, and must still be a lexically-valid header
-file. In the future, we intend to pre-tokenize such headers and include the
-token sequence within the prebuilt module representation.
-
-A header with the ``exclude`` specifier is excluded from the module. It will 
not be included when the module is built, nor will it be considered to be part 
of the module, even if an ``umbrella`` header or directory would otherwise make 
it part of the module.
-
-**Example:** The C header ``assert.h`` is an excellent candidate for a textual 
header, because it is meant to be included multiple times (possibly with 
different ``NDEBUG`` settings). However, declarations within it should 
typically be split into a separate modular header.
-
-.. parsed-literal::
-
-  module std [system] {
-    textual header "assert.h"
-  }
-
-A given header shall not be referenced by more than one *header-declaration*.
-
-Two *header-declaration*\s, or a *header-declaration* and a ``#include``, are
-considered to refer to the same file if the paths resolve to the same file
-and the specified *header-attr*\s (if any) match the attributes of that file,
-even if the file is named differently (for instance, by a relative path or
-via symlinks).
-
-.. note::
-    The use of *header-attr*\s avoids the need for Clang to speculatively
-    ``stat`` every header referenced by a module map. It is recommended that
-    *header-attr*\s only be used in machine-generated module maps, to avoid
-    mismatches between attribute values and the corresponding files.
-
-Umbrella directory declaration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-An umbrella directory declaration specifies that all of the headers in the 
specified directory should be included within the module.
-
-.. parsed-literal::
-
-  *umbrella-dir-declaration*:
-    ``umbrella`` *string-literal*
-  
-The *string-literal* refers to a directory. When the module is built, all of 
the header files in that directory (and its subdirectories) are included in the 
module.
-
-An *umbrella-dir-declaration* shall not refer to the same directory as the 
location of an umbrella *header-declaration*. In other words, only a single 
kind of umbrella can be specified for a given directory.
-
-.. note::
-
-    Umbrella directories are useful for libraries that have a large number of 
headers but do not have an umbrella header.
-
-
-Submodule declaration
-~~~~~~~~~~~~~~~~~~~~~
-Submodule declarations describe modules that are nested within their enclosing 
module.
-
-.. parsed-literal::
-
-  *submodule-declaration*:
-    *module-declaration*
-    *inferred-submodule-declaration*
-
-A *submodule-declaration* that is a *module-declaration* is a nested module. 
If the *module-declaration* has a ``framework`` specifier, the enclosing module 
shall have a ``framework`` specifier; the submodule's contents shall be 
contained within the subdirectory ``Frameworks/SubName.framework``, where 
``SubName`` is the name of the submodule.
-
-A *submodule-declaration* that is an *inferred-submodule-declaration* 
describes a set of submodules that correspond to any headers that are part of 
the module but are not explicitly described by a *header-declaration*.
-
-.. parsed-literal::
-
-  *inferred-submodule-declaration*:
-    ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' 
*attributes*:sub:`opt` '{' *inferred-submodule-member** '}'
-  
-  *inferred-submodule-member*:
-    ``export`` '*'
-
-A module containing an *inferred-submodule-declaration* shall have either an 
umbrella header or an umbrella directory. The headers to which the 
*inferred-submodule-declaration* applies are exactly those headers included by 
the umbrella header (transitively) or included in the module because they 
reside within the umbrella directory (or its subdirectories).
-
-For each header included by the umbrella header or in the umbrella directory 
that is not named by a *header-declaration*, a module declaration is implicitly 
generated from the *inferred-submodule-declaration*. The module will:
-
-* Have the same name as the header (without the file extension)
-* Have the ``explicit`` specifier, if the *inferred-submodule-declaration* has 
the ``explicit`` specifier
-* Have the ``framework`` specifier, if the    
-  *inferred-submodule-declaration* has the ``framework`` specifier
-* Have the attributes specified by the \ *inferred-submodule-declaration* 
-* Contain a single *header-declaration* naming that header
-* Contain a single *export-declaration* ``export *``, if the \ 
*inferred-submodule-declaration* contains the \ *inferred-submodule-member* 
``export *``
-
-**Example:** If the subdirectory "MyLib" contains the headers ``A.h`` and 
``B.h``, then the following module map:
-
-.. parsed-literal::
-
-  module MyLib {
-    umbrella "MyLib"
-    explicit module * {
-      export *
-    }
-  }
-
-is equivalent to the (more verbose) module map:
-
-.. parsed-literal::
-
-  module MyLib {
-    explicit module A {
-      header "A.h"
-      export *
-    }
-
-    explicit module B {
-      header "B.h"
-      export *
-    }
-  }
-
-Export declaration
-~~~~~~~~~~~~~~~~~~
-An *export-declaration* specifies which imported modules will automatically be 
re-exported as part of a given module's API.
-
-.. parsed-literal::
-
-  *export-declaration*:
-    ``export`` *wildcard-module-id*
-
-  *wildcard-module-id*:
-    *identifier*
-    '*'
-    *identifier* '.' *wildcard-module-id*
-
-The *export-declaration* names a module or a set of modules that will be 
re-exported to any translation unit that imports the enclosing module. Each 
imported module that matches the *wildcard-module-id* up to, but not including, 
the first ``*`` will be re-exported.
-
-**Example:** In the following example, importing ``MyLib.Derived`` also 
provides the API for ``MyLib.Base``:
-
-.. parsed-literal::
-
-  module MyLib {
-    module Base {
-      header "Base.h"
-    }
-
-    module Derived {
-      header "Derived.h"
-      export Base
-    }
-  }
-
-Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard 
export to re-export everything ``Derived.h`` includes:
-
-.. parsed-literal::
-
-  module MyLib {
-    module Base {
-      header "Base.h"
-    }
-
-    module Derived {
-      header "Derived.h"
-      export *
-    }
-  }
-
-.. note::
-
-  The wildcard export syntax ``export *`` re-exports all of the
-  modules that were imported in the actual header file. Because
-  ``#include`` directives are automatically mapped to module imports,
-  ``export *`` provides the same transitive-inclusion behavior
-  provided by the C preprocessor, e.g., importing a given module
-  implicitly imports all of the modules on which it depends.
-  Therefore, liberal use of ``export *`` provides excellent backward
-  compatibility for programs that rely on transitive inclusion (i.e.,
-  all of them).
-
-Use declaration
-~~~~~~~~~~~~~~~
-A *use-declaration* specifies another module that the current top-level module
-intends to use. When the option *-fmodules-decluse* is specified, a module can
-only use other modules that are explicitly specified in this way.
-
-.. parsed-literal::
-
-  *use-declaration*:
-    ``use`` *module-id*
-
-**Example:** In the following example, use of A from C is not declared, so 
will trigger a warning.
-
-.. parsed-literal::
-
-  module A {
-    header "a.h"
-  }
-
-  module B {
-    header "b.h"
-  }
-
-  module C {
-    header "c.h"
-    use B
-  }
-
-When compiling a source file that implements a module, use the option
-``-fmodule-name=module-id`` to indicate that the source file is logically part
-of that module.
-
-The compiler at present only applies restrictions to the module directly being 
built.
-
-Link declaration
-~~~~~~~~~~~~~~~~
-A *link-declaration* specifies a library or framework against which a program 
should be linked if the enclosing module is imported in any translation unit in 
that program.
-
-.. parsed-literal::
-
-  *link-declaration*:
-    ``link`` ``framework``:sub:`opt` *string-literal*
-
-The *string-literal* specifies the name of the library or framework against 
which the program should be linked. For example, specifying "clangBasic" would 
instruct the linker to link with ``-lclangBasic`` for a Unix-style linker.
-
-A *link-declaration* with the ``framework`` specifies that the linker should 
link against the named framework, e.g., with ``-framework MyFramework``.
-
-.. note::
-
-  Automatic linking with the ``link`` directive is not yet widely
-  implemented, because it requires support from both the object file
-  format and the linker. The notion is similar to Microsoft Visual
-  Studio's ``#pragma comment(lib...)``.
-
-Configuration macros declaration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The *config-macros-declaration* specifies the set of configuration macros that 
have an effect on the API of the enclosing module.
-
-.. parsed-literal::
-
-  *config-macros-declaration*:
-    ``config_macros`` *attributes*:sub:`opt` *config-macro-list*:sub:`opt`
-
-  *config-macro-list*:
-    *identifier* (',' *identifier*)*
-
-Each *identifier* in the *config-macro-list* specifies the name of a macro. 
The compiler is required to maintain different variants of the given module for 
differing definitions of any of the named macros.
-
-A *config-macros-declaration* shall only be present on a top-level module, 
i.e., a module that is not nested within an enclosing module.
-
-The ``exhaustive`` attribute specifies that the list of macros in the 
*config-macros-declaration* is exhaustive, meaning that no other macro 
definition is intended to have an effect on the API of that module. 
-
-.. note::
-
-  The ``exhaustive`` attribute implies that any macro definitions 
-  for macros not listed as configuration macros should be ignored
-  completely when building the module. As an optimization, the
-  compiler could reduce the number of unique module variants by not
-  considering these non-configuration macros. This optimization is not
-  yet implemented in Clang.
-
-A translation unit shall not import the same module under different 
definitions of the configuration macros.
-
-.. note::
-
-  Clang implements a weak form of this requirement: the definitions
-  used for configuration macros are fixed based on the definitions
-  provided by the command line. If an import occurs and the definition
-  of any configuration macro has changed, the compiler will produce a
-  warning (under the control of ``-Wconfig-macros``).
-
-**Example:** A logging library might provide different API (e.g., in the form 
of different definitions for a logging macro) based on the ``NDEBUG`` macro 
setting:
-
-.. parsed-literal::
-
-  module MyLogger {
-    umbrella header "MyLogger.h"
-    config_macros [exhaustive] NDEBUG
-  }
-
-Conflict declarations
-~~~~~~~~~~~~~~~~~~~~~
-A *conflict-declaration* describes a case where the presence of two different 
modules in the same translation unit is likely to cause a problem. For example, 
two modules may provide similar-but-incompatible functionality.
-
-.. parsed-literal::
-
-  *conflict-declaration*:
-    ``conflict`` *module-id* ',' *string-literal*
-
-The *module-id* of the *conflict-declaration* specifies the module with which 
the enclosing module conflicts. The specified module shall not have been 
imported in the translation unit when the enclosing module is imported.
-
-The *string-literal* provides a message to be provided as part of the compiler 
diagnostic when two modules conflict.
-
-.. note::
-
-  Clang emits a warning (under the control of ``-Wmodule-conflict``)
-  when a module conflict is discovered.
-
-**Example:**
-
-.. parsed-literal::
-
-  module Conflicts {
-    explicit module A {
-      header "conflict_a.h"
-      conflict B, "we just don't like B"
-    }
-
-    module B {
-      header "conflict_b.h"
-    }
-  }
-
-
-Attributes
-----------
-Attributes are used in a number of places in the grammar to describe specific 
behavior of other declarations. The format of attributes is fairly simple.
-
-.. parsed-literal::
-
-  *attributes*:
-    *attribute* *attributes*:sub:`opt`
-
-  *attribute*:
-    '[' *identifier* ']'
-
-Any *identifier* can be used as an attribute, and each declaration specifies 
what attributes can be applied to it.
-
-Private Module Map Files
-------------------------
-Module map files are typically named ``module.modulemap`` and live
-either alongside the headers they describe or in a parent directory of
-the headers they describe. These module maps typically describe all of
-the API for the library.
-
-However, in some cases, the presence or absence of particular headers
-is used to distinguish between the "public" and "private" APIs of a
-particular library. For example, a library may contain the headers
-``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
-respectively. Additionally, ``Foo_Private.h`` may only be available on
-some versions of library, and absent in others. One cannot easily
-express this with a single module map file in the library:
-
-.. parsed-literal::
+``-fbuiltin-module-map``
+  Load the Clang builtins module map file. (Equivalent to 
``-fmodule-map-file=<resource dir>/include/module.modulemap``)
 
-  module Foo {
-    header "Foo.h"
-    
-    explicit module Private {
-      header "Foo_Private.h"
-    }
-  }
-
-
-because the header ``Foo_Private.h`` won't always be available. The
-module map file could be customized based on whether
-``Foo_Private.h`` is available or not, but doing so requires custom
-build machinery.
-
-Private module map files, which are named ``module.private.modulemap``
-(or, for backward compatibility, ``module_private.map``), allow one to
-augment the primary module map file with an additional submodule. For
-example, we would split the module map file above into two module map
-files:
+Parameters controlling module compilation mode
+----------------------------------------------
 
-.. code-block:: c
+``-fimplicit-modules``
+  Implicitly build modules using the module cache. This option is implied by 
``-fmodules``. If this is disabled with ``-fno-implicit-modules``, all modules 
used by the build must be specified with ``-fmodule-file`` or 
``-fprebuilt-module-path``.
 
-  /* module.modulemap */
-  module Foo {
-    header "Foo.h"
-  }
-  
-  /* module.private.modulemap */
-  explicit module Foo.Private {
-    header "Foo_Private.h"
-  }
-
-
-When a ``module.private.modulemap`` file is found alongside a
-``module.modulemap`` file, it is loaded after the ``module.modulemap``
-file. In our example library, the ``module.private.modulemap`` file
-would be available when ``Foo_Private.h`` is available, making it
-easier to split a library's public and private APIs along header
-boundaries.
-
-When writing a private module as part of a *framework*, it's recommended that:
-
-* Headers for this module are present in the ``PrivateHeaders``
-  framework subdirectory.
-* The private module is defined as a *submodule* of the public framework (if
-  there's one), similar to how ``Foo.Private`` is defined in the example above.
-* The ``explicit`` keyword should be used to guarantee that its content will
-  only be available when the submodule itself is explicitly named (through a
-  ``@import`` for example).
+``-fmodules-cache-path=<directory>``
+  Specify the path to the modules cache. If not provided, Clang will select a 
system-appropriate default.
 
-Modularizing a Platform
-=======================
-To get any benefit out of modules, one needs to introduce module maps for 
software libraries starting at the bottom of the stack. This typically means 
introducing a module map covering the operating system's headers and the C 
standard library headers (in ``/usr/include``, for a Unix system). 
+``-fmodules-ignore-macro=macroname``
+  Instruct modules to ignore the named macro when selecting an appropriate 
module variant. Use this for macros defined on the command line that don't 
affect how modules are built, to improve sharing of compiled module files.
 
-The module maps will be written using the `module map language`_, which 
provides the tools necessary to describe the mapping between headers and 
modules. Because the set of headers differs from one system to the next, the 
module map will likely have to be somewhat customized for, e.g., a particular 
distribution and version of the operating system. Moreover, the system headers 
themselves may require some modification, if they exhibit any anti-patterns 
that break modules. Such common patterns are described below.
+``-fmodules-prune-interval=seconds``
+  Specify the minimum delay (in seconds) between attempts to prune the module 
cache. Module cache pruning attempts to clear out old, unused module files so 
that the module cache itself does not grow without bound. The default delay is 
large (604,800 seconds, or 7 days) because this is an expensive operation. Set 
this value to 0 to turn off pruning.
 
-**Macro-guarded copy-and-pasted definitions**
-  System headers vend core types such as ``size_t`` for users. These types are 
often needed in a number of system headers, and are almost trivial to write. 
Hence, it is fairly common to see a definition such as the following 
copy-and-pasted throughout the headers:
+``-fmodules-prune-after=seconds``
+  Specify the minimum time (in seconds) for which a file in the module cache 
must be unused (according to access time) before module pruning will remove it. 
The default delay is large (2,678,400 seconds, or 31 days) to avoid excessive 
module rebuilding.
 
-  .. parsed-literal::
+``-fmodule-file=<file>``
+  Load the given precompiled module file.
 
-    #ifndef _SIZE_T
-    #define _SIZE_T
-    typedef __SIZE_TYPE__ size_t;
-    #endif
+``-fprebuilt-module-path=<directory>``
+  Specify the path to the prebuilt modules. If specified, we will look for 
modules in this directory for a given top-level module name. We don't need a 
module map for loading prebuilt modules in this directory and the compiler will 
not try to rebuild these modules. This can be specified multiple times.
 
-  Unfortunately, when modules compiles all of the C library headers together 
into a single module, only the first actual type definition of ``size_t`` will 
be visible, and then only in the submodule corresponding to the lucky first 
header. Any other headers that have copy-and-pasted versions of this pattern 
will *not* have a definition of ``size_t``. Importing the submodule 
corresponding to one of those headers will therefore not yield ``size_t`` as 
part of the API, because it wasn't there when the header was parsed. The fix 
for this problem is either to pull the copied declarations into a common header 
that gets included everywhere ``size_t`` is part of the API, or to eliminate 
the ``#ifndef`` and redefine the ``size_t`` type. The latter works for C++ 
headers and C11, but will cause an error for non-modules C90/C99, where 
redefinition of ``typedefs`` is not permitted.
+Parameters controlling module semantics
+---------------------------------------
 
-**Conflicting definitions**
-  Different system headers may provide conflicting definitions for various 
macros, functions, or types. These conflicting definitions don't tend to cause 
problems in a pre-modules world unless someone happens to include both headers 
in one translation unit. Since the fix is often simply "don't do that", such 
problems persist. Modules requires that the conflicting definitions be 
eliminated or that they be placed in separate modules (the former is generally 
the better answer).
+``-fno-autolink``
+  Disable automatic linking against the libraries associated with imported 
modules.
 
-**Missing includes**
-  Headers are often missing ``#include`` directives for headers that they 
actually depend on. As with the problem of conflicting definitions, this only 
affects unlucky users who don't happen to include headers in the right order. 
With modules, the headers of a particular module will be parsed in isolation, 
so the module may fail to build if there are missing includes.
+``-fmodules-decluse``
+``-fmodules-strict-decluse``
+  Enable checking of module ``use`` declarations, which requires dependencies 
between modules to be explicitly declared in module maps. With 
``-fmodules-strict-decluse``, ``#include``\s of headers not within any module 
are also rejected.
 
-**Headers that vend multiple APIs at different times**
-  Some systems have headers that contain a number of different kinds of API 
definitions, only some of which are made available with a given include. For 
example, the header may vend ``size_t`` only when the macro ``__need_size_t`` 
is defined before that header is included, and also vend ``wchar_t`` only when 
the macro ``__need_wchar_t`` is defined. Such headers are often included many 
times in a single translation unit, and will have no include guards. There is 
no sane way to map this header to a submodule. One can either eliminate the 
header (e.g., by splitting it into separate headers, one per actual API) or 
simply ``exclude`` it in the module map.
+``-fmodule-name=module-id``
+  Consider the compiled source file to be a part of the given module.
 
-To detect and help address some of these problems, the ``clang-tools-extra`` 
repository contains a ``modularize`` tool that parses a set of given headers 
and attempts to detect these problems and produce a report. See the tool's 
in-source documentation for information on how to check your system or library 
headers.
+``-fmodules-search-all``
+  If a symbol is not found, search modules referenced in the current module 
maps but not imported for symbols, so the error message can reference the 
module by name.  Note that if the global module index has not been built 
before, this might take some time as it needs to build all the modules.  Note 
that this option doesn't apply in module builds, to avoid the recursion.
 
 Future Directions
 =================
@@ -938,8 +317,6 @@ PCHInternals_
 
 .. [#] Automatic linking against the libraries of modules requires specific 
linker support, which is not widely available.
 
-.. [#] There are certain anti-patterns that occur in headers, particularly 
system headers, that cause problems for modules. The section `Modularizing a 
Platform`_ describes some of them.
-
 .. [#] The second instance is actually a new thread within the current 
process, not a separate process. However, the original compiler instance is 
blocked on the execution of this thread.
 
 .. [#] The preprocessing context in which the modules are parsed is actually 
dependent on the command-line options provided to the compiler, including the 
language dialect and any ``-D`` options. However, the compiled modules for 
different command-line options are kept distinct, and any preprocessor 
directives that occur within the translation unit are ignored. See the section 
on the `Configuration macros declaration`_ for more information.

Added: cfe/trunk/docs/ModulesTS.rst
URL: 
http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/ModulesTS.rst?rev=309975&view=auto
==============================================================================
--- cfe/trunk/docs/ModulesTS.rst (added)
+++ cfe/trunk/docs/ModulesTS.rst Thu Aug  3 12:24:27 2017
@@ -0,0 +1,782 @@
+==============
+C++ Modules TS
+==============
+
+.. contents::
+   :local:
+
+Introduction
+============
+Clang provides experimental support for the
+C++ Modules draft Technical Specification.
+This support provides language syntax for defining and using module interfaces,
+and can be used in conjunction with Clang's :doc:`header modules <Modules>`.
+
+This document describes how to enable and use the C++ Modules TS support.
+
+Command-line interface
+======================
+
+In order to know what operations to perform on an input file, Clang needs to
+know whether a source file is a module interface unit. This can be specified
+with ``-x c++-module``, and is the default for files with a ``.cppm`` 
extension.
+
+Quick start
+-----------
+
+Add ``-fmodules-ts`` to your command lines to enable support for the Modules 
TS.
+
+To build a module interface unit to a precompiled module (PCM) file, use the
+``--precompile`` flag:
+
+.. code-block:: console
+
+  $ clang -fmodules-ts moduleinterface.cppm --precompile -o moduleinterface.pcm
+
+The resulting ``.pcm`` file should be passed to dependent compilation actions.
+The simplest way to do this is ``-fmodule-file=moduleinterface.pcm``, but see
+below for an alternative.
+
+Command-line parameters
+-----------------------
+``-fmodules-ts``
+  Enable support for the C++ Modules TS.
+
+``--precompile``
+  Given a C++ module interface unit, this flag specifies that the 
+
+``-fmodule-file=<file>``
+  Load the given precompiled module file.
+
+``-fprebuilt-module-path=<directory>``
+  Specify the path to the prebuilt modules. If specified, we will look for 
module files in this directory for a given dotted module path with a ``.pcm`` 
extension (eg, ``import foo.bar;`` will search for ``foo.bar.pcm`` in this 
directory). This can be specified multiple times.
+
+See also the :ref:`header modules command line reference 
<modules-command-line-parameters>`.
+
+Interactions with header modules
+================================
+
+Modules are modeled as if each submodule were a separate translation unit, and 
a module import makes names from the other translation unit visible. Each 
submodule starts with a new preprocessor state and an empty translation unit.
+
+.. note::
+
+  This behavior is currently only approximated when building a module with 
submodules. Entities within a submodule that has already been built are visible 
when building later submodules in that module. This can lead to fragile modules 
that depend on the build order used for the submodules of the module, and 
should not be relied upon. This behavior is subject to change.
+
+As an example, in C, this implies that if two structs are defined in different 
submodules with the same name, those two types are distinct types (but may be 
*compatible* types if their definitions match). In C++, two structs defined 
with the same name in different submodules are the *same* type, and must be 
equivalent under C++'s One Definition Rule.
+
+.. note::
+
+  Clang currently only performs minimal checking for violations of the One 
Definition Rule.
+
+If any submodule of a module is imported into any part of a program, the 
entire top-level module is considered to be part of the program. As a 
consequence of this, Clang may diagnose conflicts between an entity declared in 
an unimported submodule and an entity declared in the current translation unit, 
and Clang may inline or devirtualize based on knowledge from unimported 
submodules.
+
+Macros
+------
+
+The C and C++ preprocessor assumes that the input text is a single linear 
buffer, but with modules this is not the case. It is possible to import two 
modules that have conflicting definitions for a macro (or where one 
``#define``\s a macro and the other ``#undef``\ines it). The rules for handling 
macro definitions in the presence of modules are as follows:
+
+* Each definition and undefinition of a macro is considered to be a distinct 
entity.
+* Such entities are *visible* if they are from the current submodule or 
translation unit, or if they were exported from a submodule that has been 
imported.
+* A ``#define X`` or ``#undef X`` directive *overrides* all definitions of 
``X`` that are visible at the point of the directive.
+* A ``#define`` or ``#undef`` directive is *active* if it is visible and no 
visible directive overrides it.
+* A set of macro directives is *consistent* if it consists of only ``#undef`` 
directives, or if all ``#define`` directives in the set define the macro name 
to the same sequence of tokens (following the usual rules for macro 
redefinitions).
+* If a macro name is used and the set of active directives is not consistent, 
the program is ill-formed. Otherwise, the (unique) meaning of the macro name is 
used.
+
+For example, suppose:
+
+* ``<stdio.h>`` defines a macro ``getc`` (and exports its ``#define``)
+* ``<cstdio>`` imports the ``<stdio.h>`` module and undefines the macro (and 
exports its ``#undef``)
+  
+The ``#undef`` overrides the ``#define``, and a source file that imports both 
modules *in any order* will not see ``getc`` defined as a macro.
+
+Module Map Language
+===================
+
+.. warning::
+
+  The module map language is not currently guaranteed to be stable between 
major revisions of Clang.
+
+The module map language describes the mapping from header files to the
+logical structure of modules. To enable support for using a library as
+a module, one must write a ``module.modulemap`` file for that library. The
+``module.modulemap`` file is placed alongside the header files themselves,
+and is written in the module map language described below.
+
+.. note::
+    For compatibility with previous releases, if a module map file named
+    ``module.modulemap`` is not found, Clang will also search for a file named
+    ``module.map``. This behavior is deprecated and we plan to eventually
+    remove it.
+
+As an example, the module map file for the C standard library might look a bit 
like this:
+
+.. parsed-literal::
+
+  module std [system] [extern_c] {
+    module assert {
+      textual header "assert.h"
+      header "bits/assert-decls.h"
+      export *
+    }
+
+    module complex {
+      header "complex.h"
+      export *
+    }
+
+    module ctype {
+      header "ctype.h"
+      export *
+    }
+
+    module errno {
+      header "errno.h"
+      header "sys/errno.h"
+      export *
+    }
+
+    module fenv {
+      header "fenv.h"
+      export *
+    }
+
+    // ...more headers follow...
+  }
+
+Here, the top-level module ``std`` encompasses the whole C standard library. 
It has a number of submodules containing different parts of the standard 
library: ``complex`` for complex numbers, ``ctype`` for character types, etc. 
Each submodule lists one of more headers that provide the contents for that 
submodule. Finally, the ``export *`` command specifies that anything included 
by that submodule will be automatically re-exported. 
+
+Lexical structure
+-----------------
+Module map files use a simplified form of the C99 lexer, with the same rules 
for identifiers, tokens, string literals, ``/* */`` and ``//`` comments. The 
module map language has the following reserved words; all other C identifiers 
are valid identifiers.
+
+.. parsed-literal::
+
+  ``config_macros`` ``export``     ``private``
+  ``conflict``      ``framework``  ``requires``
+  ``exclude``       ``header``     ``textual``
+  ``explicit``      ``link``       ``umbrella``
+  ``extern``        ``module``     ``use``
+
+Module map file
+---------------
+A module map file consists of a series of module declarations:
+
+.. parsed-literal::
+
+  *module-map-file*:
+    *module-declaration**
+
+Within a module map file, modules are referred to by a *module-id*, which uses 
periods to separate each part of a module's name:
+
+.. parsed-literal::
+
+  *module-id*:
+    *identifier* ('.' *identifier*)*
+
+Module declaration
+------------------
+A module declaration describes a module, including the headers that contribute 
to that module, its submodules, and other aspects of the module.
+
+.. parsed-literal::
+
+  *module-declaration*:
+    ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` *module-id* 
*attributes*:sub:`opt` '{' *module-member** '}'
+    ``extern`` ``module`` *module-id* *string-literal*
+
+The *module-id* should consist of only a single *identifier*, which provides 
the name of the module being defined. Each module shall have a single 
definition.
+
+The ``explicit`` qualifier can only be applied to a submodule, i.e., a module 
that is nested within another module. The contents of explicit submodules are 
only made available when the submodule itself was explicitly named in an import 
declaration or was re-exported from an imported module.
+
+The ``framework`` qualifier specifies that this module corresponds to a 
Darwin-style framework. A Darwin-style framework (used primarily on Mac OS X 
and iOS) is contained entirely in directory ``Name.framework``, where ``Name`` 
is the name of the framework (and, therefore, the name of the module). That 
directory has the following layout:
+
+.. parsed-literal::
+
+  Name.framework/
+    Modules/module.modulemap  Module map for the framework
+    Headers/                  Subdirectory containing framework headers
+    PrivateHeaders/           Subdirectory containing framework private headers
+    Frameworks/               Subdirectory containing embedded frameworks
+    Resources/                Subdirectory containing additional resources
+    Name                      Symbolic link to the shared library for the 
framework
+
+The ``system`` attribute specifies that the module is a system module. When a 
system module is rebuilt, all of the module's headers will be considered system 
headers, which suppresses warnings. This is equivalent to placing ``#pragma GCC 
system_header`` in each of the module's headers. The form of attributes is 
described in the section Attributes_, below.
+
+The ``extern_c`` attribute specifies that the module contains C code that can 
be used from within C++. When such a module is built for use in C++ code, all 
of the module's headers will be treated as if they were contained within an 
implicit ``extern "C"`` block. An import for a module with this attribute can 
appear within an ``extern "C"`` block. No other restrictions are lifted, 
however: the module currently cannot be imported within an ``extern "C"`` block 
in a namespace.
+
+The ``no_undeclared_includes`` attribute specifies that the module can only 
reach non-modular headers and headers from used modules. Since some headers 
could be present in more than one search path and map to different modules in 
each path, this mechanism helps clang to find the right header, i.e., prefer 
the one for the current module or in a submodule instead of the first usual 
match in the search paths.
+
+Modules can have a number of different kinds of members, each of which is 
described below:
+
+.. parsed-literal::
+
+  *module-member*:
+    *requires-declaration*
+    *header-declaration*
+    *umbrella-dir-declaration*
+    *submodule-declaration*
+    *export-declaration*
+    *use-declaration*
+    *link-declaration*
+    *config-macros-declaration*
+    *conflict-declaration*
+
+An extern module references a module defined by the *module-id* in a file 
given by the *string-literal*. The file can be referenced either by an absolute 
path or by a path relative to the current map file.
+
+Requires declaration
+~~~~~~~~~~~~~~~~~~~~
+A *requires-declaration* specifies the requirements that an importing 
translation unit must satisfy to use the module.
+
+.. parsed-literal::
+
+  *requires-declaration*:
+    ``requires`` *feature-list*
+
+  *feature-list*:
+    *feature* (',' *feature*)*
+
+  *feature*:
+    ``!``:sub:`opt` *identifier*
+
+The requirements clause allows specific modules or submodules to specify that 
they are only accessible with certain language dialects or on certain 
platforms. The feature list is a set of identifiers, defined below. If any of 
the features is not available in a given translation unit, that translation 
unit shall not import the module. When building a module for use by a 
compilation, submodules requiring unavailable features are ignored. The 
optional ``!`` indicates that a feature is incompatible with the module.
+
+The following features are defined:
+
+altivec
+  The target supports AltiVec.
+
+blocks
+  The "blocks" language feature is available.
+
+coroutines
+  Support for the coroutines TS is available.
+
+cplusplus
+  C++ support is available.
+
+cplusplus11
+  C++11 support is available.
+
+freestanding
+  A freestanding environment is available.
+
+gnuinlineasm
+  GNU inline ASM is available.
+
+objc
+  Objective-C support is available.
+
+objc_arc
+  Objective-C Automatic Reference Counting (ARC) is available
+
+opencl
+  OpenCL is available
+
+tls
+  Thread local storage is available.
+
+*target feature*
+  A specific target feature (e.g., ``sse4``, ``avx``, ``neon``) is available.
+
+
+**Example:** The ``std`` module can be extended to also include C++ and C++11 
headers using a *requires-declaration*:
+
+.. parsed-literal::
+
+ module std {
+    // C standard library...
+
+    module vector {
+      requires cplusplus
+      header "vector"
+    }
+
+    module type_traits {
+      requires cplusplus11
+      header "type_traits"
+    }
+  }
+
+Header declaration
+~~~~~~~~~~~~~~~~~~
+A header declaration specifies that a particular header is associated with the 
enclosing module.
+
+.. parsed-literal::
+
+  *header-declaration*:
+    ``private``:sub:`opt` ``textual``:sub:`opt` ``header`` *string-literal* 
*header-attrs*:sub:`opt`
+    ``umbrella`` ``header`` *string-literal* *header-attrs*:sub:`opt`
+    ``exclude`` ``header`` *string-literal* *header-attrs*:sub:`opt`
+
+  *header-attrs*:
+    '{' *header-attr** '}'
+
+  *header-attr*:
+    ``size`` *integer-literal*
+    ``mtime`` *integer-literal*
+
+A header declaration that does not contain ``exclude`` nor ``textual`` 
specifies a header that contributes to the enclosing module. Specifically, when 
the module is built, the named header will be parsed and its declarations will 
be (logically) placed into the enclosing submodule.
+
+A header with the ``umbrella`` specifier is called an umbrella header. An 
umbrella header includes all of the headers within its directory (and any 
subdirectories), and is typically used (in the ``#include`` world) to easily 
access the full API provided by a particular library. With modules, an umbrella 
header is a convenient shortcut that eliminates the need to write out 
``header`` declarations for every library header. A given directory can only 
contain a single umbrella header.
+
+.. note::
+    Any headers not included by the umbrella header should have
+    explicit ``header`` declarations. Use the   
+    ``-Wincomplete-umbrella`` warning option to ask Clang to complain
+    about headers not covered by the umbrella header or the module map.
+
+A header with the ``private`` specifier may not be included from outside the 
module itself.
+
+A header with the ``textual`` specifier will not be compiled when the module is
+built, and will be textually included if it is named by a ``#include``
+directive. However, it is considered to be part of the module for the purpose
+of checking *use-declaration*\s, and must still be a lexically-valid header
+file. In the future, we intend to pre-tokenize such headers and include the
+token sequence within the prebuilt module representation.
+
+A header with the ``exclude`` specifier is excluded from the module. It will 
not be included when the module is built, nor will it be considered to be part 
of the module, even if an ``umbrella`` header or directory would otherwise make 
it part of the module.
+
+**Example:** The C header ``assert.h`` is an excellent candidate for a textual 
header, because it is meant to be included multiple times (possibly with 
different ``NDEBUG`` settings). However, declarations within it should 
typically be split into a separate modular header.
+
+.. parsed-literal::
+
+  module std [system] {
+    textual header "assert.h"
+  }
+
+A given header shall not be referenced by more than one *header-declaration*.
+
+Two *header-declaration*\s, or a *header-declaration* and a ``#include``, are
+considered to refer to the same file if the paths resolve to the same file
+and the specified *header-attr*\s (if any) match the attributes of that file,
+even if the file is named differently (for instance, by a relative path or
+via symlinks).
+
+.. note::
+    The use of *header-attr*\s avoids the need for Clang to speculatively
+    ``stat`` every header referenced by a module map. It is recommended that
+    *header-attr*\s only be used in machine-generated module maps, to avoid
+    mismatches between attribute values and the corresponding files.
+
+Umbrella directory declaration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+An umbrella directory declaration specifies that all of the headers in the 
specified directory should be included within the module.
+
+.. parsed-literal::
+
+  *umbrella-dir-declaration*:
+    ``umbrella`` *string-literal*
+  
+The *string-literal* refers to a directory. When the module is built, all of 
the header files in that directory (and its subdirectories) are included in the 
module.
+
+An *umbrella-dir-declaration* shall not refer to the same directory as the 
location of an umbrella *header-declaration*. In other words, only a single 
kind of umbrella can be specified for a given directory.
+
+.. note::
+
+    Umbrella directories are useful for libraries that have a large number of 
headers but do not have an umbrella header.
+
+
+Submodule declaration
+~~~~~~~~~~~~~~~~~~~~~
+Submodule declarations describe modules that are nested within their enclosing 
module.
+
+.. parsed-literal::
+
+  *submodule-declaration*:
+    *module-declaration*
+    *inferred-submodule-declaration*
+
+A *submodule-declaration* that is a *module-declaration* is a nested module. 
If the *module-declaration* has a ``framework`` specifier, the enclosing module 
shall have a ``framework`` specifier; the submodule's contents shall be 
contained within the subdirectory ``Frameworks/SubName.framework``, where 
``SubName`` is the name of the submodule.
+
+A *submodule-declaration* that is an *inferred-submodule-declaration* 
describes a set of submodules that correspond to any headers that are part of 
the module but are not explicitly described by a *header-declaration*.
+
+.. parsed-literal::
+
+  *inferred-submodule-declaration*:
+    ``explicit``:sub:`opt` ``framework``:sub:`opt` ``module`` '*' 
*attributes*:sub:`opt` '{' *inferred-submodule-member** '}'
+  
+  *inferred-submodule-member*:
+    ``export`` '*'
+
+A module containing an *inferred-submodule-declaration* shall have either an 
umbrella header or an umbrella directory. The headers to which the 
*inferred-submodule-declaration* applies are exactly those headers included by 
the umbrella header (transitively) or included in the module because they 
reside within the umbrella directory (or its subdirectories).
+
+For each header included by the umbrella header or in the umbrella directory 
that is not named by a *header-declaration*, a module declaration is implicitly 
generated from the *inferred-submodule-declaration*. The module will:
+
+* Have the same name as the header (without the file extension)
+* Have the ``explicit`` specifier, if the *inferred-submodule-declaration* has 
the ``explicit`` specifier
+* Have the ``framework`` specifier, if the    
+  *inferred-submodule-declaration* has the ``framework`` specifier
+* Have the attributes specified by the \ *inferred-submodule-declaration* 
+* Contain a single *header-declaration* naming that header
+* Contain a single *export-declaration* ``export *``, if the \ 
*inferred-submodule-declaration* contains the \ *inferred-submodule-member* 
``export *``
+
+**Example:** If the subdirectory "MyLib" contains the headers ``A.h`` and 
``B.h``, then the following module map:
+
+.. parsed-literal::
+
+  module MyLib {
+    umbrella "MyLib"
+    explicit module * {
+      export *
+    }
+  }
+
+is equivalent to the (more verbose) module map:
+
+.. parsed-literal::
+
+  module MyLib {
+    explicit module A {
+      header "A.h"
+      export *
+    }
+
+    explicit module B {
+      header "B.h"
+      export *
+    }
+  }
+
+Export declaration
+~~~~~~~~~~~~~~~~~~
+An *export-declaration* specifies which imported modules will automatically be 
re-exported as part of a given module's API.
+
+.. parsed-literal::
+
+  *export-declaration*:
+    ``export`` *wildcard-module-id*
+
+  *wildcard-module-id*:
+    *identifier*
+    '*'
+    *identifier* '.' *wildcard-module-id*
+
+The *export-declaration* names a module or a set of modules that will be 
re-exported to any translation unit that imports the enclosing module. Each 
imported module that matches the *wildcard-module-id* up to, but not including, 
the first ``*`` will be re-exported.
+
+**Example:** In the following example, importing ``MyLib.Derived`` also 
provides the API for ``MyLib.Base``:
+
+.. parsed-literal::
+
+  module MyLib {
+    module Base {
+      header "Base.h"
+    }
+
+    module Derived {
+      header "Derived.h"
+      export Base
+    }
+  }
+
+Note that, if ``Derived.h`` includes ``Base.h``, one can simply use a wildcard 
export to re-export everything ``Derived.h`` includes:
+
+.. parsed-literal::
+
+  module MyLib {
+    module Base {
+      header "Base.h"
+    }
+
+    module Derived {
+      header "Derived.h"
+      export *
+    }
+  }
+
+.. note::
+
+  The wildcard export syntax ``export *`` re-exports all of the
+  modules that were imported in the actual header file. Because
+  ``#include`` directives are automatically mapped to module imports,
+  ``export *`` provides the same transitive-inclusion behavior
+  provided by the C preprocessor, e.g., importing a given module
+  implicitly imports all of the modules on which it depends.
+  Therefore, liberal use of ``export *`` provides excellent backward
+  compatibility for programs that rely on transitive inclusion (i.e.,
+  all of them).
+
+Use declaration
+~~~~~~~~~~~~~~~
+A *use-declaration* specifies another module that the current top-level module
+intends to use. When the option *-fmodules-decluse* is specified, a module can
+only use other modules that are explicitly specified in this way.
+
+.. parsed-literal::
+
+  *use-declaration*:
+    ``use`` *module-id*
+
+**Example:** In the following example, use of A from C is not declared, so 
will trigger a warning.
+
+.. parsed-literal::
+
+  module A {
+    header "a.h"
+  }
+
+  module B {
+    header "b.h"
+  }
+
+  module C {
+    header "c.h"
+    use B
+  }
+
+When compiling a source file that implements a module, use the option
+``-fmodule-name=module-id`` to indicate that the source file is logically part
+of that module.
+
+The compiler at present only applies restrictions to the module directly being 
built.
+
+Link declaration
+~~~~~~~~~~~~~~~~
+A *link-declaration* specifies a library or framework against which a program 
should be linked if the enclosing module is imported in any translation unit in 
that program.
+
+.. parsed-literal::
+
+  *link-declaration*:
+    ``link`` ``framework``:sub:`opt` *string-literal*
+
+The *string-literal* specifies the name of the library or framework against 
which the program should be linked. For example, specifying "clangBasic" would 
instruct the linker to link with ``-lclangBasic`` for a Unix-style linker.
+
+A *link-declaration* with the ``framework`` specifies that the linker should 
link against the named framework, e.g., with ``-framework MyFramework``.
+
+.. note::
+
+  Automatic linking with the ``link`` directive is not yet widely
+  implemented, because it requires support from both the object file
+  format and the linker. The notion is similar to Microsoft Visual
+  Studio's ``#pragma comment(lib...)``.
+
+Configuration macros declaration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The *config-macros-declaration* specifies the set of configuration macros that 
have an effect on the API of the enclosing module.
+
+.. parsed-literal::
+
+  *config-macros-declaration*:
+    ``config_macros`` *attributes*:sub:`opt` *config-macro-list*:sub:`opt`
+
+  *config-macro-list*:
+    *identifier* (',' *identifier*)*
+
+Each *identifier* in the *config-macro-list* specifies the name of a macro. 
The compiler is required to maintain different variants of the given module for 
differing definitions of any of the named macros.
+
+A *config-macros-declaration* shall only be present on a top-level module, 
i.e., a module that is not nested within an enclosing module.
+
+The ``exhaustive`` attribute specifies that the list of macros in the 
*config-macros-declaration* is exhaustive, meaning that no other macro 
definition is intended to have an effect on the API of that module. 
+
+.. note::
+
+  The ``exhaustive`` attribute implies that any macro definitions 
+  for macros not listed as configuration macros should be ignored
+  completely when building the module. As an optimization, the
+  compiler could reduce the number of unique module variants by not
+  considering these non-configuration macros. This optimization is not
+  yet implemented in Clang.
+
+A translation unit shall not import the same module under different 
definitions of the configuration macros.
+
+.. note::
+
+  Clang implements a weak form of this requirement: the definitions
+  used for configuration macros are fixed based on the definitions
+  provided by the command line. If an import occurs and the definition
+  of any configuration macro has changed, the compiler will produce a
+  warning (under the control of ``-Wconfig-macros``).
+
+**Example:** A logging library might provide different API (e.g., in the form 
of different definitions for a logging macro) based on the ``NDEBUG`` macro 
setting:
+
+.. parsed-literal::
+
+  module MyLogger {
+    umbrella header "MyLogger.h"
+    config_macros [exhaustive] NDEBUG
+  }
+
+Conflict declarations
+~~~~~~~~~~~~~~~~~~~~~
+A *conflict-declaration* describes a case where the presence of two different 
modules in the same translation unit is likely to cause a problem. For example, 
two modules may provide similar-but-incompatible functionality.
+
+.. parsed-literal::
+
+  *conflict-declaration*:
+    ``conflict`` *module-id* ',' *string-literal*
+
+The *module-id* of the *conflict-declaration* specifies the module with which 
the enclosing module conflicts. The specified module shall not have been 
imported in the translation unit when the enclosing module is imported.
+
+The *string-literal* provides a message to be provided as part of the compiler 
diagnostic when two modules conflict.
+
+.. note::
+
+  Clang emits a warning (under the control of ``-Wmodule-conflict``)
+  when a module conflict is discovered.
+
+**Example:**
+
+.. parsed-literal::
+
+  module Conflicts {
+    explicit module A {
+      header "conflict_a.h"
+      conflict B, "we just don't like B"
+    }
+
+    module B {
+      header "conflict_b.h"
+    }
+  }
+
+
+Attributes
+----------
+Attributes are used in a number of places in the grammar to describe specific 
behavior of other declarations. The format of attributes is fairly simple.
+
+.. parsed-literal::
+
+  *attributes*:
+    *attribute* *attributes*:sub:`opt`
+
+  *attribute*:
+    '[' *identifier* ']'
+
+Any *identifier* can be used as an attribute, and each declaration specifies 
what attributes can be applied to it.
+
+Private Module Map Files
+------------------------
+Module map files are typically named ``module.modulemap`` and live
+either alongside the headers they describe or in a parent directory of
+the headers they describe. These module maps typically describe all of
+the API for the library.
+
+However, in some cases, the presence or absence of particular headers
+is used to distinguish between the "public" and "private" APIs of a
+particular library. For example, a library may contain the headers
+``Foo.h`` and ``Foo_Private.h``, providing public and private APIs,
+respectively. Additionally, ``Foo_Private.h`` may only be available on
+some versions of library, and absent in others. One cannot easily
+express this with a single module map file in the library:
+
+.. parsed-literal::
+
+  module Foo {
+    header "Foo.h"
+    
+    explicit module Private {
+      header "Foo_Private.h"
+    }
+  }
+
+
+because the header ``Foo_Private.h`` won't always be available. The
+module map file could be customized based on whether
+``Foo_Private.h`` is available or not, but doing so requires custom
+build machinery.
+
+Private module map files, which are named ``module.private.modulemap``
+(or, for backward compatibility, ``module_private.map``), allow one to
+augment the primary module map file with an additional submodule. For
+example, we would split the module map file above into two module map
+files:
+
+.. code-block:: c
+
+  /* module.modulemap */
+  module Foo {
+    header "Foo.h"
+  }
+  
+  /* module.private.modulemap */
+  explicit module Foo.Private {
+    header "Foo_Private.h"
+  }
+
+
+When a ``module.private.modulemap`` file is found alongside a
+``module.modulemap`` file, it is loaded after the ``module.modulemap``
+file. In our example library, the ``module.private.modulemap`` file
+would be available when ``Foo_Private.h`` is available, making it
+easier to split a library's public and private APIs along header
+boundaries.
+
+When writing a private module as part of a *framework*, it's recommended that:
+
+* Headers for this module are present in the ``PrivateHeaders``
+  framework subdirectory.
+* The private module is defined as a *submodule* of the public framework (if
+  there's one), similar to how ``Foo.Private`` is defined in the example above.
+* The ``explicit`` keyword should be used to guarantee that its content will
+  only be available when the submodule itself is explicitly named (through a
+  ``@import`` for example).
+
+Modularizing a Platform
+=======================
+To get any benefit out of modules, one needs to introduce module maps for 
software libraries starting at the bottom of the stack. This typically means 
introducing a module map covering the operating system's headers and the C 
standard library headers (in ``/usr/include``, for a Unix system). 
+
+The module maps will be written using the `module map language`_, which 
provides the tools necessary to describe the mapping between headers and 
modules. Because the set of headers differs from one system to the next, the 
module map will likely have to be somewhat customized for, e.g., a particular 
distribution and version of the operating system. Moreover, the system headers 
themselves may require some modification, if they exhibit any anti-patterns 
that break modules. Such common patterns are described below.
+
+**Macro-guarded copy-and-pasted definitions**
+  System headers vend core types such as ``size_t`` for users. These types are 
often needed in a number of system headers, and are almost trivial to write. 
Hence, it is fairly common to see a definition such as the following 
copy-and-pasted throughout the headers:
+
+  .. parsed-literal::
+
+    #ifndef _SIZE_T
+    #define _SIZE_T
+    typedef __SIZE_TYPE__ size_t;
+    #endif
+
+  Unfortunately, when modules compiles all of the C library headers together 
into a single module, only the first actual type definition of ``size_t`` will 
be visible, and then only in the submodule corresponding to the lucky first 
header. Any other headers that have copy-and-pasted versions of this pattern 
will *not* have a definition of ``size_t``. Importing the submodule 
corresponding to one of those headers will therefore not yield ``size_t`` as 
part of the API, because it wasn't there when the header was parsed. The fix 
for this problem is either to pull the copied declarations into a common header 
that gets included everywhere ``size_t`` is part of the API, or to eliminate 
the ``#ifndef`` and redefine the ``size_t`` type. The latter works for C++ 
headers and C11, but will cause an error for non-modules C90/C99, where 
redefinition of ``typedefs`` is not permitted.
+
+**Conflicting definitions**
+  Different system headers may provide conflicting definitions for various 
macros, functions, or types. These conflicting definitions don't tend to cause 
problems in a pre-modules world unless someone happens to include both headers 
in one translation unit. Since the fix is often simply "don't do that", such 
problems persist. Modules requires that the conflicting definitions be 
eliminated or that they be placed in separate modules (the former is generally 
the better answer).
+
+**Missing includes**
+  Headers are often missing ``#include`` directives for headers that they 
actually depend on. As with the problem of conflicting definitions, this only 
affects unlucky users who don't happen to include headers in the right order. 
With modules, the headers of a particular module will be parsed in isolation, 
so the module may fail to build if there are missing includes.
+
+**Headers that vend multiple APIs at different times**
+  Some systems have headers that contain a number of different kinds of API 
definitions, only some of which are made available with a given include. For 
example, the header may vend ``size_t`` only when the macro ``__need_size_t`` 
is defined before that header is included, and also vend ``wchar_t`` only when 
the macro ``__need_wchar_t`` is defined. Such headers are often included many 
times in a single translation unit, and will have no include guards. There is 
no sane way to map this header to a submodule. One can either eliminate the 
header (e.g., by splitting it into separate headers, one per actual API) or 
simply ``exclude`` it in the module map.
+
+To detect and help address some of these problems, the ``clang-tools-extra`` 
repository contains a ``modularize`` tool that parses a set of given headers 
and attempts to detect these problems and produce a report. See the tool's 
in-source documentation for information on how to check your system or library 
headers.
+
+Future Directions
+=================
+Modules support is under active development, and there are many opportunities 
remaining to improve it. Here are a few ideas:
+
+**Detect unused module imports**
+  Unlike with ``#include`` directives, it should be fairly simple to track 
whether a directly-imported module has ever been used. By doing so, Clang can 
emit ``unused import`` or ``unused #include`` diagnostics, including Fix-Its to 
remove the useless imports/includes.
+
+**Fix-Its for missing imports**
+  It's fairly common for one to make use of some API while writing code, only 
to get a compiler error about "unknown type" or "no function named" because the 
corresponding header has not been included. Clang can detect such cases and 
auto-import the required module, but should provide a Fix-It to add the import.
+
+**Improve modularize**
+  The modularize tool is both extremely important (for deployment) and 
extremely crude. It needs better UI, better detection of problems (especially 
for C++), and perhaps an assistant mode to help write module maps for you.
+
+Where To Learn More About Modules
+=================================
+The Clang source code provides additional information about modules:
+
+``clang/lib/Headers/module.modulemap``
+  Module map for Clang's compiler-specific header files.
+
+``clang/test/Modules/``
+  Tests specifically related to modules functionality.
+
+``clang/include/clang/Basic/Module.h``
+  The ``Module`` class in this header describes a module, and is used 
throughout the compiler to implement modules.
+
+``clang/include/clang/Lex/ModuleMap.h``
+  The ``ModuleMap`` class in this header describes the full module map, 
consisting of all of the module map files that have been parsed, and providing 
facilities for looking up module maps and mapping between modules and headers 
(in both directions).
+
+PCHInternals_
+  Information about the serialized AST format used for precompiled headers and 
modules. The actual implementation is in the ``clangSerialization`` library.
+
+.. [#] Automatic linking against the libraries of modules requires specific 
linker support, which is not widely available.
+
+.. [#] There are certain anti-patterns that occur in headers, particularly 
system headers, that cause problems for modules. The section `Modularizing a 
Platform`_ describes some of them.
+
+.. [#] The second instance is actually a new thread within the current 
process, not a separate process. However, the original compiler instance is 
blocked on the execution of this thread.
+
+.. [#] The preprocessing context in which the modules are parsed is actually 
dependent on the command-line options provided to the compiler, including the 
language dialect and any ``-D`` options. However, the compiled modules for 
different command-line options are kept distinct, and any preprocessor 
directives that occur within the translation unit are ignored. See the section 
on the `Configuration macros declaration`_ for more information.
+
+.. _PCHInternals: PCHInternals.html
+ 

Modified: cfe/trunk/lib/Sema/Sema.cpp
URL: 
http://llvm.org/viewvc/llvm-project/cfe/trunk/lib/Sema/Sema.cpp?rev=309975&r1=309974&r2=309975&view=diff
==============================================================================
--- cfe/trunk/lib/Sema/Sema.cpp (original)
+++ cfe/trunk/lib/Sema/Sema.cpp Thu Aug  3 12:24:27 2017
@@ -595,6 +595,9 @@ void Sema::getUndefinedButUsed(
     // __attribute__((weakref)) is basically a definition.
     if (ND->hasAttr<WeakRefAttr>()) continue;
 
+    if (isa<CXXDeductionGuideDecl>(ND))
+      continue;
+
     if (FunctionDecl *FD = dyn_cast<FunctionDecl>(ND)) {
       if (FD->isDefined())
         continue;

Modified: cfe/trunk/test/SemaCXX/cxx1z-class-template-argument-deduction.cpp
URL: 
http://llvm.org/viewvc/llvm-project/cfe/trunk/test/SemaCXX/cxx1z-class-template-argument-deduction.cpp?rev=309975&r1=309974&r2=309975&view=diff
==============================================================================
--- cfe/trunk/test/SemaCXX/cxx1z-class-template-argument-deduction.cpp 
(original)
+++ cfe/trunk/test/SemaCXX/cxx1z-class-template-argument-deduction.cpp Thu Aug  
3 12:24:27 2017
@@ -1,4 +1,9 @@
-// RUN: %clang_cc1 -std=c++1z -verify %s
+// RUN: %clang_cc1 -std=c++1z -verify %s -DERRORS
+// RUN: %clang_cc1 -std=c++1z -verify %s -UERRORS
+
+// This test is split into two because we only produce "undefined internal"
+// warnings if we didn't produce any errors.
+#if ERRORS
 
 namespace std {
   using size_t = decltype(sizeof(0));
@@ -280,3 +285,21 @@ namespace tuple_tests {
     scoped_lock l = {};
   }
 }
+
+#else
+
+// expected-no-diagnostics
+namespace undefined_warnings {
+  // Make sure we don't get an "undefined but used internal symbol" warning 
for the deduction guide here.
+  namespace {
+    template <typename T>
+    struct TemplDObj {
+      explicit TemplDObj(T func) noexcept {}
+    };
+    auto test1 = TemplDObj(0);
+
+    TemplDObj(float) -> TemplDObj<double>;
+    auto test2 = TemplDObj(.0f);
+  }
+}
+#endif


_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits