ceph/src/seastar/HACKING.md

   1 # Developing and using Seastar
   2
   3 ## Configuring the project
   4
   5 There are multiple ways to configure Seastar and its dependencies.
   6
   7 ### Use system-packages for most dependencies
   8
   9 See the instructions in [README.md](./README.md).
  10
  11 ### Download and install all external dependencies in a project-specific location
  12
  13 - Use `cmake-cooking` to prepare a development environment with all dependencies.  This allows for reproducible development environments, but means that approximately 3 GiB of dependencies get installed to `build/_cooking_`:
  14
  15 ```
  16 ./cooking.sh
  17 ```
  18
  19 - The same as above, and enable DPDK support:
  20
  21 ```
  22 ./cooking.sh -- -DSeastar_DPDK=ON
  23 ```
  24
  25 - Use system packages for all dependencies except `dpdk`, which is provided by `cmake-cooking` (and not yet widely available via system package-managers):
  26
  27 ```
  28 ./cooking.sh -i dpdk
  29 ```
  30
  31 - Use `cmake-cooking` for all dependencies except for Boost:
  32
  33 ```
  34 ./cooking.sh -e Boost
  35 ```
  36
  37 - The same, but compile in "release" mode:
  38
  39 ```
  40 ./cooking.sh -e Boost -t Release
  41 ```
  42
  43 ## Using an IDE with CMake support
  44
  45 If you use `configure.py` or `cooking.sh` to to configure Seastar, then the easiest way to use an IDE (such as Qt Creator, or CLion) for development is to instruct the IDE, when it invokes CMake, to include the following option:
  46
  47 ```
  48 -DCMAKE_PREFIX_PATH=${source_dir}/build/_cooking/installed
  49 ```
  50
  51 where `${source_dir}` is the root of the Seastar source tree on your file-system.
  52
  53 This will allow the IDE to also index Seastar's dependencies.
  54
  55 ## Building the project
  56
  57 ```
  58 cd $my_build_dir
  59 ninja
  60 ```
  61
  62 If you used `configure.py` to configure Seastar, then the build directory will be `build/$mode`. For example, `build/release`.
  63
  64 If you use `cooking.sh`, then the build directory will just be `build`.
  65
  66 ## Running tests
  67
  68 Make sure you are in the "build" directory.
  69
  70 - Run unit tests:
  71
  72 ```
  73 ninja test_unit
  74 ```
  75
  76 - Run distribution tests (these take a long time the first time, but then the dependencies are cached):
  77
  78 ```
  79 ninja test_dist
  80 ```
  81
  82 - Run all tests:
  83
  84 ```
  85 ninja test
  86 ```
  87
  88 - Build and run a specific test:
  89
  90 ```
  91 ninja test_unit_thread_run
  92 ```
  93
  94
  95 ## Building documentation
  96
  97 Make sure you are in the "build" directory.
  98
  99 - Build all documentation:
 100
 101 ```
 102 ninja docs
 103 ```
 104
 105 - Build the tutorial in HTML form:
 106
 107 ```
 108 ninja doc_tutorial_html
 109 ```
 110
 111 - Build the tutorial in HTML form (one file per chapter):
 112
 113 ```
 114 ninja doc_tutorial_html_split
 115 ```
 116
 117 - Build the Doxygen documentation:
 118
 119 ```
 120 ninja doc_api
 121 ```
 122
 123 ## Installing the project
 124
 125 Choose the install path:
 126
 127 With `configure.py`:
 128
 129 ```
 130 ./configure.py --mode=release --prefix=/my/install/path
 131 ```
 132
 133 With `cooking.sh`:
 134
 135 ```
 136 ./cooking.sh -- -DCMAKE_INSTALL_PREFIX=/my/install/path
 137 ```
 138
 139 ```
 140 ninja -C build install
 141 ```
 142
 143 ## Using Seastar in an application
 144
 145 ### CMake
 146
 147 Once Seastar has been installed, it is sufficient to add a dependency on Seastar with
 148
 149 ```
 150 find_package (Seastar ${VERSION} REQUIRED)
 151
 152 add_executable (my_program
 153   my_program.cc)
 154
 155 target_link_libraries (my_program
 156   PRIVATE Seastar::seastar)
 157 ```
 158
 159 where `VERSION` is the desired version.
 160
 161 If you'd like to use `cmake-cooking` to set up a development environment which includes Seastar and its dependencies (a "recipe"), you can include Seastar as follows:
 162
 163 ```
 164 cooking_ingredient (Seastar
 165   COOKING_RECIPE <DEFAULT>
 166   COOKING_CMAKE_ARGS
 167     -DSeastar_APPS=OFF
 168     -DSeastar_DEMOS=OFF
 169     -DSeastar_DOCS=OFF
 170     -DSeastar_TESTING=OFF
 171   EXTERNAL_PROJECT_ARGS
 172     SOURCE_DIR ${MY_SEASTAR_SOURCE_DIR})
 173 ```
 174
 175 ### pkg-config
 176
 177 Seastar includes a `seastar.pc` file. It can be used from both the
 178 install and build directories.
 179
 180 Compiling a single file:
 181 ```
 182 g++ foo.cc -o foo $(pkg-config --libs --cflags --static /path/to/seastar.pc)
 183 ```
 184
 185 Compiling multiple files:
 186 ```
 187 // Compiling sources into object files
 188 g++ -c $(pkg-config --cflags /path/to/seastar.pc)` foo.cc -o foo.o
 189 g++ -c $(pkg-config --cflags /path/to/seastar.pc)` bar.cc -o bar.o
 190
 191 // Linking object files into an executable
 192 g++ -o foo_bar foo.o bar.o $(pkg-config --libs --static /path/to/seastar.pc)
 193 ```
 194
 195 The `--static` flag is needed to include transitive (private) dependencies of `libseastar.a`.