]>
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 |
7c673cae FG |
9 | miscellaneous code is under BSD-style license or is public domain. |
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 | |
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 | |
58 | make | |
59 | ||
11fdf7f2 TL |
60 | (Note: do_cmake.sh now defaults to creating a debug build of ceph that can |
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 |
11fdf7f2 TL |
63 | release.) |
64 | ||
9f95a23c TL |
65 | (Note: `make` alone will use only one CPU thread, this could take a while. use |
66 | the `-j` option to use more threads. Something like `make -j$(nproc)` would be | |
67 | a good start. | |
68 | ||
7c673cae | 69 | This assumes you make your build dir a subdirectory of the ceph.git |
9f95a23c TL |
70 | checkout. If you put it elsewhere, just point `CEPH_GIT_DIR`to the correct |
71 | path to the checkout. Any additional CMake args can be specified setting ARGS | |
72 | before invoking do_cmake. See [cmake options](#cmake-options) | |
11fdf7f2 TL |
73 | for more details. Eg. |
74 | ||
75 | ARGS="-DCMAKE_C_COMPILER=gcc-7" ./do_cmake.sh | |
7c673cae FG |
76 | |
77 | To build only certain targets use: | |
78 | ||
11fdf7f2 | 79 | make [target name] |
7c673cae FG |
80 | |
81 | To install: | |
82 | ||
11fdf7f2 | 83 | make install |
7c673cae FG |
84 | |
85 | ### CMake Options | |
86 | ||
87 | If you run the `cmake` command by hand, there are many options you can | |
88 | set with "-D". For example the option to build the RADOS Gateway is | |
89 | defaulted to ON. To build without the RADOS Gateway: | |
90 | ||
11fdf7f2 | 91 | cmake -DWITH_RADOSGW=OFF [path to top level ceph directory] |
7c673cae FG |
92 | |
93 | Another example below is building with debugging and alternate locations | |
94 | for a couple of external dependencies: | |
95 | ||
11fdf7f2 TL |
96 | cmake -DLEVELDB_PREFIX="/opt/hyperleveldb" -DOFED_PREFIX="/opt/ofed" \ |
97 | -DCMAKE_INSTALL_PREFIX=/opt/accelio -DCMAKE_C_FLAGS="-O0 -g3 -gdwarf-4" \ | |
98 | .. | |
7c673cae FG |
99 | |
100 | To view an exhaustive list of -D options, you can invoke `cmake` with: | |
101 | ||
11fdf7f2 | 102 | cmake -LH |
7c673cae FG |
103 | |
104 | If you often pipe `make` to `less` and would like to maintain the | |
105 | diagnostic colors for errors and warnings (and if your compiler | |
106 | supports it), you can invoke `cmake` with: | |
107 | ||
11fdf7f2 | 108 | cmake -DDIAGNOSTICS_COLOR=always .. |
7c673cae FG |
109 | |
110 | Then you'll get the diagnostic colors when you execute: | |
111 | ||
11fdf7f2 | 112 | make | less -R |
7c673cae FG |
113 | |
114 | Other available values for 'DIAGNOSTICS_COLOR' are 'auto' (default) and | |
115 | 'never'. | |
116 | ||
117 | ||
118 | ## Building a source tarball | |
119 | ||
120 | To build a complete source tarball with everything needed to build from | |
121 | source and/or build a (deb or rpm) package, run | |
122 | ||
123 | ./make-dist | |
124 | ||
125 | This will create a tarball like ceph-$version.tar.bz2 from git. | |
126 | (Ensure that any changes you want to include in your working directory | |
127 | are committed to git.) | |
128 | ||
129 | ||
130 | ## Running a test cluster | |
131 | ||
132 | To run a functional test cluster, | |
133 | ||
134 | cd build | |
135 | make vstart # builds just enough to run vstart | |
11fdf7f2 | 136 | ../src/vstart.sh --debug --new -x --localhost --bluestore |
7c673cae FG |
137 | ./bin/ceph -s |
138 | ||
139 | Almost all of the usual commands are available in the bin/ directory. | |
140 | For example, | |
141 | ||
142 | ./bin/rados -p rbd bench 30 write | |
143 | ./bin/rbd create foo --size 1000 | |
144 | ||
145 | To shut down the test cluster, | |
146 | ||
147 | ../src/stop.sh | |
148 | ||
149 | To start or stop individual daemons, the sysvinit script can be used: | |
150 | ||
151 | ./bin/init-ceph restart osd.0 | |
152 | ./bin/init-ceph stop | |
153 | ||
154 | ||
155 | ## Running unit tests | |
156 | ||
157 | To build and run all tests (in parallel using all processors), use `ctest`: | |
158 | ||
159 | cd build | |
160 | make | |
161 | ctest -j$(nproc) | |
162 | ||
163 | (Note: Many targets built from src/test are not run using `ctest`. | |
164 | Targets starting with "unittest" are run in `make check` and thus can | |
165 | be run with `ctest`. Targets starting with "ceph_test" can not, and should | |
166 | be run by hand.) | |
167 | ||
168 | When failures occur, look in build/Testing/Temporary for logs. | |
169 | ||
170 | To build and run all tests and their dependencies without other | |
171 | unnecessary targets in Ceph: | |
172 | ||
11fdf7f2 TL |
173 | cd build |
174 | make check -j$(nproc) | |
7c673cae FG |
175 | |
176 | To run an individual test manually, run `ctest` with -R (regex matching): | |
177 | ||
178 | ctest -R [regex matching test name(s)] | |
179 | ||
180 | (Note: `ctest` does not build the test it's running or the dependencies needed | |
181 | to run it) | |
182 | ||
183 | To run an individual test manually and see all the tests output, run | |
184 | `ctest` with the -V (verbose) flag: | |
185 | ||
186 | ctest -V -R [regex matching test name(s)] | |
187 | ||
188 | To run an tests manually and run the jobs in parallel, run `ctest` with | |
c07f9fc5 | 189 | the `-j` flag: |
7c673cae FG |
190 | |
191 | ctest -j [number of jobs] | |
192 | ||
193 | There are many other flags you can give `ctest` for better control | |
194 | over manual test execution. To view these options run: | |
195 | ||
196 | man ctest | |
197 | ||
198 | ||
199 | ## Building the Documentation | |
200 | ||
201 | ### Prerequisites | |
202 | ||
203 | The list of package dependencies for building the documentation can be | |
c07f9fc5 | 204 | found in `doc_deps.deb.txt`: |
7c673cae FG |
205 | |
206 | sudo apt-get install `cat doc_deps.deb.txt` | |
207 | ||
208 | ### Building the Documentation | |
209 | ||
210 | To build the documentation, ensure that you are in the top-level | |
c07f9fc5 | 211 | `/ceph` directory, and execute the build script. For example: |
7c673cae FG |
212 | |
213 | admin/build-doc | |
214 |