From 040e12662a674e2ebfc93f86a70eddb7d6fc76da Mon Sep 17 00:00:00 2001 From: Richard Smith Date: Fri, 2 Jun 2017 01:55:39 +0000 Subject: Support lazy stat'ing of files referenced by module maps. This patch adds support for a `header` declaration in a module map to specify certain `stat` information (currently, size and mtime) about that header file. This has two purposes: - It removes the need to eagerly `stat` every file referenced by a module map. Instead, we track a list of unresolved header files with each size / mtime (actually, for simplicity, we track submodules with such headers), and when attempting to look up a header file based on a `FileEntry`, we check if there are any unresolved header directives with that `FileEntry`'s size / mtime and perform deferred `stat`s if so. - It permits a preprocessed module to be compiled without the original files being present on disk. The only reason we used to need those files was to get the `stat` information in order to do header -> module lookups when using the module. If we're provided with the `stat` information in the preprocessed module, we can avoid requiring the files to exist. Unlike most `header` directives, if a `header` directive with `stat` information has no corresponding on-disk file the enclosing module is *not* marked unavailable (so that behavior is consistent regardless of whether we've resolved a header directive, and so that preprocessed modules don't get marked unavailable). We could actually do this for all `header` directives: the only reason we mark the module unavailable if headers are missing is to give a diagnostic slightly earlier (rather than waiting until we actually try to build the module / load and validate its .pcm file). Differential Revision: https://reviews.llvm.org/D33703 llvm-svn: 304515 --- clang/docs/Modules.rst | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) (limited to 'clang/docs/Modules.rst') diff --git a/clang/docs/Modules.rst b/clang/docs/Modules.rst index 7bd2adf8af5..ed6f8171573 100644 --- a/clang/docs/Modules.rst +++ b/clang/docs/Modules.rst @@ -469,9 +469,16 @@ A header declaration specifies that a particular header is associated with the e .. parsed-literal:: *header-declaration*: - ``private``:sub:`opt` ``textual``:sub:`opt` ``header`` *string-literal* - ``umbrella`` ``header`` *string-literal* - ``exclude`` ``header`` *string-literal* + ``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. @@ -504,6 +511,18 @@ A header with the ``exclude`` specifier is excluded from the module. It will not 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. -- cgit v1.2.3