From 2a9b13bd7bcd8eeb955ef2f7aba7c2b1853d7402 Mon Sep 17 00:00:00 2001 From: Zac Dover Date: Mon, 21 Aug 2023 23:53:33 +1000 Subject: [PATCH] doc/README.md - improve "CMake Options" Add subheadings to the "CMake Options" section of ceph/README.md. Remove modal verbs when appropriate and make sentences tidier. Co-authored-by: Anthony D'Atri Signed-off-by: Zac Dover --- README.md | 43 +++++++++++++++++++++++++++---------------- 1 file changed, 27 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index cb3e949ed88fe..448648c26638a 100644 --- a/README.md +++ b/README.md @@ -111,42 +111,53 @@ To 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: +The `-D` flag can be used with `cmake` to speed up the process of building Ceph +and to customize the build. + +#### Building without RADOS Gateway + +The RADOS Gateway is built by default. To build Ceph without the RADOS Gateway, +run a command of the following form: 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: +#### Building with debugging and arbitrary dependency locations + +Run a command of the following form to build Ceph with debugging and alternate +locations for some external dependencies: cmake -DCMAKE_INSTALL_PREFIX=/opt/ceph -DCMAKE_C_FLAGS="-Og -g3 -gdwarf-4" \ .. Ceph has several bundled dependencies such as Boost, RocksDB and Arrow. By -default, cmake will build these bundled dependencies from source instead of -using libraries that are already installed on the system. You can opt-in to -using these system libraries, provided they meet the minimum version required -by Ceph, with cmake options like `WITH_SYSTEM_BOOST`: +default, `cmake` builds these bundled dependencies from source instead of using +libraries that are already installed on the system. You can opt to use these +system libraries, as long as they meet Ceph's version requirements. To use +system libraries, use `cmake` options like `WITH_SYSTEM_BOOST`, as in the +following example: cmake -DWITH_SYSTEM_BOOST=ON [...] -To view an exhaustive list of -D options, you can invoke `cmake` with: +To view an exhaustive list of -D options, invoke `cmake -LH`: cmake -LH -If you often pipe `ninja` 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: +#### Preserving diagnostic colors + +If you pipe `ninja` to `less` and would like to preserve the diagnostic colors +in the output in order to make errors and warnings more legible, run the +following command: cmake -DDIAGNOSTICS_COLOR=always ... -Then you'll get the diagnostic colors when you execute: +The above command works only with supported compilers. + +The diagnostic colors will be visible when the following command is run: ninja | less -R -Other available values for 'DIAGNOSTICS_COLOR' are 'auto' (default) and -'never'. +Other available values for `DIAGNOSTICS_COLOR` are `auto` (default) and +`never`. ## Building a source tarball -- 2.39.5