2012-03-14 18:58:27 +00:00
|
|
|
============================================
|
2011-09-07 17:23:39 +00:00
|
|
|
Ceph - a scalable distributed storage system
|
2012-04-11 19:33:57 +00:00
|
|
|
============================================
|
2007-03-15 23:23:52 +00:00
|
|
|
|
2012-06-16 21:50:29 +00:00
|
|
|
Please see http://ceph.com/ for current info.
|
2008-02-01 17:59:44 +00:00
|
|
|
|
2016-06-22 18:13:28 +00:00
|
|
|
|
2012-04-11 19:33:57 +00:00
|
|
|
Contributing Code
|
2012-03-14 18:58:27 +00:00
|
|
|
=================
|
2012-04-11 19:33:57 +00:00
|
|
|
|
|
|
|
Most of Ceph is licensed under the LGPL version 2.1. Some
|
|
|
|
miscellaneous code is under BSD-style license or is public domain.
|
|
|
|
The documentation is licensed under Creative Commons
|
|
|
|
Attribution-ShareAlike (CC BY-SA). There are a handful of headers
|
|
|
|
included here that are licensed under the GPL. Please see the file
|
|
|
|
COPYING for a full inventory of licenses by file.
|
|
|
|
|
|
|
|
Code contributions must include a valid "Signed-off-by" acknowledging
|
|
|
|
the license for the modified or contributed file. Please see the file
|
2016-01-20 05:28:36 +00:00
|
|
|
SubmittingPatches.rst for details on what that means and on how to
|
2012-04-11 19:33:57 +00:00
|
|
|
generate and submit patches.
|
|
|
|
|
|
|
|
We do not require assignment of copyright to contribute code; code is
|
|
|
|
contributed under the terms of the applicable license.
|
|
|
|
|
|
|
|
|
2016-06-16 17:44:35 +00:00
|
|
|
Checking out the source
|
|
|
|
=======================
|
|
|
|
|
|
|
|
You can clone from github with
|
|
|
|
|
2016-06-27 18:03:11 +00:00
|
|
|
git clone git@github.com:ceph/ceph
|
2016-06-16 17:44:35 +00:00
|
|
|
|
|
|
|
or, if you are not a github user,
|
|
|
|
|
2016-06-27 18:03:11 +00:00
|
|
|
git clone git://github.com/ceph/ceph
|
2016-06-16 17:44:35 +00:00
|
|
|
|
|
|
|
Ceph contains many git submodules that need to be checked out with
|
|
|
|
|
2016-06-27 18:03:11 +00:00
|
|
|
git submodule update --init --recursive
|
2016-06-16 17:44:35 +00:00
|
|
|
|
|
|
|
|
2014-08-05 18:48:38 +00:00
|
|
|
Build Prerequisites
|
|
|
|
===================
|
|
|
|
|
2015-06-03 21:25:23 +00:00
|
|
|
The list of Debian or RPM packages dependencies can be installed with:
|
2014-08-05 18:48:38 +00:00
|
|
|
|
2014-11-25 16:25:26 +00:00
|
|
|
./install-deps.sh
|
2014-08-05 18:48:38 +00:00
|
|
|
|
|
|
|
|
2012-04-11 19:33:57 +00:00
|
|
|
Building Ceph
|
2012-03-14 18:58:27 +00:00
|
|
|
=============
|
2012-04-05 18:43:11 +00:00
|
|
|
|
2016-06-23 13:28:09 +00:00
|
|
|
Note that these instructions are meant for developers who are
|
|
|
|
compiling the code for development and testing. To build binaries
|
|
|
|
suitable for installation we recommend you build deb or rpm packages,
|
|
|
|
or refer to the ceph.spec.in or debian/rules to see which
|
|
|
|
configuration options are specified for production builds.
|
2015-08-04 16:45:52 +00:00
|
|
|
|
2016-06-27 18:03:11 +00:00
|
|
|
Prerequisite: CMake 2.8.11
|
2015-08-04 16:45:52 +00:00
|
|
|
|
|
|
|
Build instructions:
|
|
|
|
|
2016-06-27 18:03:11 +00:00
|
|
|
./do_cmake.sh
|
2015-08-04 16:45:52 +00:00
|
|
|
cd build
|
|
|
|
make
|
|
|
|
|
2016-06-16 17:47:12 +00:00
|
|
|
This assumes you make your build dir a subdirectory of the ceph.git
|
2016-06-29 20:05:26 +00:00
|
|
|
checkout. If you put it elsewhere, just replace .. above with a
|
2016-06-16 17:47:12 +00:00
|
|
|
correct path to the checkout.
|
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
To build only certain targets use:
|
|
|
|
|
|
|
|
make [target name]
|
|
|
|
|
|
|
|
To install:
|
|
|
|
|
|
|
|
make install
|
|
|
|
|
|
|
|
CMake Options
|
|
|
|
-------------
|
|
|
|
|
|
|
|
If you run the `cmake` command by hand, there are many options you can
|
|
|
|
set with "-D". For example the option to build the RADOS Gateway is
|
|
|
|
defaulted to ON. To build without the RADOS Gateway:
|
|
|
|
|
|
|
|
cmake -DWITH_RADOSGW=OFF [path to top level ceph directory]
|
|
|
|
|
|
|
|
Another example below is building with debugging and alternate locations
|
|
|
|
for a couple of external dependencies:
|
|
|
|
|
|
|
|
cmake -DLEVELDB_PREFIX="/opt/hyperleveldb" -DOFED_PREFIX="/opt/ofed" \
|
|
|
|
-DCMAKE_INSTALL_PREFIX=/opt/accelio -DCMAKE_C_FLAGS="-O0 -g3 -gdwarf-4" \
|
|
|
|
..
|
|
|
|
|
|
|
|
To view an exhaustive list of -D options, you can invoke `cmake` with:
|
|
|
|
|
|
|
|
cmake -LH
|
|
|
|
|
|
|
|
If you often pipe `make` to `less` and would like to maintain the
|
|
|
|
diagnostic colors for errors and warnings (and if your compiler
|
|
|
|
supports it), you can invoke `cmake` with:
|
|
|
|
|
|
|
|
cmake -DDIAGNOSTICS_COLOR=always ..
|
|
|
|
|
|
|
|
Then you'll get the diagnostic colors when you execute:
|
|
|
|
|
|
|
|
make | less -R
|
|
|
|
|
|
|
|
Other available values for 'DIAGNOSTICS_COLOR' are 'auto' (default) and
|
|
|
|
'never'.
|
|
|
|
|
2015-08-04 16:45:52 +00:00
|
|
|
|
2016-08-23 18:22:21 +00:00
|
|
|
Building a source tarball
|
|
|
|
=========================
|
2012-04-11 19:33:57 +00:00
|
|
|
|
2016-08-23 18:22:21 +00:00
|
|
|
To build a complete source tarball with everything needed to build from
|
|
|
|
source and/or build a (deb or rpm) package, run
|
2008-03-18 16:31:04 +00:00
|
|
|
|
2016-08-23 18:22:21 +00:00
|
|
|
./make-dist
|
2008-03-18 16:31:04 +00:00
|
|
|
|
2016-08-23 18:22:21 +00:00
|
|
|
This will create a tarball like ceph-$version.tar.bz2 from git.
|
|
|
|
(Ensure that any changes you want to include in your working directory
|
|
|
|
are committed to git.)
|
2012-03-14 18:58:27 +00:00
|
|
|
|
2016-06-16 17:55:11 +00:00
|
|
|
|
|
|
|
Running a test cluster
|
|
|
|
======================
|
|
|
|
|
2016-06-20 19:15:09 +00:00
|
|
|
To run a functional test cluster,
|
|
|
|
|
|
|
|
cd build
|
2016-06-27 18:16:23 +00:00
|
|
|
make vstart # builds just enough to run vstart
|
2016-06-22 18:13:28 +00:00
|
|
|
../src/vstart.sh -d -n -x -l
|
2016-06-20 19:15:09 +00:00
|
|
|
./bin/ceph -s
|
|
|
|
|
|
|
|
Almost all of the usual commands are available in the bin/ directory.
|
|
|
|
For example,
|
|
|
|
|
|
|
|
./bin/rados -p rbd bench 30 write
|
|
|
|
./bin/rbd create foo --size 1000
|
2016-06-16 17:55:11 +00:00
|
|
|
|
2016-06-20 19:15:09 +00:00
|
|
|
To shut down the test cluster,
|
|
|
|
|
2016-06-22 18:13:28 +00:00
|
|
|
../src/stop.sh
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-22 18:13:28 +00:00
|
|
|
To start or stop individual daemons, the sysvinit script can be used:
|
2016-06-20 19:15:09 +00:00
|
|
|
|
|
|
|
./bin/init-ceph restart osd.0
|
|
|
|
./bin/init-ceph stop
|
2016-06-16 17:55:11 +00:00
|
|
|
|
2016-06-22 18:13:28 +00:00
|
|
|
|
2016-06-15 20:54:53 +00:00
|
|
|
Running unit tests
|
|
|
|
==================
|
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
To build and run all tests (in parallel using all processors), use `ctest`:
|
2016-06-20 19:15:09 +00:00
|
|
|
|
|
|
|
cd build
|
2016-06-27 18:16:23 +00:00
|
|
|
make
|
2016-06-22 18:13:28 +00:00
|
|
|
ctest -j$(nproc)
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
(Note: Many targets built from src/test are not run using `ctest`.
|
|
|
|
Targets starting with "unittest" are run in `make check` and thus can
|
|
|
|
be run with `ctest`. Targets starting with "ceph_test" can not, and should
|
|
|
|
be run by hand.)
|
|
|
|
|
2016-11-10 22:43:41 +00:00
|
|
|
When failures occur, look in build/Testing/Temporary for logs.
|
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
To build and run all tests and their dependencies without other
|
|
|
|
unnecessary targets in Ceph:
|
|
|
|
|
|
|
|
cd build
|
|
|
|
make check -j$(nproc)
|
|
|
|
|
|
|
|
To run an individual test manually, run `ctest` with -R (regex matching):
|
|
|
|
|
|
|
|
ctest -R [regex matching test name(s)]
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
(Note: `ctest` does not build the test it's running or the dependencies needed
|
|
|
|
to run it)
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-22 18:13:28 +00:00
|
|
|
To run an individual test manually and see all the tests output, run
|
2016-06-29 20:05:26 +00:00
|
|
|
`ctest` with the -V (verbose) flag:
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
ctest -V -R [regex matching test name(s)]
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
To run an tests manually and run the jobs in parallel, run `ctest` with
|
|
|
|
the -j flag:
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-27 18:03:11 +00:00
|
|
|
ctest -j [number of jobs]
|
2016-06-20 19:15:09 +00:00
|
|
|
|
2016-06-29 20:05:26 +00:00
|
|
|
There are many other flags you can give `ctest` for better control
|
2016-06-20 19:15:09 +00:00
|
|
|
over manual test execution. To view these options run:
|
2016-06-15 20:54:53 +00:00
|
|
|
|
2016-06-27 18:03:11 +00:00
|
|
|
man ctest
|
2016-06-16 17:55:11 +00:00
|
|
|
|
2016-06-22 18:13:28 +00:00
|
|
|
|
2012-03-14 18:58:27 +00:00
|
|
|
Building the Documentation
|
|
|
|
==========================
|
|
|
|
|
|
|
|
Prerequisites
|
|
|
|
-------------
|
|
|
|
|
2014-08-06 15:16:21 +00:00
|
|
|
The list of package dependencies for building the documentation can be
|
|
|
|
found in doc_deps.deb.txt:
|
2012-03-14 18:58:27 +00:00
|
|
|
|
2014-05-21 04:56:05 +00:00
|
|
|
sudo apt-get install `cat doc_deps.deb.txt`
|
2012-03-14 18:58:27 +00:00
|
|
|
|
|
|
|
Building the Documentation
|
|
|
|
--------------------------
|
|
|
|
|
2014-08-06 15:16:21 +00:00
|
|
|
To build the documentation, ensure that you are in the top-level
|
|
|
|
`/ceph directory, and execute the build script. For example:
|
2012-03-14 18:58:27 +00:00
|
|
|
|
2014-05-21 04:56:05 +00:00
|
|
|
admin/build-doc
|
2013-11-26 15:14:22 +00:00
|
|
|
|