Questions on Clang's documentation of Modules

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Questions on Clang's documentation of Modules

Vassil Vassilev via cfe-dev
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.
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Clang's documentation of Modules

Vassil Vassilev via cfe-dev
On Wed, May 11, 2016 at 11:40 PM, Dan Liew <[hidden email]> 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.

_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev
Reply | Threaded
Open this post in threaded view
|

Re: Questions on Clang's documentation of Modules

Vassil Vassilev via cfe-dev
> 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
_______________________________________________
cfe-dev mailing list
[hidden email]
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-dev