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