<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Wed, May 11, 2016 at 11:40 PM, Dan Liew <span dir="ltr"><<a href="mailto:dan@su-root.co.uk" target="_blank">dan@su-root.co.uk</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">Hi,<br>
<br>
I was reading Clang's documentation [1] on Modules and there are<br>
several aspects that confused me that I was wondering if someone could<br>
clarify some parts. I'm CC'ing a few people who git blame shows<br>
contributed to the documentation. Hopefully answers can be used to<br>
help me write a patch to improve the documentation here.<br>
<br>
# Modules Semantics<br>
<br>
The following is stated<br>
<br>
```<br>
If any submodule of a module is imported into any part of a program,<br>
the entire top-level module is considered to be part of the program.<br>
As a consequence of this, Clang may diagnose conflicts between an<br>
entity declared in an unimported submodule and an entity declared in<br>
the current translation unit, and Clang may inline or devirtualize<br>
based on knowledge from unimported submodules.<br>
```<br>
<br>
What does considered "part of the program" mean here? Initially I<br>
thought that meant just import the parent module (i.e. writing<br>
``import <a href="http://std.io" rel="noreferrer" target="_blank">std.io</a>`` is the same as ``import std``) but thinking about it<br>
some more that doesn't make sense because there wouldn't be any point<br>
in having submodules because they couldn't be used independently from<br>
other submodules.<br>
<br>
Perhaps what was meant here is that because ``std`` corresponds to one<br>
or more libraries we can have Clang check for problems that might<br>
occur if the program did do ``import std`` (i.e. we used more of the<br>
library that we are linking against) even though it isn't. Is that<br>
correct?<br></blockquote><div><br></div><div>Yes. The rest of the module is part of the program in the same way that other .o files that are linked to the current one are part of the program. But the import only makes the nominated submodule visible.</div><div><br></div><div>Put another way: top-level modules are the units of granularity for linking, and submodules are the units of granularity for visibility within a particular translation unit. But because the compiler knows that the entire top-level module will be part of the program when a submodule is imported, it's able to diagnose more problems / conflicts.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
# Use declaration<br>
<br>
I don't understand this part at all.<br>
<br>
What does ``the current top-level module`` mean here? In other places<br>
the docs say "enclosing module" for other declarations inside a module<br>
declaration. Are these supposed to be the same? They do not sound the<br>
same.<br></blockquote><div><br></div><div>A top-level module is one that's not a submodule of another module.  We can easily add a definition if that's not obvious.</div><div><br></div><div>Example:</div><div><br></div><div>module A {</div><div>  module B {</div><div>    module C {</div><div>      // Here, A is the top-level module, but A.B.C is the (immediately) enclosing module.</div><div><br></div><div>In any case, I think the documentation is a little unclear here: we should probably phrase this as "A use-declaration specifies another module that the enclosing module (that is required to be a top-level module) intends to use." or similar.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">
The example given further confuses me because<br>
<br>
- I don't know what the "current top-level module" is here<br>
- I don't understand why the compiler would complain about anything<br>
here. There's nothing here that indicates that "c.h" depends on "a.h"<br>
so why would the compiler complain about module C not declaring a<br>
dependency on module A.<br></blockquote><div><br></div><div>It says that "use of A from C" would trigger a warning, that is, if C included one of A's headers, a warning would be triggered. This would be a lot more obvious if we gave example contents for c.h.</div></div></div></div>