Skip to content

build.md

Latest commit

 

History

History
88 lines (64 loc) · 2.88 KB

build.md

File metadata and controls

88 lines (64 loc) · 2.88 KB
Raw

Building and Usage

@brief 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.