<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta name="Generator" content="Microsoft Word 14 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
        {font-family:Calibri;
        panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
        {font-family:Tahoma;
        panose-1:2 11 6 4 3 5 4 4 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
        {margin:0in;
        margin-bottom:.0001pt;
        font-size:12.0pt;
        font-family:"Times New Roman","serif";}
a:link, span.MsoHyperlink
        {mso-style-priority:99;
        color:blue;
        text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
        {mso-style-priority:99;
        color:purple;
        text-decoration:underline;}
span.EmailStyle17
        {mso-style-type:personal-reply;
        font-family:"Calibri","sans-serif";
        color:#1F497D;}
.MsoChpDefault
        {mso-style-type:export-only;
        font-family:"Calibri","sans-serif";}
@page WordSection1
        {size:8.5in 11.0in;
        margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
        {page:WordSection1;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]-->
</head>
<body lang="EN-US" link="blue" vlink="purple">
<div class="WordSection1">
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">I have found layering to be a particularly useful and beneficial model in past large software projects.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">Is LLVM's layering actually written down anywhere?  Last time I went looking, there was nothing.  If there's no spec, there's no verifiable conformance; you
 have to guess based on what other files do.<o:p></o:p></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D">--paulr<o:p></o:p></span></p>
<p class="MsoNormal"><a name="_MailEndCompose"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1F497D"><o:p> </o:p></span></a></p>
<div style="border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt">
<div>
<div style="border:none;border-top:solid #B5C4DF 1.0pt;padding:3.0pt 0in 0in 0in">
<p class="MsoNormal"><b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif"">From:</span></b><span style="font-size:10.0pt;font-family:"Tahoma","sans-serif""> llvm-dev [mailto:llvm-dev-bounces@lists.llvm.org]
<b>On Behalf Of </b>David Blaikie via llvm-dev<br>
<b>Sent:</b> Tuesday, January 16, 2018 9:22 AM<br>
<b>To:</b> llvm-dev; Richard Smith; Chandler Carruth; Reid Kleckner<br>
<b>Subject:</b> [llvm-dev] Layering Requirements in the LLVM Coding Style Guide<o:p></o:p></span></p>
</div>
</div>
<p class="MsoNormal"><o:p> </o:p></p>
<div>
<p class="MsoNormal">Context: I've been looking at experimenting with using Modular Code Generation (My talk at last year's LLVM dev meeting <a href="https://www.youtube.com/watch?v=lYYxDXgbUZ0">https://www.youtube.com/watch?v=lYYxDXgbUZ0</a> 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.<br>
<br>
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.<br>
<br>
<br>
Currently the <a href="https://llvm.org/docs/CodingStandards.html">LLVM Coding Standards</a> doesn't say much/anything about layering.
<a href="https://llvm.org/docs/CodingStandards.html#a-public-header-file-is-a-module">
'A Public Header File <b>is</b> a Module'</a> 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.<br>
<br>
I propose making this wording a bit more explicit, including:<br>
<br>
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).<br>
<br>
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).<br>
<br>
And the actual layering issue:<br>
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.<br>
<br>
<br>
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:<br>
<br>
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:<br>
<br>
<a href="http://lists.llvm.org/pipermail/llvm-dev/2017-December/119494.html">TargetSelect.h
</a>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.<br>
<a href="https://reviews.llvm.org/D41357">Clang Diagnostics</a> (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)<br>
<br>
<br>
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.<br>
<br>
Happy to go into more details about any of this, examples, etc, but I realize this is already a bit long.<br>
- Dave<o:p></o:p></p>
</div>
</div>
</div>
</body>
</html>