]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | # Ceph - a scalable distributed storage system |
2 | ||
3 | Please see http://ceph.com/ for current info. | |
4 | ||
5 | ||
6 | ## Contributing Code | |
7 | ||
9f95a23c | 8 | Most of Ceph is dual licensed under the LGPL version 2.1 or 3.0. Some |
20effc67 | 9 | miscellaneous code is under a BSD-style license or is public domain. |
7c673cae | 10 | The documentation is licensed under Creative Commons |
94b18763 | 11 | Attribution Share Alike 3.0 (CC-BY-SA-3.0). There are a handful of headers |
7c673cae FG |
12 | included here that are licensed under the GPL. Please see the file |
13 | COPYING for a full inventory of licenses by file. | |
14 | ||
15 | Code contributions must include a valid "Signed-off-by" acknowledging | |
16 | the license for the modified or contributed file. Please see the file | |
17 | SubmittingPatches.rst for details on what that means and on how to | |
18 | generate and submit patches. | |
19 | ||
20 | We do not require assignment of copyright to contribute code; code is | |
21 | contributed under the terms of the applicable license. | |
22 | ||
23 | ||
24 | ## Checking out the source | |
25 | ||
26 | You can clone from github with | |
27 | ||
28 | git clone git@github.com:ceph/ceph | |
29 | ||
30 | or, if you are not a github user, | |
31 | ||
32 | git clone git://github.com/ceph/ceph | |
33 | ||
34 | Ceph contains many git submodules that need to be checked out with | |
35 | ||
36 | git submodule update --init --recursive | |
37 | ||
38 | ||
39 | ## Build Prerequisites | |
40 | ||
41 | The list of Debian or RPM packages dependencies can be installed with: | |
42 | ||
43 | ./install-deps.sh | |
44 | ||
45 | ||
46 | ## Building Ceph | |
47 | ||
48 | Note that these instructions are meant for developers who are | |
49 | compiling the code for development and testing. To build binaries | |
20effc67 | 50 | suitable for installation we recommend you build deb or rpm packages |
c07f9fc5 | 51 | or refer to the `ceph.spec.in` or `debian/rules` to see which |
7c673cae FG |
52 | configuration options are specified for production builds. |
53 | ||
7c673cae FG |
54 | Build instructions: |
55 | ||
56 | ./do_cmake.sh | |
57 | cd build | |
20effc67 | 58 | ninja |
7c673cae | 59 | |
20effc67 | 60 | (do_cmake.sh now defaults to creating a debug build of ceph that can |
11fdf7f2 | 61 | be up to 5x slower with some workloads. Please pass |
9f95a23c | 62 | "-DCMAKE_BUILD_TYPE=RelWithDebInfo" to do_cmake.sh to create a non-debug |
20effc67 | 63 | release. |
11fdf7f2 | 64 | |
20effc67 TL |
65 | The number of jobs used by `ninja` is derived from the number of CPU cores of |
66 | the building host if unspecified. Use the `-j` option to limit the job number | |
67 | if the build jobs are running out of memory. On average, each job takes around | |
68 | 2.5GiB memory.) | |
9f95a23c | 69 | |
7c673cae | 70 | This assumes you make your build dir a subdirectory of the ceph.git |
20effc67 TL |
71 | checkout. If you put it elsewhere, just point `CEPH_GIT_DIR` to the correct |
72 | path to the checkout. Any additional CMake args can be specified by setting ARGS | |
9f95a23c | 73 | before invoking do_cmake. See [cmake options](#cmake-options) |
11fdf7f2 TL |
74 | for more details. Eg. |
75 | ||
76 | ARGS="-DCMAKE_C_COMPILER=gcc-7" ./do_cmake.sh | |
7c673cae FG |
77 | |
78 | To build only certain targets use: | |
79 | ||
20effc67 | 80 | ninja [target name] |
7c673cae FG |
81 | |
82 | To install: | |
83 | ||
20effc67 | 84 | ninja install |
7c673cae FG |
85 | |
86 | ### CMake Options | |
87 | ||
88 | If you run the `cmake` command by hand, there are many options you can | |
20effc67 | 89 | set with "-D". For example, the option to build the RADOS Gateway is |
7c673cae FG |
90 | defaulted to ON. To build without the RADOS Gateway: |
91 | ||
20effc67 | 92 | cmake -DWITH_RADOSGW=OFF [path to top-level ceph directory] |
7c673cae FG |
93 | |
94 | Another example below is building with debugging and alternate locations | |
95 | for a couple of external dependencies: | |
96 | ||
f67539c2 | 97 | cmake -DLEVELDB_PREFIX="/opt/hyperleveldb" \ |
20effc67 | 98 | -DCMAKE_INSTALL_PREFIX=/opt/ceph -DCMAKE_C_FLAGS="-Og -g3 -gdwarf-4" \ |
11fdf7f2 | 99 | .. |
7c673cae FG |
100 | |
101 | To view an exhaustive list of -D options, you can invoke `cmake` with: | |
102 | ||
11fdf7f2 | 103 | cmake -LH |
7c673cae | 104 | |
20effc67 | 105 | If you often pipe `ninja` to `less` and would like to maintain the |
7c673cae FG |
106 | diagnostic colors for errors and warnings (and if your compiler |
107 | supports it), you can invoke `cmake` with: | |
108 | ||
20effc67 | 109 | cmake -DDIAGNOSTICS_COLOR=always ... |
7c673cae FG |
110 | |
111 | Then you'll get the diagnostic colors when you execute: | |
112 | ||
20effc67 | 113 | ninja | less -R |
7c673cae FG |
114 | |
115 | Other available values for 'DIAGNOSTICS_COLOR' are 'auto' (default) and | |
116 | 'never'. | |
117 | ||
118 | ||
119 | ## Building a source tarball | |
120 | ||
121 | To build a complete source tarball with everything needed to build from | |
122 | source and/or build a (deb or rpm) package, run | |
123 | ||
124 | ./make-dist | |
125 | ||
126 | This will create a tarball like ceph-$version.tar.bz2 from git. | |
127 | (Ensure that any changes you want to include in your working directory | |
128 | are committed to git.) | |
129 | ||
130 | ||
131 | ## Running a test cluster | |
132 | ||
133 | To run a functional test cluster, | |
134 | ||
135 | cd build | |
20effc67 | 136 | ninja vstart # builds just enough to run vstart |
11fdf7f2 | 137 | ../src/vstart.sh --debug --new -x --localhost --bluestore |
7c673cae FG |
138 | ./bin/ceph -s |
139 | ||
140 | Almost all of the usual commands are available in the bin/ directory. | |
141 | For example, | |
142 | ||
143 | ./bin/rados -p rbd bench 30 write | |
144 | ./bin/rbd create foo --size 1000 | |
145 | ||
146 | To shut down the test cluster, | |
147 | ||
148 | ../src/stop.sh | |
149 | ||
150 | To start or stop individual daemons, the sysvinit script can be used: | |
151 | ||
152 | ./bin/init-ceph restart osd.0 | |
153 | ./bin/init-ceph stop | |
154 | ||
155 | ||
156 | ## Running unit tests | |
157 | ||
158 | To build and run all tests (in parallel using all processors), use `ctest`: | |
159 | ||
160 | cd build | |
20effc67 | 161 | ninja |
7c673cae FG |
162 | ctest -j$(nproc) |
163 | ||
164 | (Note: Many targets built from src/test are not run using `ctest`. | |
20effc67 | 165 | Targets starting with "unittest" are run in `ninja check` and thus can |
7c673cae FG |
166 | be run with `ctest`. Targets starting with "ceph_test" can not, and should |
167 | be run by hand.) | |
168 | ||
169 | When failures occur, look in build/Testing/Temporary for logs. | |
170 | ||
171 | To build and run all tests and their dependencies without other | |
172 | unnecessary targets in Ceph: | |
173 | ||
11fdf7f2 | 174 | cd build |
20effc67 | 175 | ninja check -j$(nproc) |
7c673cae FG |
176 | |
177 | To run an individual test manually, run `ctest` with -R (regex matching): | |
178 | ||
179 | ctest -R [regex matching test name(s)] | |
180 | ||
181 | (Note: `ctest` does not build the test it's running or the dependencies needed | |
182 | to run it) | |
183 | ||
184 | To run an individual test manually and see all the tests output, run | |
185 | `ctest` with the -V (verbose) flag: | |
186 | ||
187 | ctest -V -R [regex matching test name(s)] | |
188 | ||
20effc67 | 189 | To run tests manually and run the jobs in parallel, run `ctest` with |
c07f9fc5 | 190 | the `-j` flag: |
7c673cae FG |
191 | |
192 | ctest -j [number of jobs] | |
193 | ||
194 | There are many other flags you can give `ctest` for better control | |
195 | over manual test execution. To view these options run: | |
196 | ||
197 | man ctest | |
198 | ||
199 | ||
200 | ## Building the Documentation | |
201 | ||
202 | ### Prerequisites | |
203 | ||
204 | The list of package dependencies for building the documentation can be | |
c07f9fc5 | 205 | found in `doc_deps.deb.txt`: |
7c673cae FG |
206 | |
207 | sudo apt-get install `cat doc_deps.deb.txt` | |
208 | ||
209 | ### Building the Documentation | |
210 | ||
211 | To build the documentation, ensure that you are in the top-level | |
c07f9fc5 | 212 | `/ceph` directory, and execute the build script. For example: |
7c673cae FG |
213 | |
214 | admin/build-doc | |
215 | ||
20effc67 TL |
216 | ## Reporting Issues |
217 | ||
218 | To report an issue and view existing issues, please visit https://tracker.ceph.com/projects/ceph. |