llvm dev - Jan 2018 - Layering Requirements in the LLVM Coding Style Guide

On Tue, Jan 16, 2018 at 11:35 AM Philip Reames <listmail at
philipreames.com>
wrote:
>
>
> On 01/16/2018 09:21 AM, David Blaikie via llvm-dev wrote:
>
> Context: I've been looking at experimenting with using Modular Code
> Generation (My talk at last year's LLVM dev meeting
> https://www.youtube.com/watch?v=lYYxDXgbUZ0 is about the best reference
> at the moment) when building the LLVM project, as a good experiment for the
> feature. This can/does enforce a stronger layering invariant than LLVM has
> historically been enforced. So I'm curious to get buy-in and maybe
document
> this if it's something people like the idea of.
>
> I'm starting this discussion here rather than in an actual code review
on
> llvm-commits since it seems like it could do with a bit of a wider
> discussion, but once/if the general direction is agreed on, I'll send a
> patch for review of specific wording for the LLVM Coding Standards.
>
>
> Currently the LLVM Coding Standards
> <https://llvm.org/docs/CodingStandards.html> doesn't say
much/anything
> about layering. 'A Public Header File *is* a Module'
>
<https://llvm.org/docs/CodingStandards.html#a-public-header-file-is-a-module>
section
> talks about modules of functionality, mostly trying to describe why a
> header file should be self contained - but uses anachronistic language
> about modules that doesn't line up with the implicit or explicit
modules
> concepts in use today, I think.
>
> I propose making this wording a bit more explicit, including:
>
> 1) Headers should be standalone (include all their dependencies - this is
> mentioned in the "is a Module" piece, by way of a technique to
help ensure
> this, but not explicit as a goal itself).
>
> 2) Files intended to be included in a particular context (that aren't
> safe/benign to include multiple times, in multiple .cpp files, etc) should
> use a '.inc' or '.def' (.def specifically for those
"define a macro,
> include the header which will reference that macro" style setups we
have in
> a few places).
>
> Everything up to here seems non-controversial.  We should document this
> and ideally identify tooling suitable to enforce it.
>
+1

>
>
> And the actual layering issue:
> 3) Each library should only include headers or otherwise reference
> entities from libraries it depends on. Including in headers and inline
> functions. A simple/explicit way to put this: every inline function should
> be able to be moved into a .cpp file and the build (with a unix linker -
> one that cannot handle circular library dependencies) should still succeed.
>
>
> This last point is the most interesting - and I hope one that people
> generally find desirable, so it might not be immediately obvious why it may
> be contentious or difficult:
>
> LLVM violates this constraint by using inline functions in headers to
> avoid certain layering constraints that might otherwise cause the build to
> fail. A couple of major examples I've hit are:
>
> TargetSelect.h
>
<http://lists.llvm.org/pipermail/llvm-dev/2017-December/119494.html>and
> similar: This one's especially tricky - the header is part of
libSupport,
> but each function in here depends on a different subset of targets
> (creating a circular dependency) - to call the given function the
> programmer needs to choose the right dependencies to link to or the program
> will not link.
> Clang Diagnostics <https://reviews.llvm.org/D41357> (work in
progress):
> The diagnostics for each component are in their own component directories,
> but are then all included from libClangBasic, a library none of those
> components depends on. (so this isn't so much an inlining case as
#include
> based circular dependency)
>
>
> Generally I'd like to get buy-in that stricter layering is desirable,
and
> that these few cases are at least sub-optimal, if accepted for now.
>
> I have no strong opinion on this topic.  My experience has been that
it's
> often far harder to unwind these types of inline dependencies than it first
> seems and that the value in doing so is often unclear.  I'm not
opposed,
> but I'm also not signing up to help.  :)
>
While I'm also not in a position to help a lot, I think there is a question
we should ask here:

Should we hold new code to this standard? Should we declare that this is
what we want?

For me, I say emphatically "yes" and we should put it into the coding
standards. I think cleaning up the existing code is a good thing to do and
we can let people who have a reason actually drive that, but I don't want
that to be necessarily finished in order for us to establish reasonable
guidelines going forward.

>
> Happy to go into more details about any of this, examples, etc, but I
> realize this is already a bit long.
> - Dave
>
>
> _______________________________________________
> LLVM Developers mailing listllvm-dev at
lists.llvm.orghttp://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180117/4716ce44/attachment.html>

On Wed, Jan 17, 2018 at 1:27 PM Chandler Carruth <chandlerc at gmail.com>
wrote:
> On Tue, Jan 16, 2018 at 11:35 AM Philip Reames <listmail at
philipreames.com>
> wrote:
>
>>
>>
>> On 01/16/2018 09:21 AM, David Blaikie via llvm-dev wrote:
>>
>> Context: I've been looking at experimenting with using Modular Code
>> Generation (My talk at last year's LLVM dev meeting
>> https://www.youtube.com/watch?v=lYYxDXgbUZ0 is about the best reference
>> at the moment) when building the LLVM project, as a good experiment for
the
>> feature. This can/does enforce a stronger layering invariant than LLVM
has
>> historically been enforced. So I'm curious to get buy-in and maybe
document
>> this if it's something people like the idea of.
>>
>> I'm starting this discussion here rather than in an actual code
review on
>> llvm-commits since it seems like it could do with a bit of a wider
>> discussion, but once/if the general direction is agreed on, I'll
send a
>> patch for review of specific wording for the LLVM Coding Standards.
>>
>>
>> Currently the LLVM Coding Standards
>> <https://llvm.org/docs/CodingStandards.html> doesn't say
much/anything
>> about layering. 'A Public Header File *is* a Module'
>>
<https://llvm.org/docs/CodingStandards.html#a-public-header-file-is-a-module>
section
>> talks about modules of functionality, mostly trying to describe why a
>> header file should be self contained - but uses anachronistic language
>> about modules that doesn't line up with the implicit or explicit
modules
>> concepts in use today, I think.
>>
>> I propose making this wording a bit more explicit, including:
>>
>> 1) Headers should be standalone (include all their dependencies - this
is
>> mentioned in the "is a Module" piece, by way of a technique
to help ensure
>> this, but not explicit as a goal itself).
>>
>> 2) Files intended to be included in a particular context (that
aren't
>> safe/benign to include multiple times, in multiple .cpp files, etc)
should
>> use a '.inc' or '.def' (.def specifically for those
"define a macro,
>> include the header which will reference that macro" style setups
we have in
>> a few places).
>>
>> Everything up to here seems non-controversial.  We should document this
>> and ideally identify tooling suitable to enforce it.
>>
>
> +1
>
>
>>
>>
>> And the actual layering issue:
>> 3) Each library should only include headers or otherwise reference
>> entities from libraries it depends on. Including in headers and inline
>> functions. A simple/explicit way to put this: every inline function
should
>> be able to be moved into a .cpp file and the build (with a unix linker
-
>> one that cannot handle circular library dependencies) should still
succeed.
>>
>>
>> This last point is the most interesting - and I hope one that people
>> generally find desirable, so it might not be immediately obvious why it
may
>> be contentious or difficult:
>>
>> LLVM violates this constraint by using inline functions in headers to
>> avoid certain layering constraints that might otherwise cause the build
to
>> fail. A couple of major examples I've hit are:
>>
>> TargetSelect.h
>>
<http://lists.llvm.org/pipermail/llvm-dev/2017-December/119494.html>and
>> similar: This one's especially tricky - the header is part of
libSupport,
>> but each function in here depends on a different subset of targets
>> (creating a circular dependency) - to call the given function the
>> programmer needs to choose the right dependencies to link to or the
program
>> will not link.
>> Clang Diagnostics <https://reviews.llvm.org/D41357> (work in
progress):
>> The diagnostics for each component are in their own component
directories,
>> but are then all included from libClangBasic, a library none of those
>> components depends on. (so this isn't so much an inlining case as
#include
>> based circular dependency)
>>
>>
>> Generally I'd like to get buy-in that stricter layering is
desirable, and
>> that these few cases are at least sub-optimal, if accepted for now.
>>
>> I have no strong opinion on this topic.  My experience has been that
it's
>> often far harder to unwind these types of inline dependencies than it
first
>> seems and that the value in doing so is often unclear.  I'm not
opposed,
>> but I'm also not signing up to help.  :)
>>
>
> While I'm also not in a position to help a lot, I think there is a
> question we should ask here:
>
> Should we hold new code to this standard? Should we declare that this is
> what we want?
>
> For me, I say emphatically "yes" and we should put it into the
coding
> standards. I think cleaning up the existing code is a good thing to do and
> we can let people who have a reason actually drive that, but I don't
want
> that to be necessarily finished in order for us to establish reasonable
> guidelines going forward.
>
Yep, that's where I am too - I want it to be our standard going forward
but, like naming conventions and other things, realize that not all
existing code in the project will conform to this constraint.

- Dave

>
>
>>
>> Happy to go into more details about any of this, examples, etc, but I
>> realize this is already a bit long.
>> - Dave
>>
>>
>> _______________________________________________
>> LLVM Developers mailing listllvm-dev at
lists.llvm.orghttp://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>
>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180117/fd64f12e/attachment.html>

Sent out the code review: https://reviews.llvm.org/D42771 & CC'd
everyone
who commented on this thread so they can easily follow along there.

On Wed, Jan 17, 2018 at 2:53 PM David Blaikie <dblaikie at gmail.com>
wrote:
> On Wed, Jan 17, 2018 at 1:27 PM Chandler Carruth <chandlerc at
gmail.com>
> wrote:
>
>> On Tue, Jan 16, 2018 at 11:35 AM Philip Reames <listmail at
philipreames.com>
>> wrote:
>>
>>>
>>>
>>> On 01/16/2018 09:21 AM, David Blaikie via llvm-dev wrote:
>>>
>>> Context: I've been looking at experimenting with using Modular
Code
>>> Generation (My talk at last year's LLVM dev meeting
>>> https://www.youtube.com/watch?v=lYYxDXgbUZ0 is about the best
reference
>>> at the moment) when building the LLVM project, as a good experiment
for the
>>> feature. This can/does enforce a stronger layering invariant than
LLVM has
>>> historically been enforced. So I'm curious to get buy-in and
maybe document
>>> this if it's something people like the idea of.
>>>
>>> I'm starting this discussion here rather than in an actual code
review
>>> on llvm-commits since it seems like it could do with a bit of a
wider
>>> discussion, but once/if the general direction is agreed on,
I'll send a
>>> patch for review of specific wording for the LLVM Coding Standards.
>>>
>>>
>>> Currently the LLVM Coding Standards
>>> <https://llvm.org/docs/CodingStandards.html> doesn't say
much/anything
>>> about layering. 'A Public Header File *is* a Module'
>>>
<https://llvm.org/docs/CodingStandards.html#a-public-header-file-is-a-module>
section
>>> talks about modules of functionality, mostly trying to describe why
a
>>> header file should be self contained - but uses anachronistic
language
>>> about modules that doesn't line up with the implicit or
explicit modules
>>> concepts in use today, I think.
>>>
>>> I propose making this wording a bit more explicit, including:
>>>
>>> 1) Headers should be standalone (include all their dependencies -
this
>>> is mentioned in the "is a Module" piece, by way of a
technique to help
>>> ensure this, but not explicit as a goal itself).
>>>
>>> 2) Files intended to be included in a particular context (that
aren't
>>> safe/benign to include multiple times, in multiple .cpp files, etc)
should
>>> use a '.inc' or '.def' (.def specifically for those
"define a macro,
>>> include the header which will reference that macro" style
setups we have in
>>> a few places).
>>>
>>> Everything up to here seems non-controversial.  We should document
this
>>> and ideally identify tooling suitable to enforce it.
>>>
>>
>> +1
>>
>>
>>>
>>>
>>> And the actual layering issue:
>>> 3) Each library should only include headers or otherwise reference
>>> entities from libraries it depends on. Including in headers and
inline
>>> functions. A simple/explicit way to put this: every inline function
should
>>> be able to be moved into a .cpp file and the build (with a unix
linker -
>>> one that cannot handle circular library dependencies) should still
succeed.
>>>
>>>
>>> This last point is the most interesting - and I hope one that
people
>>> generally find desirable, so it might not be immediately obvious
why it may
>>> be contentious or difficult:
>>>
>>> LLVM violates this constraint by using inline functions in headers
to
>>> avoid certain layering constraints that might otherwise cause the
build to
>>> fail. A couple of major examples I've hit are:
>>>
>>> TargetSelect.h
>>>
<http://lists.llvm.org/pipermail/llvm-dev/2017-December/119494.html>and
>>> similar: This one's especially tricky - the header is part of
libSupport,
>>> but each function in here depends on a different subset of targets
>>> (creating a circular dependency) - to call the given function the
>>> programmer needs to choose the right dependencies to link to or the
program
>>> will not link.
>>> Clang Diagnostics <https://reviews.llvm.org/D41357> (work in
progress):
>>> The diagnostics for each component are in their own component
directories,
>>> but are then all included from libClangBasic, a library none of
those
>>> components depends on. (so this isn't so much an inlining case
as #include
>>> based circular dependency)
>>>
>>>
>>> Generally I'd like to get buy-in that stricter layering is
desirable,
>>> and that these few cases are at least sub-optimal, if accepted for
now.
>>>
>>> I have no strong opinion on this topic.  My experience has been
that
>>> it's often far harder to unwind these types of inline
dependencies than it
>>> first seems and that the value in doing so is often unclear. 
I'm not
>>> opposed, but I'm also not signing up to help.  :)
>>>
>>
>> While I'm also not in a position to help a lot, I think there is a
>> question we should ask here:
>>
>> Should we hold new code to this standard? Should we declare that this
is
>> what we want?
>>
>> For me, I say emphatically "yes" and we should put it into
the coding
>> standards. I think cleaning up the existing code is a good thing to do
and
>> we can let people who have a reason actually drive that, but I
don't want
>> that to be necessarily finished in order for us to establish reasonable
>> guidelines going forward.
>>
>
> Yep, that's where I am too - I want it to be our standard going forward
> but, like naming conventions and other things, realize that not all
> existing code in the project will conform to this constraint.
>
> - Dave
>
>
>>
>>
>>>
>>> Happy to go into more details about any of this, examples, etc, but
I
>>> realize this is already a bit long.
>>> - Dave
>>>
>>>
>>> _______________________________________________
>>> LLVM Developers mailing listllvm-dev at
lists.llvm.orghttp://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>>>
>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20180201/3f29f136/attachment.html>