From ccaf6244ef4c79d9c4c09c352443cbcdb8331e97 Mon Sep 17 00:00:00 2001 From: Richard Smith Date: Mon, 20 Oct 2014 00:15:49 +0000 Subject: [modules] Add support for #include_next. #include_next interacts poorly with modules: it depends on where in the list of include paths the current file was found. Files covered by module maps are not found in include search paths when building the module (and are not found in include search paths when @importing the module either), so this isn't really meaningful. Instead, we fake up the result that #include_next *should* have given: find the first path that would have resulted in the given file being picked, and search from there onwards. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@220177 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/Modules.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'docs') diff --git a/docs/Modules.rst b/docs/Modules.rst index 110a77b5da..bfc9a5a59d 100644 --- a/docs/Modules.rst +++ b/docs/Modules.rst @@ -136,6 +136,19 @@ will be automatically mapped to an import of the module ``std.io``. Even with sp 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 +in which the current file was found. +Because files listed in module maps are not found through include paths, a +different strategy is used for ``#include_next`` directives in such files: the +list of include paths is searched for the specified header name, to find the +first include path that would refer to the current file. ``#include_next`` is +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.`` + 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 (````, ````, ````, 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. -- cgit v1.2.3