<html 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 15 (filtered medium)">
<style><!--
/* Font Definitions */
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:11.0pt;
font-family:"Calibri",sans-serif;}
span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:windowtext;}
.MsoChpDefault
{mso-style-type:export-only;
font-size:10.0pt;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
--></style>
</head>
<body lang="EN-US" link="#0563C1" vlink="#954F72">
<div class="WordSection1">
<p class="MsoNormal">My comments and questions are below in line.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Tim<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> Hi list<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> As discussed on previous threads, we need to propose a plan for making F18 more LLVM-like in style and use of LLVM APIs and facilities. David is working on getting the permissions to put this into a github project in LLVM so we can collaborate
. In order to make progress ahead of that happening, I'd like to have a go on email.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> For each area I would like to capture a list of work items we'll commit to doing before merge to monorepo. I want us to be happy we can achieve these in a short time period so we can propose a new merging date. I'd also like to create
a list of items we'll commit to fixing after merging to the monorepo and a timeline for getting that done.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> Note that I'll only cover API and coding style work items in this thread. The other initiatives we can discuss in other threads. I'll just say that we'll propose cmake changes and porting test suite to lit in the pre-merge stuff and setting
up build bots in the post-merge stuff.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> When he has access, David can create two projects one for pre-merge and one for post-merge and we'll put everything in there.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> Please consider the below a strawman. All dates can change, all list items can change position, new ones can be added, items can be deleted, etc.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> What do people think about these lists? Do we think those two dates are do-able?<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> Ta<o:p></o:p></p>
<p class="MsoNormal">> Rich<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> Proposal:<o:p></o:p></p>
<p class="MsoNormal">> We will make the following style changes before merging to the monorepo<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> F18 changes to make it more LLVM-like in code style<o:p></o:p></p>
<p class="MsoNormal">> 1. Rationalise headers to put public headers in /include and not /lib<o:p></o:p></p>
<p class="MsoNormal">> 2. Unify F18's clang-format file to match LLVMs<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">We should discuss what should be in .clang-format with an eye to make it more like LLVM's.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> 3. Rename all .cc files to .cpp<o:p></o:p></p>
<p class="MsoNormal">> 4. Switch module names to starting with capital letters<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">What does "module" mean in this context?<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> Increase use of LLVM APIs and utilities in F18<o:p></o:p></p>
<p class="MsoNormal">> a. Switch F18 custom File handling to LLVM's File handling (helps with non-POSIX platform support)<o:p></o:p></p>
<p class="MsoNormal">> b. Change uses of <iostream> to LLVM's streams<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">F18 doesn't use <iostream>.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> c. Migrate use of std::list to a suitable alternative in LLVM's API<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I would say: replace std::list with a better data structure where appropriate.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> d. Use llvm_unreachable with an error message for unreachable cases<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">What does llvm_unreachable do for us?<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> e. Use llvm::Error instead of error codes if and when error codes are used.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">I don't know of any use of error codes.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> We would like to aim for a merge date of Monday 24th Feb to merge to the monorepo with all of the above changes committed to F18 master.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> We then propose to make the following changes after merging to the monorepo.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> F18 changes to make it more LLVM-like in code style<o:p></o:p></p>
<p class="MsoNormal">> We will commit to a perform a one-off exercise where we automatically audit the code to find these instances and bring them in line.<o:p></o:p></p>
<p class="MsoNormal">> 1. Eliminate braces from all single-line if statements<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">This seems like a really bad idea and would like to see a reason for it.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> 2. Eliminate all uses of else-after-return<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Doing this blindly is also a bad idea.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> 3. Add doxygen infrastructure so we can generate docs<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> Increase use of LLVM APIs and utilities in F18<o:p></o:p></p>
<p class="MsoNormal">> a. std::string → StringRef where appropriate<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">These aren't similar data structures. std::string owns the string data and StringRef does not. std::string_view is now a standard class for the latter case.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> b. std::vector → llvm::SmallVector where appropriate<o:p></o:p></p>
<p class="MsoNormal">> c. std::set → llvm::SmallSet/llvm::StringSet/llvm::DenseSet where appropriate<o:p></o:p></p>
<p class="MsoNormal">> d. std::map → llvm::StringMap/llvm::DenseMap where appropriate<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">As long as "where appropriate" means there is tangible benefit to changing from a standard type to a non-standard one. Not just change for the sake of change.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> e. Audit functions in include/flang/common and port to LLVM equivalents (e.g. builtin_popcount)<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> Assuming we hit the above merge date, we think we can commit to making these changes before the LLVM11 branch is taken in June.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> After that date, we will continue to make progress towards LLVM style and API usage by fixing things as we find them during development and enforce the new style through code review.<o:p></o:p></p>
<p class="MsoNormal">> <o:p></o:p></p>
<p class="MsoNormal">> A few specific areas that have been mentioned before that we will tackle in this way are:<o:p></o:p></p>
<p class="MsoNormal">> - Add doxygen style comments and file comments<o:p></o:p></p>
<p class="MsoNormal">> - Find more expressive names for classes, files, etc.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Names are already supposed to be expressive. Improvements are always welcome.<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">> - Refactor code to use early exits<o:p></o:p></p>
<p class="MsoNormal"><o:p> </o:p></p>
<p class="MsoNormal">Where it improves the code, not blindly. As with improving names, there is no reason to wait for any specific date to make improvements to the code.<o:p></o:p></p>
</div>
<DIV>
<HR>
</DIV>
<DIV>This email message is for the sole use of the intended recipient(s) and may
contain confidential information. Any unauthorized review, use, disclosure
or distribution is prohibited. If you are not the intended recipient,
please contact the sender by reply email and destroy all copies of the original
message. </DIV>
<DIV>
<HR>
</DIV>
</body>
</html>