Tutorial: How to contribute to upstream LLVM

As a LLVM Developer, you will have to know how to use the Phabricator if you want to contribute a patch(commit) to the upstream. You can know more about what is upstream here.

Prerequisite

There are too many articles on how to use Git, so go Google it if you don’t know how to do the following:

  • Creating a commit in a repository
  • Create / Delete / Switch between branches
  • Rebase a branch to another
  • Revert a commit
  • The difference between “Squash and merge” and “Rebase and merge”

In the context of LLVM upstream development, the term “patch” refers to a “revision” that will later be committed to upstream when it is accepted. You will be submitting a commit by creating a revision to the Phabricator. Here is an example of how a revision looks like: https://reviews.llvm.org/D99323.

Phabricator

LLVM’s patch review website is based on Phabricator, you can find it on https://reviews.llvm.org/.

Arcanist is a command-line interface for Phabricator. You can find how to download it in the link. Other than that, you may encounter certificate issues, you can resolve with the instructions mentioned here(https://reviews.llvm.org/D110976).

LLVM’s revision is different from GitHub’s pull request. GitHub’s pull request can contain multiple commits, while LLVM’s revision can only contain 1 commit. So if you have multiple commits, you either squash it into one commits or create multiple revision.

Here are some commands I frequently use, feel free to help me update this document.

  • arc diff : This command generates a “differential” (aka revision) of the local change. A revision will belong to a patch. You can later commit the revision when it is accepted by other reviewers.
    • arc diff --create : Create a revision upon local change
      • After the command, Arcanist will bring you to your local editor to jot down commit messages
    • arc diff --update [REVISION_ID] : Update a revision upon local change
      • You may use this when reviewers ask for you to rebase the current revision upon the latest main.
  • arc patch [REVISION_ID] : Grep a certain online revision to your local Git.
    • You may use this when you want to continue a patch you have been working on.
    • The patch may be old compared to the latest main, and you may have to recompile many things when you switch to an older commit.
  • arc amend
    • Update commit messages, it adds reviewers name into the commit when it is accepted.
  • arc set-config editor vim
    • If your default editor is not vim

Note

Ask your reviewer to commit your 1st commit

At least for myself, I was told that usually the 1st commit of a new contributor will be committed by the reviewer that already has commit access to the upstream repository. So you may kindly ask the reviewer to do it for you.

After that you may want commit access of your own since you are actively part of the community right now! You can request for commit access from Mr. Lattner by sending him an email. I believe after you have done the 1st commit you must be able to find his email link, so I will not expose it here 😉.

Make sure you can be online and revert your patch when you commit it

In case you break the build, make sure you are able to stay around for an hour or two after your commit before you do it. You will be spammed with mail-bots of failure notifications if you really did break the build.

Subscribe to mailing list

You may want to subscribe to the LLVM mailing list and LLVM Weekly to keep yourself up-to-date on some upstream development.

LLVM Documents

Some LLVM documents you might find helpful:

[1] https://llvm.org/docs/Contributing.html
[2] https://llvm.org/docs/Phabricator.html
[3] https://llvm.org/docs/DeveloperPolicy.html

Author: eopXD

Hi 我是 eopXD ,希望人生過得有趣有挑戰。有任何問題都可以寄到 eopxdd[at]gmail.com。

One thought on “Tutorial: How to contribute to upstream LLVM”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: