[flang-dev] Preparing for life in LLVM

[Richard Barton via flang-dev]

Hi flang-dev



On Monday March 16th, F18 is scheduled to become part of LLVM and the existing F18 repository will be frozen. This email aims to prepare you for this event.



What will happen on the day?

On Monday 16th (the exact time is still TBC) the following will happen:
*       F18 will be closed to new commits and new pull requests
*       Any open F18 pull requests will be closed
*       F18's github Issues will remain open and will remain the right place to open F18 issues. This is a short-term measure while we arrange for them to migrate to LLVM processes
*       F18 project boards will remain live to track ongoing work. This is also a short-term measure while we arrange for them to migrate elsewhere.



How do I work on F18 going forward?
*       F18's new home will be in a directory called "flang" at https://github.com/llvm/llvm-project
*       The build instructions will change - see [1] for more information.
*       The LLVM project does not accept github pull requests. In order to submit a patch for code review you need to use the phabricator instance at https://reviews.llvm.org/. See [2] for details.
*       In order to commit an approved code review you will need to get commit access to the repository - see [3] for instructions.



What should I do now?

In this last week before merging I suggest that you:
*       Prioritise finishing off any last PRs that are close to being accepted.
*       Read the LLVM Developer policy https://llvm.org/docs/DeveloperPolicy.html.
*       Set up an account on phabricator and set up arcanist (if you like) [2]
*       If you have downstream builds, get a head start on porting them to the new build setup.



If there are any questions then please feel free to ask on flang-dev as there are a few llvm-dev veterans on the list who can probably answer.



Thanks

Rich



[1] New build instructions for F18



The way to build F18 will change slightly once it is inside the LLVM project. The general instructions for building LLVM are at https://github.com/llvm/llvm-project#getting-the-source-code-and-building-llvm. F18 will be enabled in an LLVM build by passing -DLLVM_ENABLE_PROJECTS="mlir;flang" to cmake. The build instructions for F18 will be updated accordingly. These are currently at https://github.com/flang-compiler/f18#building-f18. They will be moved to an equivalent location at llvm-project/flang/README.md.



If you want to get a head start on this build setup then you can mimic today with these steps.


1.       Clone the llvm-project git repo

git clone https://github.com/llvm/llvm-project.git
2.       Clone F18 inside llvm-project as "flang"

cd llvm-project

git clone https://github.com/<https://github.com/llvm/llvm-project.git>flang-compiler/f18.git flang
o   It helps to teach llvm-project to ignore that flag is a separate clone

echo "# flang (pre-merge)" >> .gitignore

echo "flang" >> .gitignore

git commit -a -m "Ignore flang repo"
3.       Apply the F18 patch for the new cmake setup https://github.com/flang-compiler/f18/pull/1045 (unless it has already been merged, in which case you can skip this step)

cd flang

git fetch origin pull/1045/head:pr-1045

git checkout pr-1045
4.       Apply the patch to add flang as a project to LLVM: https://reviews.llvm.org/D72416
a.       If you have set up your phabricator account and arcanist [2] then you can do

cd ..

arc patch D72416

If you have not done this, then the patch can be manually downloaded from the web UI or you could just apply it by hand as it very small.
5.       Build LLVM with -DLLVM_ENABLE_PROJECTS="mlir;flang" -DLLVM_EXTERNAL_PROJECTS=flang added to the usual options

mkdir build && cd build

cmake -DLLVM_ENABLE_PROJECTS="mlir;flang" -DLLVM_EXTERNAL_PROJECTS=flang -DCMAKE_INSTALL_PREFIX=`pwd`/../install -DLLVM_TARGETS_TO_BUILD=host -DCMAKE_BUILD_TYPE=Release ../llvm

make -j64

Note: after F18 is merged to the monorepo -DLLVM_EXTERNAL_PROJECTS will not need to be set.



There should be no other changes in build-time tool requirements from when building F18 as part of the F18 project.





[2] Code review in LLVM



LLVM strongly encourages open, pre-commit code review on all changes. More information is here: https://llvm.org/docs/DeveloperPolicy.html#code-reviews and https://llvm.org/docs/CodeReview.html



https://llvm.org/docs/Contributing.html#how-to-submit-a-patch explains how to submit a patch to LLVM for code review.



As with F18, large or controversial changes require a prior RFC to be circulated. We will use flang-dev (this list) for these as usual.



Technically speaking, it is possible to get a code review by emailing a patch to the commits list, in our case flang-commits at lists.llvm.org however the vast majority of patches are reviewed in Phabricator so this is the preferred route. You will find it easier to attract the attention of potential reviewers in this tool.



Phabricator requires you to create an account - see https://llvm.org/docs/Phabricator.html#sign-up.

Phabricator reviews can be started via the web UI https://llvm.org/docs/Phabricator.html#phabricator-request-review-web or there is a command line tool called arcanist- see https://llvm.org/docs/Phabricator.html#requesting-a-review-via-the-command-line.



If committing via the Web UI a common mistake is to make a patch with not enough context. Remember to use the -U999999 option when creating your patches.



Also when committing via the web UI you need to remember to add the "Differential Revision: <URL>" line as the last line of the commit message yourself. If you use arcanist it will do this for you. Doing this will close the Phabricator review automatically saving you going back to the UI to do this. See also https://llvm.org/docs/Phabricator.html#committing-a-change



As with F18, Code review is open in LLVM and all developers are invited to review. The interface is similar to github. There is an RFC on the llvm-dev list about moving to github PRs but such a move will be take time. When we are a part of the community, we can lend our voice to the debate.



Flang will gain a CODE_OWNERS file before we merge which establishes maintainers or reviewers in chief.



There is a tool called Herald https://secure.phabricator.com/book/phabricator/article/herald/ which you can use to get automated messages on new phab reviews in a specific area.



For those used to reviewing github pull requests and who pull in changes to their local clone to play around with, the arcanist tool is the way to go. Once set up you can pull a patch down from Phabricator to a local branch using:

arc patch D<number>



[3] Submitting a patch



Once your patch has been code reviewed and approved you need to commit to

https://github.com/llvm/llvm-project.git. If you don't have commit access, it is generally ok to ask someone (probably your reviewer) to submit it on your behalf. We are arranging for all regular F18 contributors to have commit access established before the merge happens.



To get commit access you follow the process here: https://llvm.org/docs/DeveloperPolicy.html#obtaining-commit-access.



See also https://llvm.org/docs/DeveloperPolicy.html#making-and-submitting-a-patch for more information.



One aspect to be aware of are the LLVM buildbots running at http://lab.llvm.org:8011/console. If any commit regresses a stable builder it is standard for the maintainer or another community member to revert the patch to restore the builder to green before further investigation can take place on the real fix. This is a normal event and it is then the responsibility of the original committer to adapt the commit so that it can be resubmitted in a way that passes the buildbot. F18 will not be a default target for LLVM when we first land, so it is unlikely that any commits in the early days will cause a buildbot failure. We will add buildbots after we land in the monorepo.



Created with Microsoft OneNote 2016.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/flang-dev/attachments/20200309/2ecec693/attachment-0001.html>