How to build and integrate ublk-cpp in your project.

Note: ublk-cpp requires condy with std::execution support. Condy uses the standard library implementation when available, or a fetched backend (stdexec or beman/execution) enabled through condy's CONDY_LINK_STDEXEC / CONDY_LINK_BEMAN options.

Using ublk-cpp as a Submodule

You can add ublk-cpp to your project via Git submodule:

git submodule add https://github.com/condy-cpp/ublk-cpp.git third_party/ublk-cpp

git submodule update --init --recursive

In your CMakeLists.txt:

add_subdirectory(third_party/ublk-cpp)
add_executable(my_app src/main.cpp)
target_link_libraries(my_app PRIVATE ublkcpp)

Using ublk-cpp via FetchContent

Alternatively, you can add ublk-cpp with FetchContent:

include(FetchContent)
FetchContent_Declare(
    ublk-cpp
    GIT_REPOSITORY https://github.com/condy-cpp/ublk-cpp.git
    GIT_TAG master  # Change to the commit/tag you want
)
FetchContent_MakeAvailable(ublk-cpp)
add_executable(my_app src/main.cpp)
target_link_libraries(my_app PRIVATE ublkcpp)

Dependencies

Condy fetches and statically links liburing by default (CONDY_LINK_LIBURING=ON). To use the liburing installed on your system instead, configure with CONDY_LINK_LIBURING=OFF.

ublk-cpp requires condy with std::execution support. When the standard library provides it, condy detects it automatically. Otherwise enable a fetched backend with CONDY_LINK_STDEXEC=ON (stdexec) or CONDY_LINK_BEMAN=ON (beman/execution).

Building

ublk-cpp provides CMake options to build tests, the ublkctl tool, examples, and the Doxygen documentation:

Option	Description	Default
UBLKCPP_BUILD_TESTS	Build tests	OFF
UBLKCPP_BUILD_UBLKCTL	Build the ublkctl tool	OFF
UBLKCPP_BUILD_EXAMPLES	Build examples	OFF
UBLKCPP_BUILD_DOCS	Build Doxygen documentation	OFF
UBLKCPP_USE_URING_CMD128	Use IORING_OP_URING_CMD128 for control commands	ON

cmake -B build -S . \
    -DUBLKCPP_BUILD_TESTS=ON \
    -DUBLKCPP_BUILD_UBLKCTL=ON \
    -DUBLKCPP_BUILD_EXAMPLES=ON \
    -DCONDY_LINK_STDEXEC=ON \
    -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

Running the Examples

The examples are ublk block device daemons and need the ublk driver loaded:

sudo modprobe ublk_drv

sudo ./build/examples/ublk-nop -n 0

Using ublkctl

ublkctl is a control tool for ublk devices. Run it with a subcommand:

sudo ./build/bin/ublkctl list    # list devices
sudo ./build/bin/ublkctl add -q 1 -d 32   # add a device
sudo ./build/bin/ublkctl del -n 0 # delete device 0

See ublkctl --help for all supported subcommands and options.