Skip to content

Commit 3e6cf35

Browse files
wokronwokron
committed
add docs
1 parent 8ec3cb2 commit 3e6cf35

8 files changed

Lines changed: 3542 additions & 2 deletions

File tree

‎.github/workflows/deploy-docs.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches: [ "master" ]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-26.04
20+
timeout-minutes: 15
21+
22+
steps:
23+
- name: Checkout Repository
24+
uses: actions/checkout@v4
25+
with:
26+
submodules: recursive
27+
28+
- name: Install Doxygen
29+
run: |
30+
sudo apt-get update
31+
sudo apt-get install -y doxygen
32+
33+
- name: Setup Pages
34+
id: pages
35+
uses: actions/configure-pages@v5
36+
37+
- name: Configure CMake
38+
run: cmake -B build -DUBLKCPP_BUILD_DOCS=ON
39+
40+
- name: Build Documentation
41+
run: cmake --build build --target docs
42+
43+
- name: Upload artifact
44+
uses: actions/upload-pages-artifact@v3
45+
with:
46+
path: ./build/docs/html
47+
48+
deploy:
49+
needs: build
50+
runs-on: ubuntu-26.04
51+
environment:
52+
name: github-pages
53+
url: ${{ steps.deployment.outputs.page_url }}
54+
steps:
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@v4

‎CMakeLists.txt‎

Lines changed: 37 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,33 @@
11
cmake_minimum_required(VERSION 3.13)
22

3-
project(ublkcpp LANGUAGES CXX)
3+
# Version is defined once in the version header.
4+
set(UBLKCPP_VERSION_HEADER include/ublk/version.hpp)
5+
file(READ ${UBLKCPP_VERSION_HEADER} _ublkcpp_version_h)
6+
string(REGEX MATCH "#define UBLKCPP_VERSION_MAJOR ([0-9]+)" _ublkcpp_ver_m "${_ublkcpp_version_h}")
7+
set(UBLKCPP_VERSION_MAJOR ${CMAKE_MATCH_1})
8+
string(REGEX MATCH "#define UBLKCPP_VERSION_MINOR ([0-9]+)" _ublkcpp_ver_m "${_ublkcpp_version_h}")
9+
set(UBLKCPP_VERSION_MINOR ${CMAKE_MATCH_1})
10+
set(UBLKCPP_VERSION_STRING "v${UBLKCPP_VERSION_MAJOR}.${UBLKCPP_VERSION_MINOR}")
11+
12+
project(ublkcpp VERSION ${UBLKCPP_VERSION_MAJOR}.${UBLKCPP_VERSION_MINOR} LANGUAGES CXX)
13+
message(STATUS "Configuring ublkcpp ${UBLKCPP_VERSION_STRING}")
414

515
option(UBLKCPP_BUILD_TESTS "Build tests" OFF)
616
option(UBLKCPP_BUILD_UBLKCTL "Build ublkctl" OFF)
717
option(UBLKCPP_BUILD_EXAMPLES "Build examples" OFF)
18+
option(UBLKCPP_BUILD_DOCS "Build Doxygen documentation" OFF)
819
option(UBLKCPP_USE_URING_CMD128 "Use IORING_OP_URING_CMD128 for control commands" ON)
920
option(UBLKCPP_TESTS_STATIC_LINK "Use static linking for tests" OFF)
1021
option(UBLKCPP_TESTS_ASAN "Enable address and undefined behavior sanitizers for tests" OFF)
1122
option(UBLKCPP_TESTS_TSAN "Enable thread sanitizer for tests" OFF)
23+
set(UBLKCPP_EXECUTION_BACKEND "stdexec" CACHE STRING
24+
"std::execution implementation used via Condy: stdexec (default) or beman")
1225

1326
include(FetchContent)
1427

1528
set(DOCTEST_VERSION v2.5.0)
1629
set(CLI11_VERSION v2.7.2)
30+
set(DOXYGEN_AWESOME_CSS_VERSION v2.4.1)
1731

1832
FetchContent_Declare(
1933
doctest
@@ -25,6 +39,11 @@ FetchContent_Declare(
2539
URL https://github.com/CLIUtils/CLI11/releases/download/${CLI11_VERSION}/CLI11.hpp
2640
DOWNLOAD_NO_EXTRACT TRUE
2741
)
42+
FetchContent_Declare(
43+
doxygen-awesome-css
44+
URL https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/${DOXYGEN_AWESOME_CSS_VERSION}/doxygen-awesome.css
45+
DOWNLOAD_NO_EXTRACT TRUE
46+
)
2847

2948
add_library(ublkcpp INTERFACE)
3049
target_include_directories(ublkcpp INTERFACE include)
@@ -33,7 +52,18 @@ if(UBLKCPP_USE_URING_CMD128)
3352
target_compile_definitions(ublkcpp INTERFACE UBLKCPP_USE_URING_CMD128)
3453
endif()
3554

36-
set(CONDY_ENABLE_STDEXEC ON)
55+
if(UBLKCPP_EXECUTION_BACKEND STREQUAL "beman")
56+
set(CONDY_ENABLE_STDEXEC OFF)
57+
set(CONDY_ENABLE_BEMAN ON)
58+
elseif(UBLKCPP_EXECUTION_BACKEND STREQUAL "stdexec")
59+
set(CONDY_ENABLE_STDEXEC ON)
60+
set(CONDY_ENABLE_BEMAN OFF)
61+
else()
62+
message(FATAL_ERROR
63+
"UBLKCPP_EXECUTION_BACKEND must be 'stdexec' or 'beman', got '"
64+
"${UBLKCPP_EXECUTION_BACKEND}'")
65+
endif()
66+
message(STATUS "ublkcpp: execution backend: ${UBLKCPP_EXECUTION_BACKEND}")
3767
add_subdirectory(third_party/condy)
3868
target_link_libraries(ublkcpp INTERFACE condy)
3969

@@ -52,3 +82,8 @@ if(UBLKCPP_BUILD_EXAMPLES)
5282
message(STATUS "Configuring examples in ${CMAKE_CURRENT_SOURCE_DIR}/examples")
5383
add_subdirectory(examples)
5484
endif()
85+
86+
if(UBLKCPP_BUILD_DOCS)
87+
message(STATUS "Configuring docs in ${CMAKE_CURRENT_SOURCE_DIR}/docs")
88+
add_subdirectory(docs)
89+
endif()

‎README.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,38 @@
11
# ublk-cpp
2+
3+
![C++](https://img.shields.io/badge/C++-26-blue)
4+
![License](https://img.shields.io/github/license/condy-cpp/ublk-cpp)
5+
![Release](https://img.shields.io/github/v/release/condy-cpp/ublk-cpp)
6+
![Stars](https://img.shields.io/github/stars/condy-cpp/ublk-cpp?style=social)
7+
8+
![CI (Main)](https://github.com/condy-cpp/ublk-cpp/actions/workflows/ci-main.yml/badge.svg?branch=master)
9+
![CI (Latest Kernel)](https://github.com/condy-cpp/ublk-cpp/actions/workflows/ci-latest-kernel.yml/badge.svg?branch=master)
10+
![CI (Static Check)](https://github.com/condy-cpp/ublk-cpp/actions/workflows/ci-static-check.yml/badge.svg?branch=master)
11+
![Deploy Docs](https://github.com/condy-cpp/ublk-cpp/actions/workflows/deploy-docs.yml/badge.svg?branch=master)
12+
13+
ublk-cpp is a C++ library for writing [ublk servers](https://docs.kernel.org/block/ublk.html), targeting the C++26 `std::execution` sender model:
14+
15+
- **Comprehensive ublk Support**
16+
Full coverage of the ublk userspace interface — device lifecycle management, per-queue I/O loops, and advanced features such as user recovery and shm buffer registration.
17+
18+
- **Full io_uring Ecosystem**
19+
Built on top of [Condy](https://github.com/condy-cpp/condy), all io_uring operations can be used directly inside your ublk server.
20+
21+
- **C++26 Sender Model**
22+
The API is built on `std::execution` senders — composable with standard algorithms and interoperable with any asynchronous driver.
23+
24+
> [!NOTE]
25+
> This repository is experimental and will not reach a stable state until
26+
> `std::execution` (C++26) is finalized.
27+
28+
## Documentation
29+
30+
- **[Online Docs (GitHub Pages)](https://condy-cpp.github.io/ublk-cpp/)**
31+
- **[User Guide](docs/guide.md):** Step-by-step introduction to ublk-cpp's concepts and usage.
32+
- **[Building and Usage](docs/build.md):** How to build and integrate ublk-cpp in your project.
33+
- **[Examples](docs/examples.md):** Practical ublk-cpp code samples.
34+
35+
## Support
36+
37+
- For questions, bug reports, or feature requests, please open an [issue](https://github.com/condy-cpp/ublk-cpp/issues).
38+
- [Pull requests](https://github.com/condy-cpp/ublk-cpp/pulls) are welcome!

‎docs/CMakeLists.txt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
find_program(DOXYGEN_EXECUTABLE NAMES doxygen REQUIRED)
2+
3+
message(STATUS "Fetching doxygen-awesome-css")
4+
FetchContent_MakeAvailable(doxygen-awesome-css)
5+
FetchContent_GetProperties(doxygen-awesome-css SOURCE_DIR AWESOME_CSS_DIR)
6+
7+
set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
8+
set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
9+
configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
10+
11+
add_custom_target(docs
12+
COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYFILE_OUT}
13+
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
14+
COMMENT "Generate Doxygen documentation into ${CMAKE_CURRENT_BINARY_DIR}/html"
15+
VERBATIM)

0 commit comments

Comments
 (0)