<div dir="ltr"><br><br><div class="gmail_quote"><div dir="ltr">On Tue, Jan 16, 2018 at 10:15 AM Robinson, Paul <<a href="mailto:paul.robinson@sony.com">paul.robinson@sony.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div lang="EN-US" link="blue" vlink="purple">
<div class="m_3991833971104045793WordSection1">
<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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></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.</span></p></div></div></blockquote><div><br>Fair point - Google's build system is pretty specific about this & so we've got it codified there, and the open source build system has to know some of this to get the link order right - otherwise LLVM programs couldn't successfully link (if the libraries weren't placed in the right order on the link command)<br><br>I think the the LLVMBuild.txt files contain the library dependency lists for the CMake build.<br><br>- Dave<br> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div lang="EN-US" link="blue" vlink="purple"><div class="m_3991833971104045793WordSection1"><p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d">--paulr<u></u><u></u></span></p>
<p class="MsoNormal"><a name="m_3991833971104045793__MailEndCompose"><span style="font-size:11.0pt;font-family:"Calibri","sans-serif";color:#1f497d"><u></u> <u></u></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:<a href="mailto:llvm-dev-bounces@lists.llvm.org" target="_blank">llvm-dev-bounces@lists.llvm.org</a>]
<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<u></u><u></u></span></p>
</div>
</div></div></div></div><div lang="EN-US" link="blue" vlink="purple"><div class="m_3991833971104045793WordSection1"><div style="border:none;border-left:solid blue 1.5pt;padding:0in 0in 0in 4.0pt">
<p class="MsoNormal"><u></u> <u></u></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" target="_blank">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" target="_blank">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" target="_blank">
'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" target="_blank">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" target="_blank">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<u></u><u></u></p>
</div>
</div></div></div></blockquote></div></div>