Skip to content

Latest commit

 

History

History
195 lines (128 loc) · 4 KB

HACKING.md

File metadata and controls

195 lines (128 loc) · 4 KB
Raw

Developing and using Seastar

Configuring the project

There are multiple ways to configure Seastar and its dependencies.

Use system-packages for most dependencies

See the instructions in README.md.

Download and install all external dependencies in a project-specific location

  • 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_:
./cooking.sh
  • The same as above, and enable DPDK support:
./cooking.sh -- -DSeastar_DPDK=ON
  • Use system packages for all dependencies except dpdk, which is provided by cmake-cooking (and not yet widely available via system package-managers):
./cooking.sh -i dpdk
  • Use cmake-cooking for all dependencies except for Boost:
./cooking.sh -e Boost
  • The same, but compile in "release" mode:
./cooking.sh -e Boost -t Release

Using an IDE with CMake support

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:

-DCMAKE_PREFIX_PATH=${source_dir}/build/_cooking/installed

where ${source_dir} is the root of the Seastar source tree on your file-system.

This will allow the IDE to also index Seastar's dependencies.

Building the project

cd $my_build_dir
ninja

If you used configure.py to configure Seastar, then the build directory will be build/$mode. For example, build/release.

If you use cooking.sh, then the build directory will just be build.

Running tests

Make sure you are in the "build" directory.

  • Run unit tests:
ninja test_unit
  • Run distribution tests (these take a long time the first time, but then the dependencies are cached):
ninja test_dist
  • Run all tests:
ninja test
  • Build and run a specific test:
ninja test_unit_thread_run

Building documentation

Make sure you are in the "build" directory.

  • Build all documentation:
ninja docs
  • Build the tutorial in HTML form:
ninja doc_tutorial_html
  • Build the tutorial in HTML form (one file per chapter):
ninja doc_tutorial_html_split
  • Build the Doxygen documentation:
ninja doc_api

Installing the project

Choose the install path:

With configure.py:

./configure.py --mode=release --prefix=/my/install/path

With cooking.sh:

./cooking.sh -- -DCMAKE_INSTALL_PREFIX=/my/install/path

ninja -C build install

Using Seastar in an application

CMake

Once Seastar has been installed, it is sufficient to add a dependency on Seastar with

find_package (Seastar ${VERSION} REQUIRED)

add_executable (my_program
  my_program.cc)
  
target_link_libraries (my_program
  PRIVATE Seastar::seastar)

where VERSION is the desired version.

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:

cooking_ingredient (Seastar
  COOKING_RECIPE <DEFAULT>
  COOKING_CMAKE_ARGS
    -DSeastar_APPS=OFF
    -DSeastar_DEMOS=OFF
    -DSeastar_DOCS=OFF
    -DSeastar_TESTING=OFF
  EXTERNAL_PROJECT_ARGS
    SOURCE_DIR ${MY_SEASTAR_SOURCE_DIR})

pkg-config

Seastar includes a seastar.pc file. It can be used from both the install and build directories.

Compiling a single file:

g++ foo.cc -o foo $(pkg-config --libs --cflags --static /path/to/seastar.pc)

Compiling multiple files:

// Compiling sources into object files
g++ -c $(pkg-config --cflags /path/to/seastar.pc)` foo.cc -o foo.o
g++ -c $(pkg-config --cflags /path/to/seastar.pc)` bar.cc -o bar.o

// Linking object files into an executable
g++ -o foo_bar foo.o bar.o $(pkg-config --libs --static /path/to/seastar.pc)

The --static flag is needed to include transitive (private) dependencies of libseastar.a.