1================================== 2Contributing to LLVM 3================================== 4 5 6Thank you for your interest in contributing to LLVM! There are multiple ways to 7contribute, and we appreciate all contributions. In case you 8have questions, you can either use the `Developer's List (llvm-dev)`_ 9or the #llvm channel on `irc.oftc.net`_. 10 11If you want to contribute code, please familiarize yourself with the :doc:`DeveloperPolicy`. 12 13.. contents:: 14 :local: 15 16 17Ways to Contribute 18================== 19 20Bug Reports 21----------- 22If you are working with LLVM and run into a bug, we definitely want to know 23about it. Please let us know and follow the instructions in 24:doc:`HowToSubmitABug` to create a bug report. 25 26Bug Fixes 27--------- 28If you are interested in contributing code to LLVM, bugs labeled with the 29`beginner keyword`_ in the `bug tracker`_ are a good way to get familiar with 30the code base. If you are interested in fixing a bug, please create an account 31for the bug tracker and assign it to yourself, to let people know you are working on 32it. 33 34Then try to reproduce and fix the bug with upstream LLVM. Start by building 35LLVM from source as described in :doc:`GettingStarted` and 36and use the built binaries to reproduce the failure described in the bug. Use 37a debug build (`-DCMAKE_BUILD_TYPE=Debug`) or a build with assertions 38(`-DLLVM_ENABLE_ASSERTIONS=On`, enabled for Debug builds). 39 40Reporting a Security Issue 41-------------------------- 42 43There is a separate process to submit security-related bugs, see :ref:`report-security-issue`. 44 45Bigger Pieces of Work 46--------------------- 47In case you are interested in taking on a bigger piece of work, a list of 48interesting projects is maintained at the `LLVM's Open Projects page`_. In case 49you are interested in working on any of these projects, please send a mail to 50the `LLVM Developer's mailing list`_, so that we know the project is being 51worked on. 52 53How to Submit a Patch 54===================== 55Once you have a patch ready, it is time to submit it. The patch should: 56 57* include a small unit test 58* conform to the :doc:`CodingStandards`. You can use the `clang-format-diff.py`_ or `git-clang-format`_ tools to automatically format your patch properly. 59* not contain any unrelated changes 60* be an isolated change. Independent changes should be submitted as separate patches as this makes reviewing easier. 61 62.. _format patches: 63 64Before sending a patch for review, please also try to ensure it is 65formatted properly. We use ``clang-format`` for this, which has git integration 66through the ``git-clang-format`` script. On some systems, it may already be 67installed (or be installable via your package manager). If so, you can simply 68run it -- the following command will format only the code changed in the most 69recent commit: 70 71.. code-block:: console 72 73 % git clang-format HEAD~1 74 75Note that this modifies the files, but doesn't commit them -- you'll likely want 76to run 77 78.. code-block:: console 79 80 % git commit --amend -a 81 82in order to update the last commit with all pending changes. 83 84.. note:: 85 If you don't already have ``clang-format`` or ``git clang-format`` installed 86 on your system, the ``clang-format`` binary will be built alongside clang, and 87 the git integration can be run from 88 ``clang/tools/clang-format/git-clang-format``. 89 90 91To get a patch accepted, it has to be reviewed by the LLVM community. This can 92be done using `LLVM's Phabricator`_ or the llvm-commits mailing list. 93Please follow :ref:`Phabricator#requesting-a-review-via-the-web-interface <phabricator-request-review-web>` 94to request a review using Phabricator. 95 96To make sure the right people see your patch, please select suitable reviewers 97and add them to your patch when requesting a review. Suitable reviewers are the 98code owner (see CODE_OWNERS.txt) and other people doing work in the area your 99patch touches. If you are using Phabricator, add them to the `Reviewers` field 100when creating a review and if you are using `llvm-commits`, add them to the CC of 101your email. 102 103A reviewer may request changes or ask questions during the review. If you are 104uncertain on how to provide test cases, documentation, etc., feel free to ask 105for guidance during the review. Please address the feedback and re-post an 106updated version of your patch. This cycle continues until all requests and comments 107have been addressed and a reviewer accepts the patch with a `Looks good to me` or `LGTM`. 108Once that is done the change can be committed. If you do not have commit 109access, please let people know during the review and someone should commit it 110on your behalf. 111 112If you have received no comments on your patch for a week, you can request a 113review by 'ping'ing a patch by responding to the email thread containing the 114patch, or the Phabricator review with "Ping." The common courtesy 'ping' rate 115is once a week. Please remember that you are asking for valuable time from other 116professional developers. 117 118For more information on LLVM's code-review process, please see :doc:`CodeReview`. 119 120 121Helpful Information About LLVM 122============================== 123:doc:`LLVM's documentation <index>` provides a wealth of information about LLVM's internals as 124well as various user guides. The pages listed below should provide a good overview 125of LLVM's high-level design, as well as its internals: 126 127:doc:`GettingStarted` 128 Discusses how to get up and running quickly with the LLVM infrastructure. 129 Everything from unpacking and compilation of the distribution to execution 130 of some tools. 131 132:doc:`LangRef` 133 Defines the LLVM intermediate representation. 134 135:doc:`ProgrammersManual` 136 Introduction to the general layout of the LLVM sourcebase, important classes 137 and APIs, and some tips & tricks. 138 139`LLVM for Grad Students`__ 140 This is an introduction to the LLVM infrastructure by Adrian Sampson. While it 141 has been written for grad students, it provides a good, compact overview of 142 LLVM's architecture, LLVM's IR and how to write a new pass. 143 144 .. __: http://www.cs.cornell.edu/~asampson/blog/llvm.html 145 146`Intro to LLVM`__ 147 Book chapter providing a compiler hacker's introduction to LLVM. 148 149 .. __: http://www.aosabook.org/en/llvm.html 150 151.. _Developer's List (llvm-dev): http://lists.llvm.org/mailman/listinfo/llvm-dev 152.. _irc.oftc.net: irc://irc.oftc.net/llvm 153.. _beginner keyword: https://bugs.llvm.org/buglist.cgi?bug_status=NEW&bug_status=REOPENED&keywords=beginner%2C%20&keywords_type=allwords&list_id=130748&query_format=advanced&resolution=--- 154.. _bug tracker: https://bugs.llvm.org 155.. _clang-format-diff.py: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/clang-format-diff.py 156.. _git-clang-format: https://reviews.llvm.org/source/clang/browse/cfe/trunk/tools/clang-format/git-clang-format 157.. _LLVM's Phabricator: https://reviews.llvm.org/ 158.. _LLVM's Open Projects page: https://llvm.org/OpenProjects.html#what 159.. _LLVM Developer's mailing list: http://lists.llvm.org/mailman/listinfo/llvm-dev 160