README.zh_CN.md

Sese Framework

简介

这是一个跨平台的、用于基础组件开发的框架，一定程度上作为标准库的补充使用。定位上类似于 Boost、folly 之于标准库。项目使用 C++ 17 标准，引入了 vcpkg 作为包管理器帮助我们简化依赖项管理问题。

示例

内建日志器

#include <sese/record/Marco.h>
// ...
SESE_INFO("hello world");
SESE_WARN("error %s", err.what().c_str());

2024-05-15T15:54:48.296Z I main.cpp:8 Main:7116> hello world
2024-05-15T15:54:48.296Z W main.cpp:9 Main:7116> error End of file

---

HTTP 控制器

#include <sese/service/http/HttpServer_V3.h>
// ...
SESE_CTRL(MyController, std::mutex mutex{}; int times = 0) {
    SESE_INFO("LOADING MyController");
    SESE_URL(timers, RequestType::GET, "/times") {
        sese::Locker locker(mutex);
        times += 1;
        auto message = "timers = '" + std::to_string(this->times) + "'\n";
        resp.getBody().write(message.data(), message.length());
    };
    SESE_URL(say, RequestType::GET, "/say?<say>") {
        auto words = req.get("say");
        auto message = "you say '" + words + "'\n";
        resp.getBody().write(message.data(), message.length());
    };
    SESE_INFO("LOADED");
}

---

跨进程通讯

#include <sese/system/IPC.h>
#include <sese/record/Marco.h>
// ···
// server
auto channel = sese::system::IPCChannel::create("Test", 1024);
    while (true) {
        auto messages = channel->read(1);
        if (messages.empty()) {
            sese::sleep(1s);
            continue;
        }
        for (auto &&msg: messages) {
            SESE_INFO("recv %s", msg.getDataAsString().c_str());

            if (msg.getDataAsString() == "Exit") {
                goto end;
            }
        }
    }
end:
    return 0;
// ···
// client
auto channel = sese::system::IPCChannel::use("Test");
channel->write(1, "Hello");
channel->write(2, "Hi");
channel->write(1, "Exit");

构建

对于开发者/贡献者

1. 配置开发环境

对于 Windows 用户，请安装并配置 vcpkg 到目标机器上。

对于非 Windows 用户，vcpkg 同样是可用的。但同时你可以选择使用原生的系统依赖管理工具安装相应依赖。我们提供了几个预设的安装脚本。

• Ubuntu

sudo ./scripts/install_ubuntu_deps.sh

• Fedora

sudo ./scripts/install_fedora_deps.sh

• macOS

./scripts/install_darwin_deps.sh

2. 编译选项

如果你配置好了 vcpkg，只需设置工具链文件 即可完成依赖配置。

如果你使用系统依赖管理工具，那么你需要在按完成对应依赖后，手动添加 SESE_USE_NATIVE_MANAGER 编译选项。

我们定义了一些 options 用于启用或关闭部分功能，具体可以参照以下的类似格式：

sese/CMakeLists.txt

Lines 8 to 16 in 4cd7438

	option(SESE_USE_NATIVE_MANAGER "use the unix-like packages control" OFF)
	option(SESE_BUILD_TEST "build unit test targets" OFF)
	option(SESE_BUILD_EXAMPLE "build example targets" OFF)
	option(SESE_AUTO_VCPKG "auto find vcpkg and include toolchain" OFF)
	option(SESE_USE_ASYNC_LOGGER "use async logger" OFF)
	option(SESE_USE_ARCHIVE "add archive support" OFF)
	option(SESE_DB_USE_SQLITE "add sqlite support" ON)
	option(SESE_DB_USE_MARIADB "add mariadb and mysql support" OFF)
	option(SESE_DB_USE_POSTGRES "add postgresql support" OFF)

Tip

请根据最新 CMakeLists.txt文件了解相应的功能选项， 或者你可以直接使用我们预设的 CMakePresets.json, 这将默认开启绝大多数功能选项。

3. 编译

配置完成编译选项只需要常规构建即可，例如：

cmake --build build/linux-debug -- -j 4

对于普通使用者

对于普通使用者，我们推荐使用 vcpkg 导入此依赖，可以参考我们的模板项目配置你的项目：

Warning

项目也可以作为普通项目安装在普通机器上，但这不是推荐的做法，也无法得到支持， 如果你想这么做可以参考 构建 > 对于开发者/贡献者 中关于系统依赖管理工具的内容。

主要工作是编写项目的依赖配置文件，例如：

vcpkg.json

{
  "dependencies": [
    "sese"
  ]
}

Important

自内建库基线 14b91796a68c87bc8d5cb35911b39287ccb7bd95 之后，sese 已进入内建列表。 在此之前，你需要多编写一个配置文件用于导入我们的私有注册表。

vcpkg-configuration.json

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg.git",
    "baseline": "c8696863d371ab7f46e213d8f5ca923c4aef2a00"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/libsese/vcpkg-registry.git",
      "baseline": "73268778d5f796f188ca66f71536377b171ee37e",
      "packages": [
        "sese"
      ]
    }
  ]
}

如果你没有使用 vcpkg，上述步骤是不必要的。

测试

使用了 googletest 作为了测试框架，测试的详细信息可以从 github actions 中查看，包括各个平台的测试结果和 linux 的测试覆盖率等内容。

平台	入口	单元测试	覆盖率测试
Windows	Unit Tests	✅
Linux	Unit Tests	✅	✅
macOS	Unit Tests	✅

1. 本地测试

如果你需要在本地运行完整测试，那么你可能需要注意关于数据库方面的测试，这需要一些额外的服务和配置支撑。

• Ubuntu 工作流对于服务的处理参考

sese/.github/workflows/ubuntu-22.04-apt.yml

Lines 14 to 34 in 4cd7438

	services:
	mariadb:
	image: mariadb
	env:
	MARIADB_ROOT_HOST: '%'
	MARIADB_USER: libsese
	MARIADB_PASSWORD: libsese
	MARIADB_ROOT_PASSWORD: libsese
	ports:
	- '127.0.0.1:18806:3306'
	postgresql:
	image: postgres
	env:
	POSTGRES_PASSWORD: libsese
	options: >-
	--health-cmd pg_isready
	--health-interval 10s
	--health-timeout 5s
	--health-retries 5
	ports:
	- '127.0.0.1:18080:5432'

sese/.github/workflows/ubuntu-22.04-apt.yml

Lines 45 to 53 in 4cd7438

	- name: Setup Database
	working-directory: ${{ github.workspace }}
	env:
	PGPASSWORD: libsese
	run: |
	mysql -uroot -plibsese -h 127.0.0.1 -P 18806 < ./scripts/mysql_dump.sql
	psql -U postgres -d postgres -h 127.0.0.1 -p 18080 -f ./scripts/postgres_dump.sql
	mkdir build
	sqlite3 build/db_test.db < scripts/sqlite_dump.sql

sese/.github/workflows/ubuntu-22.04-apt.yml

Lines 72 to 75 in 4cd7438

	-DSESE_DB_MYSQL_CONNECTION_STRING="host=127.0.0.1\;port=18806\;user=root\;pwd=libsese\;db=db_test\;"
	-DSESE_DB_PSQL_CONNECTION_STRING="host=127.0.0.1\;port=18080\;user=postgres\;pwd=libsese\;db=db_test\;"
	-DSESE_DB_SQLITE_CONNECTION_STRING="${{ github.workspace }}/build/db_test.db"
	-DCMAKE_CXX_FLAGS="--coverage -fprofile-update=atomic"

• 直接使用 docker-compose.yml

docker-compose up -d
sqlite3 build/db_test.db < scripts/sqlite_dump.sql

2. 生成覆盖率测试报告

需要安装 gcovr，可以选择 pip 安装或者使用系统包管理器安装。

mkdir -p build/coverage/html
gcovr --config gcovr-html.cfg

Note

生成覆盖率测试数据首先需要设置一些额外的编译选项来生成例如 gcov 格式的测试数据，例如 GCC：

sese/.github/workflows/ubuntu-22.04-apt.yml

Line 75 in 4cd7438

-DCMAKE_CXX_FLAGS="--coverage -fprofile-update=atomic"

文档

文档将会随着主线的更新而自动更新到 github pages 上。

文档内容将从代码注释中自动生成，docs 目录实际存放构建文档所需的部分资源。

贡献者