]>
Commit | Line | Data |
---|---|---|
9f95a23c TL |
1 | Essentials (tl;dr) |
2 | ================== | |
3 | ||
4 | This chapter presents essential information that every Ceph developer needs | |
5 | to know. | |
6 | ||
7 | Leads | |
8 | ----- | |
9 | ||
10 | The Ceph project is led by Sage Weil. In addition, each major project | |
11 | component has its own lead. The following table shows all the leads and | |
12 | their nicks on `GitHub`_: | |
13 | ||
14 | .. _github: https://github.com/ | |
15 | ||
16 | ========= ================ ============= | |
17 | Scope Lead GitHub nick | |
18 | ========= ================ ============= | |
19 | Ceph Sage Weil liewegas | |
20 | RADOS Neha Ojha neha-ojha | |
21 | RGW Yehuda Sadeh yehudasa | |
22 | RGW Matt Benjamin mattbenjamin | |
23 | RBD Jason Dillaman dillaman | |
24 | CephFS Patrick Donnelly batrick | |
25 | Dashboard Lenz Grimmer LenzGr | |
26 | MON Joao Luis jecluis | |
27 | Build/Ops Ken Dreyer ktdreyer | |
f67539c2 | 28 | Docs Zac Dover zdover23 |
9f95a23c TL |
29 | ========= ================ ============= |
30 | ||
31 | The Ceph-specific acronyms in the table are explained in | |
32 | :doc:`/architecture`. | |
33 | ||
34 | History | |
35 | ------- | |
36 | ||
37 | See the `History chapter of the Wikipedia article`_. | |
38 | ||
39 | .. _`History chapter of the Wikipedia article`: https://en.wikipedia.org/wiki/Ceph_%28software%29#History | |
40 | ||
41 | Licensing | |
42 | --------- | |
43 | ||
44 | Ceph is free software. | |
45 | ||
46 | Unless stated otherwise, the Ceph source code is distributed under the | |
47 | terms of the LGPL2.1 or LGPL3.0. For full details, see the file | |
48 | `COPYING`_ in the top-level directory of the source-code tree. | |
49 | ||
50 | .. _`COPYING`: | |
51 | https://github.com/ceph/ceph/blob/master/COPYING | |
52 | ||
53 | Source code repositories | |
54 | ------------------------ | |
55 | ||
56 | The source code of Ceph lives on `GitHub`_ in a number of repositories below | |
57 | the `Ceph "organization"`_. | |
58 | ||
59 | .. _`Ceph "organization"`: https://github.com/ceph | |
60 | ||
f67539c2 | 61 | A working knowledge of git_ is essential to make a meaningful contribution to the project as a developer. |
9f95a23c TL |
62 | |
63 | .. _git: https://git-scm.com/doc | |
64 | ||
65 | Although the `Ceph "organization"`_ includes several software repositories, | |
66 | this document covers only one: https://github.com/ceph/ceph. | |
67 | ||
68 | Redmine issue tracker | |
69 | --------------------- | |
70 | ||
71 | Although `GitHub`_ is used for code, Ceph-related issues (Bugs, Features, | |
72 | Backports, Documentation, etc.) are tracked at http://tracker.ceph.com, | |
73 | which is powered by `Redmine`_. | |
74 | ||
75 | .. _Redmine: http://www.redmine.org | |
76 | ||
77 | The tracker has a Ceph project with a number of subprojects loosely | |
78 | corresponding to the various architectural components (see | |
79 | :doc:`/architecture`). | |
80 | ||
81 | Mere `registration`_ in the tracker automatically grants permissions | |
82 | sufficient to open new issues and comment on existing ones. | |
83 | ||
84 | .. _registration: http://tracker.ceph.com/account/register | |
85 | ||
86 | To report a bug or propose a new feature, `jump to the Ceph project`_ and | |
87 | click on `New issue`_. | |
88 | ||
89 | .. _`jump to the Ceph project`: http://tracker.ceph.com/projects/ceph | |
90 | .. _`New issue`: http://tracker.ceph.com/projects/ceph/issues/new | |
91 | ||
f67539c2 | 92 | .. _mailing-list: |
9f95a23c | 93 | |
f67539c2 TL |
94 | Mailing lists |
95 | ------------- | |
96 | ||
97 | Ceph Development Mailing List | |
98 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
9f95a23c TL |
99 | The ``dev@ceph.io`` list is for discussion about the development of Ceph, |
100 | its interoperability with other technology, and the operations of the | |
101 | project itself. | |
102 | ||
f67539c2 TL |
103 | The email discussion list for Ceph development is open to all. Subscribe by |
104 | sending a message to ``dev-request@ceph.io`` with the following line in the | |
105 | body of the message:: | |
9f95a23c TL |
106 | |
107 | subscribe ceph-devel | |
108 | ||
9f95a23c | 109 | |
f67539c2 TL |
110 | Ceph Client Patch Review Mailing List |
111 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
9f95a23c TL |
112 | The ``ceph-devel@vger.kernel.org`` list is for discussion and patch review |
113 | for the Linux kernel Ceph client component. Note that this list used to | |
f67539c2 TL |
114 | be an all-encompassing list for developers. When searching the archives, |
115 | remember that this list contains the generic devel-ceph archives before mid-2018. | |
9f95a23c | 116 | |
f67539c2 TL |
117 | Subscribe to the list covering the Linux kernel Ceph client component by sending |
118 | a message to ``majordomo@vger.kernel.org`` with the following line in the body | |
119 | of the message:: | |
9f95a23c TL |
120 | |
121 | subscribe ceph-devel | |
122 | ||
9f95a23c | 123 | |
f67539c2 TL |
124 | Other Ceph Mailing Lists |
125 | ^^^^^^^^^^^^^^^^^^^^^^^^ | |
9f95a23c TL |
126 | |
127 | There are also `other Ceph-related mailing lists`_. | |
128 | ||
129 | .. _`other Ceph-related mailing lists`: https://ceph.com/irc/ | |
130 | ||
f67539c2 TL |
131 | .. _irc: |
132 | ||
9f95a23c TL |
133 | |
134 | IRC | |
135 | --- | |
136 | ||
f67539c2 TL |
137 | In addition to mailing lists, the Ceph community also communicates in real time |
138 | using `Internet Relay Chat`_. | |
9f95a23c TL |
139 | |
140 | .. _`Internet Relay Chat`: http://www.irchelp.org/ | |
141 | ||
142 | See ``https://ceph.com/irc/`` for how to set up your IRC | |
143 | client and a list of channels. | |
144 | ||
f67539c2 TL |
145 | .. _submitting-patches: |
146 | ||
9f95a23c TL |
147 | Submitting patches |
148 | ------------------ | |
149 | ||
150 | The canonical instructions for submitting patches are contained in the | |
151 | file `CONTRIBUTING.rst`_ in the top-level directory of the source-code | |
152 | tree. There may be some overlap between this guide and that file. | |
153 | ||
154 | .. _`CONTRIBUTING.rst`: | |
155 | https://github.com/ceph/ceph/blob/master/CONTRIBUTING.rst | |
156 | ||
157 | All newcomers are encouraged to read that file carefully. | |
158 | ||
159 | Building from source | |
160 | -------------------- | |
161 | ||
162 | See instructions at :doc:`/install/build-ceph`. | |
163 | ||
164 | Using ccache to speed up local builds | |
165 | ------------------------------------- | |
f67539c2 TL |
166 | `ccache`_ can make the process of rebuilding the ceph source tree faster. |
167 | ||
168 | Before you use `ccache`_ to speed up your rebuilds of the ceph source tree, | |
169 | make sure that your source tree is clean and will produce no build failures. | |
170 | When you have a clean source tree, you can confidently use `ccache`_, secure in | |
171 | the knowledge that you're not using a dirty tree. | |
172 | ||
173 | Old build artifacts can cause build failures. You might introduce these | |
174 | artifacts unknowingly when switching from one branch to another. If you see | |
175 | build errors when you attempt a local build, follow the procedure below to | |
176 | clean your source tree. | |
9f95a23c | 177 | |
f67539c2 TL |
178 | Cleaning the Source Tree |
179 | ^^^^^^^^^^^^^^^^^^^^^^^^ | |
9f95a23c | 180 | |
f67539c2 | 181 | .. prompt:: bash $ |
9f95a23c | 182 | |
f67539c2 TL |
183 | make clean |
184 | ||
185 | .. note:: The following commands will remove everything in the source tree | |
186 | that isn't tracked by git. Make sure to back up your log files | |
187 | and configuration options before running these commands. | |
9f95a23c | 188 | |
f67539c2 | 189 | .. prompt:: bash $ |
9f95a23c | 190 | |
f67539c2 | 191 | git clean -fdx; git submodule foreach git clean -fdx |
9f95a23c | 192 | |
f67539c2 TL |
193 | Building Ceph with ccache |
194 | ^^^^^^^^^^^^^^^^^^^^^^^^^ | |
195 | ``ccache`` is available as a package in most distros. To build ceph with | |
196 | ccache, run the following command. | |
9f95a23c | 197 | |
f67539c2 | 198 | .. prompt:: bash $ |
9f95a23c | 199 | |
f67539c2 | 200 | cmake -DWITH_CCACHE=ON .. |
9f95a23c | 201 | |
f67539c2 TL |
202 | Using ccache to Speed Up Build Times |
203 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
204 | ``ccache`` can be used for speeding up all builds of the system. For more | |
205 | details, refer to the `run modes`_ section of the ccache manual. The default | |
206 | settings of ``ccache`` can be displayed with the ``ccache -s`` command. | |
207 | ||
208 | .. note:: We recommend overriding the ``max_size``. The default is 10G. | |
209 | Use a larger value, like 25G. Refer to the `configuration`_ section | |
210 | of the ccache manual for more information. | |
9f95a23c TL |
211 | |
212 | To further increase the cache hit rate and reduce compile times in a | |
f67539c2 TL |
213 | development environment, set the version information and build timestamps to |
214 | fixed values. This makes it unnecessary to rebuild the binaries that contain | |
215 | this information. | |
9f95a23c TL |
216 | |
217 | This can be achieved by adding the following settings to the ``ccache`` | |
218 | configuration file ``ccache.conf``:: | |
219 | ||
220 | sloppiness = time_macros | |
221 | run_second_cpp = true | |
222 | ||
223 | Now, set the environment variable ``SOURCE_DATE_EPOCH`` to a fixed value (a | |
224 | UNIX timestamp) and set ``ENABLE_GIT_VERSION`` to ``OFF`` when running | |
f67539c2 TL |
225 | ``cmake``: |
226 | ||
227 | .. prompt:: bash $ | |
9f95a23c | 228 | |
f67539c2 TL |
229 | export SOURCE_DATE_EPOCH=946684800 |
230 | cmake -DWITH_CCACHE=ON -DENABLE_GIT_VERSION=OFF .. | |
9f95a23c TL |
231 | |
232 | .. note:: Binaries produced with these build options are not suitable for | |
233 | production or debugging purposes, as they do not contain the correct build | |
234 | time and git version information. | |
235 | ||
236 | .. _`ccache`: https://ccache.samba.org/ | |
237 | .. _`run modes`: https://ccache.samba.org/manual.html#_run_modes | |
238 | .. _`configuration`: https://ccache.samba.org/manual.html#_configuration | |
239 | ||
240 | Development-mode cluster | |
241 | ------------------------ | |
242 | ||
243 | See :doc:`/dev/quick_guide`. | |
244 | ||
245 | Kubernetes/Rook development cluster | |
246 | ----------------------------------- | |
247 | ||
248 | See :ref:`kubernetes-dev` | |
249 | ||
f67539c2 TL |
250 | .. _backporting: |
251 | ||
9f95a23c TL |
252 | Backporting |
253 | ----------- | |
254 | ||
255 | All bugfixes should be merged to the ``master`` branch before being | |
256 | backported. To flag a bugfix for backporting, make sure it has a | |
257 | `tracker issue`_ associated with it and set the ``Backport`` field to a | |
258 | comma-separated list of previous releases (e.g. "hammer,jewel") that you think | |
259 | need the backport. | |
260 | The rest (including the actual backporting) will be taken care of by the | |
261 | `Stable Releases and Backports`_ team. | |
262 | ||
263 | .. _`tracker issue`: http://tracker.ceph.com/ | |
264 | .. _`Stable Releases and Backports`: http://tracker.ceph.com/projects/ceph-releases/wiki | |
265 | ||
266 | Guidance for use of cluster log | |
267 | ------------------------------- | |
268 | ||
269 | If your patches emit messages to the Ceph cluster log, please consult | |
f67539c2 | 270 | this: :doc:`/dev/logging`. |