# mpilog

**Repository Path**: Yoshiera/mpilog

## Basic Information

- **Project Name**: mpilog
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-07
- **Last Updated**: 2026-02-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MPILog

MPILog 是一个专为 MPI（消息传递接口）应用程序设计的轻量级、仅头文件的日志库。它提供了双输出模式（统一输出用于 rank 0，本地输出用于所有 rank），并通过编译时日志级别消除实现最大性能。

## 特性

- **双输出模式**：统一输出（仅 rank 0）和本地输出（所有 rank）
- **编译时日志级别消除**：使用 `-DMPILog_LEVEL=...` 在编译时移除低级别日志
- **类型安全格式化**：使用 `fmt::format_to_n` 进行安全、高效的格式化
- **零动态分配**：所有缓冲区都在栈上，避免内存分配开销
- **跨平台兼容性**：支持 Linux（包括银河麒麟）和 Windows 7
- **全 MPI 兼容**：兼容 MPICH、OpenMPI、Intel MPI 等
- **仅头文件**：单个头文件包含，易于集成

## 安装

### 先决条件

- 符合 C++14 标准的编译器
- MPI 实现（MPICH、OpenMPI 等）
- CMake 3.14+

### 构建

```bash
mkdir build
cd build
cmake ..
make
```

### 测试（仅主项目）

```bash
cd build
ctest --verbose
```

### 多级别测试

本项目为不同的 `MPILog_LEVEL` 配置提供了全面的测试：

#### 自动化测试（推荐）
```bash
# 自动运行所有级别的测试
./run_level_tests.sh
```

#### 手动测试
```bash
# 启用测试构建
mkdir build && cd build
cmake .. -DMPILOG_BUILD_TESTS=ON
make -j$(nproc)

# 运行特定级别测试
./tests/mpilog_test_TRACE    # Trace 级别
./tests/mpilog_test_DEBUG    # Debug 级别
./tests/mpilog_test_INFO     # Info 级别（默认）
./tests/mpilog_test_WARN     # Warning 级别
./tests/mpilog_test_ERROR    # Error 级别
./tests/mpilog_test_FATAL    # Fatal 级别
./tests/mpilog_test_OFF      # 禁用所有日志
```

详见 [tests/README.md](tests/README.md) 获取详细的测试文档。

### 安装

```bash
cd build
cmake --install . --prefix /usr/local
```

## 使用方法

### 基本使用

```cpp
#include "mpilog.hpp"

int main(int argc, char** argv) {
    // 初始化 MPI 和 MPILog
    MPI_Init(&argc, &argv);
    
    // 初始化 MPILog - 统一输出到 stdout，本地输出到 rank 特定文件
    mpilog_init(nullptr, "myapp.{}");  // 创建 myapp.0000, myapp.0001 等
    
    // 记录不同级别的消息
    MPILogUnifiedINFO("应用程序启动");
    MPILogLocalDEBUG("调试信息：处理 rank {}", 0);
    MPILogUnifiedWARN("警告：资源使用率高");
    MPILogLocalERROR("错误：无法处理数据");
    
    // 刷新日志确保写入
    MPILogFlush();
    
    MPI_Finalize();
    return 0;
}
```

### 日志级别

- `MPILogUnifiedTRACE(...)` / `MPILogLocalTRACE(...)`：Trace 级别（最低优先级）
- `MPILogUnifiedDEBUG(...)` / `MPILogLocalDEBUG(...)`：Debug 级别
- `MPILogUnifiedINFO(...)` / `MPILogLocalINFO(...)`：Info 级别
- `MPILogUnifiedWARN(...)` / `MPILogLocalWARN(...)`：Warning 级别
- `MPILogUnifiedERROR(...)` / `MPILogLocalERROR(...)`：Error 级别
- `MPILogUnifiedFATAL(...)` / `MPILogLocalFATAL(...)`：Fatal 级别（最高优先级）

### 编译时日志级别控制

控制哪些日志级别被编译到您的应用程序中：

```bash
# 仅编译 INFO 及更高级别的日志
g++ -DMPILog_LEVEL=2 -o myapp myapp.cpp

# 仅编译 ERROR 和 FATAL 日志
g++ -DMPILog_LEVEL=4 -o myapp myapp.cpp
```

### 输出配置

```cpp
// 统一输出到 stdout（仅 rank 0），本地输出到 rank 特定文件
mpilog_init(nullptr, "app.{}");

// 统一输出到 stderr（仅 rank 0），无本地输出
mpilog_init("stderr", nullptr);

// 统一输出到文件（仅 rank 0），本地输出到 rank 特定文件
mpilog_init("unified.log", "rank_{}.log");

// 无统一输出，仅本地输出到 rank 特定文件
mpilog_init(nullptr, "local.{}");
```

## 配置选项

### 文件命名

本地文件名支持 `{}` 作为 rank 数字的占位符：
- `"log.{}"` 变为 `"log.0000"`、`"log.0001"` 等
- 如果没有 `{}`，会追加为 `".{}"`：`"log"` 变为 `"log.0000"`、`"log.0001"` 等

### 日志消息格式

每条日志消息包含：
- 时间戳：`[YYYY-MM-DD HH:MM:SS]`
- Rank：`[Rank N]`
- 源位置：`[file:line]`
- 日志级别和消息

示例：
```
[2023-05-15 14:30:22] [INFO] [Rank 0] [main.cpp:25] 应用程序启动
```

## 依赖项

- **MPI**：用于 rank 识别
- **fmt**：用于类型安全格式化（通过 CMake 的 FetchContent 自动下载）
- **Catch2**：用于测试（通过 CMake 的 FetchContent 自动下载，仅当作为主项目构建时）

## 线程安全

MPILog 内部不是线程安全的。如果应用程序中的多个线程可能同时调用日志函数，则必须提供外部同步。

## 许可证

本项目根据 LICENSE 文件中指定的条款获得许可。