diff options
author | Richard Smith <richard-llvm@metafoo.co.uk> | 2017-06-02 01:55:39 +0000 |
---|---|---|
committer | Richard Smith <richard-llvm@metafoo.co.uk> | 2017-06-02 01:55:39 +0000 |
commit | 146ecad762cb83f8e00d8027188b622c6a8ce15d (patch) | |
tree | 17b1d69656572e2a842ac2dcd9ef6dc525b1e290 /docs | |
parent | d4d74154ebb7baf50ad9b9d08c714a961afa59d8 (diff) |
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
git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@304515 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs')
-rw-r--r-- | docs/Modules.rst | 25 |
1 files changed, 22 insertions, 3 deletions
diff --git a/docs/Modules.rst b/docs/Modules.rst index 7bd2adf8af..ed6f817157 100644 --- a/docs/Modules.rst +++ b/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. |