llvm dev - May 2016 - Questions on Clang's documentation of Modules

Hi,

I was reading Clang's documentation [1] on Modules and there are
several aspects that confused me that I was wondering if someone could
clarify some parts. I'm CC'ing a few people who git blame shows
contributed to the documentation. Hopefully answers can be used to
help me write a patch to improve the documentation here.

# Modules Semantics

The following is stated

```
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.
```

What does considered "part of the program" mean here? Initially I
thought that meant just import the parent module (i.e. writing
``import std.io`` is the same as ``import std``) but thinking about it
some more that doesn't make sense because there wouldn't be any point
in having submodules because they couldn't be used independently from
other submodules.

Perhaps what was meant here is that because ``std`` corresponds to one
or more libraries we can have Clang check for problems that might
occur if the program did do ``import std`` (i.e. we used more of the
library that we are linking against) even though it isn't. Is that
correct?

# Use declaration

I don't understand this part at all.

What does ``the current top-level module`` mean here? In other places
the docs say "enclosing module" for other declarations inside a module
declaration. Are these supposed to be the same? They do not sound the
same.

The example given further confuses me because

- I don't know what the "current top-level module" is here
- I don't understand why the compiler would complain about anything
here. There's nothing here that indicates that "c.h" depends on
"a.h"
so why would the compiler complain about module C not declaring a
dependency on module A.

Any insight here would be appreciated.

[1] http://clang.llvm.org/docs/Modules.html

Thanks,
Dan.

On Wed, May 11, 2016 at 11:40 PM, Dan Liew <dan at su-root.co.uk> wrote:
> Hi,
>
> I was reading Clang's documentation [1] on Modules and there are
> several aspects that confused me that I was wondering if someone could
> clarify some parts. I'm CC'ing a few people who git blame shows
> contributed to the documentation. Hopefully answers can be used to
> help me write a patch to improve the documentation here.
>
> # Modules Semantics
>
> The following is stated
>
> ```
> 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.
> ```
>
> What does considered "part of the program" mean here? Initially I
> thought that meant just import the parent module (i.e. writing
> ``import std.io`` is the same as ``import std``) but thinking about it
> some more that doesn't make sense because there wouldn't be any
point
> in having submodules because they couldn't be used independently from
> other submodules.
>
> Perhaps what was meant here is that because ``std`` corresponds to one
> or more libraries we can have Clang check for problems that might
> occur if the program did do ``import std`` (i.e. we used more of the
> library that we are linking against) even though it isn't. Is that
> correct?
>
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.

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.

# Use declaration
>
> I don't understand this part at all.
>
> What does ``the current top-level module`` mean here? In other places
> the docs say "enclosing module" for other declarations inside a
module
> declaration. Are these supposed to be the same? They do not sound the
> same.
>
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.

Example:

module A {
  module B {
    module C {
      // Here, A is the top-level module, but A.B.C is the (immediately)
enclosing module.

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.

The example given further confuses me because
>
> - I don't know what the "current top-level module" is here
> - I don't understand why the compiler would complain about anything
> here. There's nothing here that indicates that "c.h" depends
on "a.h"
> so why would the compiler complain about module C not declaring a
> dependency on module A.
>
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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20160512/b16449d7/attachment.html>

> 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.
>
> 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.
Okay thanks for clarifying.
>> # Use declaration
>>
>> I don't understand this part at all.
>>
>> What does ``the current top-level module`` mean here? In other places
>> the docs say "enclosing module" for other declarations inside
a module
>> declaration. Are these supposed to be the same? They do not sound the
>> same.
>
>
> 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.
>
> Example:
>
> module A {
>   module B {
>     module C {
>       // Here, A is the top-level module, but A.B.C is the (immediately)
> enclosing module.
Okay that makes sense now.
> 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.
That seems like a better explanation.
>> The example given further confuses me because
>>
>> - I don't know what the "current top-level module" is
here
>> - I don't understand why the compiler would complain about anything
>> here. There's nothing here that indicates that "c.h"
depends on "a.h"
>> so why would the compiler complain about module C not declaring a
>> dependency on module A.
>
>
> 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.
That's not how I read it. It currently says

```
In the following example, use of A from C is not declared, so will
trigger a warning.
```

To me this is stating that

"use of A from C is not declared in the module map" (i.e. there is no
``use A`` in the declaration of module C in the module map).

and I intuitively expect that

"use of symbols in A from C" and "use of A from C is not declared
in
the module map" imply a warning will be raised.

However nothing states whether "use of symbols in A from C" is true or
false so I cannot concluded if a warning will be raised.

I think cleaning up the wording and example contents of the header
would remove confusion here.

I'll try to write a patch and I'll CC you.

Thanks,
Dan.


it **will trigger a warning**. Given the intention here the wording i

-- 
Dan Liew
PhD Student - Imperial College London