KlyLogger

一个支持彩色控制台输出和日志文件写入的轻量级 C/C++ 日志库。

平台支持

• Windows (tested on Windows 7, Windows 10 and Windows 11)
• Linux (tested on Ubuntu and Kali)

使用示例

语言标准要求：KlyLogger.hpp 最低需要 C++20；KlyLogger.h 的 _Generic
自动格式参数最低需要 C11。底层不带格式参数的 C 声明本身只使用 C99 特性，
但若要使用完整的公开 C API，受支持的最低版本是 C11。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

#include "KlyLogger.hpp"

int main() {
  // 初始化日志器
  KlyLogger logger; // 默认日志器

  // 日志示例
  logger.info(L"Application started: {}", L"MyApp");

  std::string user = "Lucy";
  std::wstring action = L"logged in";
  logger.info("User {} {}", user, action); // string 与 wstring 混用

  logger.warn(L"Low memory warning: {} MB left", 100);
  logger.error(L"File not found: {}", "config.txt");
  logger.fatal(L"Unexpected crash!");

  // Minecraft 风格彩色字符示例
  // Example: §c red, §a green, §e yellow, §b aqua, §f white, §5 purple
  KlyLogger("Colorful").info(L"§c红色 §a绿色 §e黄色 §b水蓝色 §f白色 §5紫色");

  return 0;
}

C API / C 接口

C 头文件通过 opaque handle 保留日志器对象。C11 _Generic 让静态库能够保留参数类型，并应用 fmt 风格的 {} 格式化。默认 C API 使用宽字符串，窄字符串 API 使用 _narrow 后缀。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

#include "KlyLogger.h"

int main(void) {
  KlyLogger logger = kly_logger_create_named(L"C_App");
  const char *narrow_user = "Lucy";
  if (!logger) return 1;

  kly_logger_info(logger, L"Application started");
  kly_logger_info(logger, L"User {} has {:04} points; pi={:.2f}", L"Lucy", 42, 3.14159);
  // 普通 char 字符串作为格式参数时需要显式标记
  kly_logger_info(logger, L"Narrow user: {}", KLY_STRING_ARG(narrow_user));
  kly_logger_warn_narrow(logger, "Narrow text: {}; value: {}", KLY_STRING_ARG("warning"), 7);
  kly_logger_wait();
  return 0;
}

同一组 info、warn、error、fatal 名称既可接收普通消息，也可在格式串后直接接收最多 16 个参数。
C11 _Generic 会保留每个参数的类型，宏会自动计算参数数量，因此用户不需要构造类型标记数组、手写参数数量或调用单独的 _format 函数。
遇到少见类型或需要精确控制转换时，仍可使用 KLY_INT_ARG 等显式构造宏。

在少数 wchar_t 与 char 属于兼容类型的 C 实现中，两种指针无法同时写入同一个 _Generic 关联列表。
KlyLogger 会优先将这个有歧义的类型视为 wchar_t *；窄字符串参数请显式写成 KLY_STRING_ARG(value)。
在 wchar_t 与 char 类型不同的常规平台上，两者仍会被自动识别。

C 格式化接口支持 {}、{1} 等位置参数、{:08x} 和 {:.2f} 等普通格式说明，{{`、`}} 转义花括号，以及 {0:{1}}、{0:.{1}f} 这类嵌套动态宽度或精度。
C 的类型标记参数会传入 fmt 的动态参数存储，完整格式字符串只进行一次格式化。

静态库构建

克隆仓库及其子模块:

1

git clone --recursive https://github.com/KinnerFisch/KlyLogger.git

如果克隆时未使用 --recursive:

1

git submodule update --init --recursive

1
2
3

mkdir build
cmake -S . -B build
cmake --build build --config Release

使用 CMake 时直接链接所选目标:

1
2

add_subdirectory(path/to/KlyLogger)
target_link_libraries(your_target PRIVATE KlyLogger::KlyLogger)

四种组合会同时生成:

输出句柄缓存是 Windows 特有行为；Linux 仍会生成对应的静态库，以便各平台发布包保持相同的四种命名布局。

手动链接 C API 时请使用 C++ 链接器驱动，或显式加入平台的 C++ 运行库，因为静态库的内部实现使用 C++。

主要功能

• 多线程安全操作
• 控制台彩色输出
• 同时支持控制台和文件日志
• 提供默认和自定义名称日志器, 开箱即用
• 提供简单易用的 {fmt} 格式化，支持动态宽度与精度
• 支持类似 Minecraft 的彩色字符输出
• 支持多种日志等级：info, warn, error, fatal
• 支持 std::string 与 std::wstring 混合使用
• 所有日志文件会自动保存到程序所在位置（非工作目录）下的 logs 文件夹中

  ⚠️ 注意：不建议在 std::string 中使用非 ASCII 字符, 避免解码出现乱码

许可证与第三方软件

KlyLogger 使用 Boost Software License 1.0 发布。
格式化实现使用 {fmt}，版权归 Victor Zverovich 及 {fmt} 贡献者所有，并使用 MIT 许可证。
fmt 的完整许可文本保留于 fmt/LICENSE 和 THIRD_PARTY_NOTICES.md，
CMake 安装静态库时也会一并安装这些许可证文件。

灵感来源

KlyLogger 的日志输出格式灵感来自知名的 Minecraft 服务器项目 PaperMC，并在此基础上根据个人喜好进行了颜色与视觉样式的改进。
同时，这也是本人踏入现代化 C++ 开发的入门作品。

在 GitHub 查看代码