ZZY
52097a36ee
- 创建了项目的基本目录结构和文件 - 添加了 CMakeLists.txt 和 Makefile 构建配置 - 创建了 main.c 文件，实现了简单的 LED 闪烁和按键检测功能 - 集成了 SEGGER RTT 库 - 添加了 .gitignore 文件，排除了不必要的生成文件
213 lines
5.7 KiB
Markdown
213 lines
5.7 KiB
Markdown
# Pythonic_log
|
|
|
|
纯头文件的轻量化日志库，模仿 Python `logging` 标准库的设计，支持终端彩色输出，不依赖任何标准库。
|
|
|
|
## 特性亮点
|
|
|
|
- 🚀 **纯头文件实现** - 单文件集成，无需编译
|
|
- 🧩 **零依赖** - 不依赖标准库（可通过宏配置）
|
|
- 🌈 **终端彩色输出** - 内置 ANSI 颜色支持
|
|
- ⚙️ **多级日志系统** - 支持 DEBUG/INFO/WARN/ERROR/FATAL/TRACE
|
|
- 🧪 **高级断言工具** - 包含 Assert, Panie, TODO 等实用宏
|
|
- 📦 **模块化设计** - 支持多模块独立日志配置
|
|
- 🔧 **高度可配置** - 自定义输出、格式化和退出行为
|
|
|
|
## 快速入门
|
|
|
|
### 基础使用
|
|
|
|
```c
|
|
#include "pylike_log.h"
|
|
|
|
int main() {
|
|
// 基础日志输出
|
|
LOG_INFO("Application started");
|
|
LOG_DEBUG("Debug value: %d", 42);
|
|
LOG_WARN("This is a warning");
|
|
LOG_ERROR("Something went wrong!");
|
|
|
|
// 断言工具
|
|
int value = 10;
|
|
Assert(value > 5); // 条件断言
|
|
AssertFmt(value != 0, "Value cannot be zero");
|
|
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
### 输出示例
|
|
|
|
```shell
|
|
[INFO ] - root - main.c:8 | Application started
|
|
[DEBUG] - root - main.c:9 | Debug value: 42
|
|
[WARN ] - root - main.c:10 | This is a warning
|
|
[ERROR] - root - main.c:11 | Something went wrong!
|
|
```
|
|
|
|
## 核心功能
|
|
|
|
### 日志级别控制
|
|
|
|
```c
|
|
// 获取日志器实例
|
|
logger_t* logger = log_get("my_module");
|
|
|
|
// 设置日志级别（只显示 WARN 及以上）
|
|
log_set_level(logger, LOG_LEVEL_WARN | LOG_LEVEL_ERROR | LOG_LEVEL_FATAL);
|
|
|
|
// 模块化日志
|
|
MLOG_WARN(logger, "Module-specific warning: %s", "Low memory");
|
|
```
|
|
|
|
### 自定义日志处理器
|
|
|
|
```c
|
|
void custom_handler(
|
|
log_level_t level,
|
|
const char* module,
|
|
const char* file,
|
|
int line,
|
|
const char* message
|
|
) {
|
|
// 自定义处理逻辑（如写入文件/网络）
|
|
printf("[CUSTOM] %s:%d - %s\n", file, line, message);
|
|
}
|
|
|
|
int main() {
|
|
logger_t* logger = log_get(NULL);
|
|
log_set_handler(logger, custom_handler);
|
|
|
|
LOG_INFO("This will use custom handler");
|
|
return 0;
|
|
}
|
|
```
|
|
|
|
### 断言系统
|
|
|
|
```c
|
|
void critical_function(int* ptr) {
|
|
// 空指针检查
|
|
AssertFmt(ptr != NULL, "Received NULL pointer");
|
|
|
|
// 范围检查
|
|
AssertFmt(*ptr >= 0 && *ptr <= 100, "Value %d out of range", *ptr);
|
|
|
|
// 标记未实现功能
|
|
TODO(); // 触发致命错误
|
|
}
|
|
```
|
|
|
|
## 配置选项
|
|
|
|
### 基本配置宏
|
|
|
|
| 宏名称 | 默认值 | 描述 |
|
|
| :-------------------- | :----- | :--------------- |
|
|
| `LOGGER_MAX_BUF_SIZE` | 512 | 单条日志最大长度 |
|
|
| `__LOG_NO_COLOR__` | - | 禁用彩色输出 |
|
|
| `__NO_STDIO__` | - | 禁用标准库依赖 |
|
|
|
|
|
|
### 标准库替代（嵌入式环境）
|
|
```c
|
|
// 在包含头文件前定义这些宏
|
|
#define _pylike_logout_printf(fmt, ...) my_printf(fmt, ##__VA_ARGS__)
|
|
#define _pylike_snprintf my_snprintf
|
|
#define _pylike_exit my_exit
|
|
|
|
#include "pylike_log.h"
|
|
```
|
|
|
|
### 颜色自定义
|
|
编辑 `pylike_color.h` 修改 ANSI 颜色代码，或定义 `__NO_PYLIKE_COLOR__` 完全禁用颜色。
|
|
|
|
## 高级用法
|
|
|
|
### 性能追踪
|
|
|
|
```c
|
|
void complex_operation() {
|
|
LOG_TRACE("Entering complex_operation");
|
|
|
|
// ... 复杂计算 ...
|
|
|
|
LOG_TRACE("Exiting complex_operation");
|
|
}
|
|
```
|
|
|
|
### 致命错误处理
|
|
|
|
```c
|
|
void load_config() {
|
|
if (!config_valid) {
|
|
LOG_FATAL("Invalid configuration - aborting");
|
|
// 此处会自动调用 exit(-1)
|
|
}
|
|
}
|
|
```
|
|
|
|
### 模块化日志系统
|
|
|
|
```c
|
|
// 创建模块专用日志器
|
|
logger_t network_logger;
|
|
init_logger(&network_logger, "NETWORK");
|
|
|
|
// 设置模块日志级别
|
|
log_set_level(&network_logger, LOG_LEVEL_DEBUG | LOG_LEVEL_ERROR);
|
|
|
|
// 使用模块日志
|
|
MLOG_DEBUG(&network_logger, "Connecting to %s", "192.168.1.1");
|
|
```
|
|
|
|
## API 参考
|
|
|
|
### 日志级别
|
|
|
|
```c
|
|
typedef enum log_level {
|
|
LOG_LEVEL_NOTSET = 0, // 未设置级别（继承默认配置）
|
|
LOG_LEVEL_DEBUG = 1 << 0, // 调试信息（开发阶段详细信息）
|
|
LOG_LEVEL_INFO = 1 << 1, // 常规信息（系统运行状态）
|
|
LOG_LEVEL_WARN = 1 << 2, // 警告信息（潜在问题提示）
|
|
LOG_LEVEL_ERROR = 1 << 3, // 错误信息（可恢复的错误）
|
|
LOG_LEVEL_FATAL = 1 << 4, // 致命错误（导致程序终止的严重错误）
|
|
LOG_LEVEL_TRACE = 1 << 5, // 追踪（性能追踪或者栈帧追踪）
|
|
LOG_LEVEL_ALL = 0xFF, // 全级别标志（组合所有日志级别）
|
|
} log_level_t;
|
|
```
|
|
|
|
### 日志器结构
|
|
|
|
```c
|
|
typedef struct logger {
|
|
const char* name; // 日志器名称（用于模块区分）
|
|
log_level_t level; // 当前设置的日志级别
|
|
log_handler handler; // 日志处理回调函数
|
|
char buf[LOGGER_MAX_BUF_SIZE]; // 格式化缓冲区
|
|
} logger_t;
|
|
```
|
|
|
|
### 核心函数
|
|
|
|
| 函数 | 描述 |
|
|
| :---------------------------------------- | :------------------- |
|
|
| `init_logger(logger_t*, const char*)` | 初始化日志器实例 |
|
|
| `log_get(const char*)` | 获取或创建日志器实例 |
|
|
| `log_set_level(logger_t*, log_level_t)` | 设置日志级别 |
|
|
| `log_set_handler(logger_t*, log_handler)` | 设置自定义日志处理器 |
|
|
|
|
## 集成指南
|
|
|
|
1. 将 `pylike_log.h` 和 `pylike_color.h` 添加到项目
|
|
2. 在需要日志的源文件中包含头文件
|
|
3. （可选）配置自定义输出函数（嵌入式系统）
|
|
4. 使用提供的日志宏记录信息
|
|
|
|
## 设计理念
|
|
|
|
- **极简主义**：单头文件实现核心功能
|
|
- **灵活性**：通过宏配置适应各种环境
|
|
- **Pythonic API**：借鉴 Python logging 的优秀设计
|
|
- **安全第一**：所有宏都使用 `do {...} while(0)` 包装
|