📁 CMake 包含目录配置

include_directories(librecad/src/lib/debug) 详解

功能：将调试模块的头文件目录添加到编译器搜索路径

语法解析：

• include_directories()：CMake 命令，添加头文件包含路径
• librecad/src/lib/debug：相对路径，指向调试模块的头文件目录

实际效果：

// 在其他模块中可以直接包含调试头文件
#include "rs_debug.h"  // 编译器知道在这个目录查找

// 无需使用完整路径
#include "librecad/src/lib/debug/rs_debug.h"  // 不需要这样写

在项目中的上下文：

# 虽然排除了调试模块的源文件编译
file(GLOB_RECURSE AUTO_EXCLUDED_SOURCES
    "${PROJECT_SOURCE_DIR}/librecad/src/lib/debug/*.*"  # 排除 rs_debug.cpp
)

# 但仍然包含头文件目录，使得接口可用
include_directories(librecad/src/lib/debug)

🔧 RS_Debug 调试系统完整解析

系统架构概览

设计模式：单例模式 + RAII 流式日志

• 单例模式：全局唯一的调试实例
• 流式接口：C++ 流式操作符重载
• RAII 管理：自动资源清理

核心组件详解

1. 单例管理系统

// 线程安全的单例实现（C++11 标准保证）
RS_Debug *RS_Debug::instance() {
    static RS_Debug *uniqueInstance = nullptr;
    if (uniqueInstance == nullptr) {
        uniqueInstance = new RS_Debug;
        s_logStream = stderr;  // 默认输出到标准错误
    }
    return uniqueInstance;
}

单例优势：

• 全局统一的调试配置
• 避免多次初始化开销
• 线程安全的初始化

2. 流式日志系统 (LogStream)

RAII 设计模式：

RS_Debug::LogStream::LogStream(RS_DebugLevel level)
    : m_pStream(new StreamImpl{level})
{}

RS_Debug::LogStream::~LogStream() {
    // 析构时自动输出累积的日志
    if (!m_pStream->m_string.isEmpty())
        RS_Debug::instance()->print(m_pStream->m_debugLevel, "%s",
                                    m_pStream->m_string.toStdString().c_str());
    delete m_pStream;
}

工作流程：

1. 创建 LogStream 对象
2. 通过 operator<< 累积日志内容
3. 对象析构时自动输出完整日志

3. Qt 集成设计

// 基于 QTextStream 的实现
struct RS_Debug::LogStream::StreamImpl : public QTextStream {
    StreamImpl(RS_DebugLevel level) 
        : QTextStream{&m_string, QIODeviceBase::WriteOnly}
    {}
    
    QString m_string;  // 存储格式化后的字符串
    RS_DebugLevel m_debugLevel;
};

Qt 类型支持：

// 完整的 Qt 类型支持
LogStream& operator<<(const QString &s);
LogStream& operator<<(QStringView s);
LogStream& operator<<(QLatin1String s);
LogStream& operator<<(const QByteArray &array);
LogStream& operator<<(QChar ch);

4. LibreCAD 特定类型支持

// 对 RS_Vector 的特殊支持
LogStream& operator<<(const RS_Vector & v) {
    *m_pStream << "(" << v.x << "," << v.y <<  (v.valid ? ")" : "!)");
    return *this;
}

输出示例：(10.5, 20.3) 或 (15.0, 25.5!)（无效向量）

调试级别系统

7级调试体系

enum RS_DebugLevel: char { 
    D_NOTHING=0,        // 完全静默
    D_CRITICAL=1,       // 严重错误（程序可能崩溃）
    D_ERROR=2,          // 普通错误（功能失败）
    D_WARNING=3,        // 警告信息（潜在问题）
    D_NOTICE=4,         // 通知信息（重要状态变化）
    D_INFORMATIONAL=5,  // 一般信息（流程跟踪）
    D_DEBUGGING=6       // 详细调试（算法内部状态）
};

级别过滤逻辑

void RS_Debug::print(RS_DebugLevel level, const char *format...) {
    if (m_debugLevel >= level) {  // 只有更高级别的消息才输出
        va_list ap;
        va_start(ap, format);
        vfprintf(s_logStream, format, ap);
        fprintf(s_logStream, "\n");
        va_end(ap);
        fflush(s_logStream);
    }
}

🎯 实际使用示例

1. 基本调试输出

#include "rs_debug.h"

// 传统方式（C风格）
RS_DEBUG->print("加载文件: %s", filename.c_str());
RS_DEBUG->print(D_ERROR, "文件不存在: %s", filename.c_str());

// 现代方式（流式风格）
LC_LOG << "加载文件: " << filename;
LC_ERR << "文件不存在: " << filename;

2. 复杂数据类型输出

#include "rs_debug.h"

void RS_Math::calculateIntersection(const RS_Line& line1, const RS_Line& line2) {
    LC_LOG << "直线交点计算:"
           << "\n  直线1: 起点" << line1.startPoint << " 终点" << line1.endPoint
           << "\n  直线2: 起点" << line2.startPoint << " 终点" << line2.endPoint;
    
    RS_Vector intersection = computeIntersection(line1, line2);
    
    LC_LOG << "计算结果: 交点" << intersection;
    
    if (!intersection.valid) {
        LC_WARNING << "直线平行，无交点";
    }
}

3. 性能监控和时序

#include "rs_debug.h"

void RS_GraphicView::renderComplexScene() {
    LC_LOG(D_DEBUGGING) << "开始渲染复杂场景";
    RS_DEBUG->timestamp();  // 输出时间戳
    
    // 复杂渲染逻辑
    renderBackground();
    renderGrid();
    for (auto& entity : m_entities) {
        LC_LOG(D_DEBUGGING) << "渲染实体: " << entity->typeName();
        entity->draw(m_painter);
    }
    
    LC_LOG(D_DEBUGGING) << "场景渲染完成";
}

⚡ 性能优化特性

1. 运行时级别过滤

// 低级别消息在运行时被过滤
LC_LOG(D_DEBUGGING) << "详细算法状态";  // 可能被过滤
LC_ERR << "关键错误信息";              // 通常输出

2. 字符串构建优化

// 使用 QString 避免多次内存分配
// QTextStream 内部优化字符串构建

3. 资源自动管理

// RAII 确保资源正确释放
{
    auto log = RS_Debug::Log(D_DEBUGGING);
    log << "临时调试信息";
} // 自动输出并清理资源

🔧 配置和使用建议

开发阶段配置

// 开发版本：详细调试
RS_DEBUG->setLevel(RS_Debug::D_DEBUGGING);

// 在关键算法中添加详细日志
LC_LOG << "几何算法输入: " << inputParameters;
LC_LOG << "计算中间结果: " << intermediateResult;
LC_LOG << "最终输出: " << finalResult;

测试阶段配置

// 测试版本：关注错误和警告
RS_DEBUG->setLevel(RS_Debug::D_WARNING);

// 验证关键路径
LC_ASSERT(result.isValid());  // 自定义断言（需要实现）
LC_LOG(D_WARNING) << "性能注意: 操作耗时较长";

生产环境配置

// 生产版本：只记录关键问题
RS_DEBUG->setLevel(RS_Debug::D_ERROR);

// 用户几乎看不到调试输出
LC_ERR << "系统错误: 需要重启";  // 只有严重错误才显示

✅ 设计优势总结

技术优势

• ✅ 类型安全：编译时类型检查，避免格式化错误
• ✅ 性能可控：多级别运行时过滤
• ✅ 资源安全：RAII 自动管理，避免资源泄漏
• ✅ 扩展性强：易于添加新的数据类型支持

架构优势

• 🏗️ 模块化设计：清晰的接口与实现分离
• 🔧 现代 C++：使用单例、RAII、流式操作符等现代特性
• 🌍 Qt 集成：完整的 Qt 类型系统支持
• 📊 生产就绪：支持从开发到生产的不同配置

在 LibreCAD 中的价值

这个调试系统为复杂的 CAD 软件提供了：

• 🔍 深度洞察：跟踪几何算法的执行细节
• 🐛 快速诊断：直观的流式输出便于问题定位
• 📈 性能分析：通过日志分析渲染和计算性能
• 🎯 质量保证：支持不同严格程度的测试验证

CMake 配置的合理性：
通过 include_directories(librecad/src/lib/debug) 虽然排除了源文件编译，但保持了接口的可用性，这种设计允许：

• 灵活的构建配置（包含/排除调试功能）
• 统一的代码库（无需为不同构建修改源码）
• 运行时控制（通过调试级别动态调整）