郭金锋的博客

TensorRT部署Cifar100CNN模型

2026-04-09T16:00:00.000Z

本文介绍如何使用TensorRT部署一个简单的用于Cifar100分类任务的CNN模型。

本文项目源码在这里，所使用的模型为我自己训练的小型CNN模型，导出的ONNX格式模型和训练代码在这里。

PyTorch 导出 ONNX 格式

PyTorch 支持将模型导出到 ONNX 格式，便于后面使用 TensorRT 进行加速。支持动态 batch size，方便批处理。方法如下：

def export_onnx(model, checkpoint):
    model = CIFAR100_VGG()
    load_model_params(model, checkpoint)
    model.eval()

    dummy_input = torch.randn(1, 3, 32, 32)
    torch.onnx.export(
        model,
        dummy_input,
        "cifar100_vgg.onnx",
        verbose=True,
        input_names=["input"],  # 输入节点名称
        output_names=["output"],  # 输出节点名称
        opset_version=13,  # 算子集版本
        dynamic_axes={
            "input": {0: "batch_size"},  # 第0维 = 动态 batch
            "output": {0: "batch_size"},  # 输出第0维也跟着动态
        },
    )


if __name__ == "__main__":
    model = CIFAR100_VGG()
    export_onnx(model, "./checkpoints/model_best.pth")

TensorRT 编译 ONNX 模型

之后是使用 TensorRT 编译导出的 ONNX 模型。TensorRT 编译主要有三种方法，分别是通过 trtexec 命令和通过 TensorRT 的 Python 和 C++的 API。

trtexec 命令最为简单快速，适应简单模型。而 Python API 相对要更方便一些，支持更多细致的配置。但是如果有自定义插件等更复杂的要求，还是需要 C++ API，其提供最多的特性和最高的性能。

这里进行的是简单的 CNN 模型，于是直接使用 trtexec 命令进行编译。命令大致如下：

1	`trtexec --onnx=cifar100_vgg.onnx --saveEngine=cifar100_vgg.engine --fp16`

在训练的过程中往往使用 32 位浮点型作为计算的数据结构，而在工程实践中，则常常使用 16 位，这在精度影响不大的情况下获得更高的速度。这便是量化。

量化的本质是：用更低比特（更少位数）的数据类型来近似表示高精度的浮点数据。除了 fp32 和 fp16，有时为了极致速度会使用 int8，这还会牵扯到“校准”的过程，精度也容易出现明显下降。

这里我们使用常用的 fp16 来加速。

模型性能简单评估

可以使用 trtexec 提供的功能来简单评估模型的性能。

1	`trtexec --loadEngine=cifar100_vgg.engine`

输出的信息中有延迟和吞吐量等信息。吞吐量表示每秒可以处理多少个请求(queries per second/qps)。

使用 TensorRT C++ API 进行模型构建

目前计划写一个简单的 TensorRT C++ API 的封装工具，用于部署简单的模型，封装构建，推理，预处理等过程，便于之后的学习。

目前已完成构建部分的代码，目前该模块实现了从 .engine 文件中直接加载模型和先将模型从 onnx 格式转化再加载的功能。同时对 Nvidia 相关库中的指针进行了简单的 RAII 封装，使用 unique_ptr 保证保证资源被正确释放并自定了删除器。

后续会尝试通过 C++ API 进行推理，并使用 OpenCV 做基础的预处理。这些都完善之后就是想办法将其集成到 ROS 中，在 Gazebo 仿真环境下进行基础的视觉任务。

使用 TensorRT C++ API 构建模型

封装了编译模型和加载模型的接口。在编译模型后将其保存为 .engine 文件，编译模型函数接受一个回调函数，用于配置构建器等。也可以从 .engine 文件加载模型。

// ModelBuilder.h
using TRTBuildConfigFun =
    std::function<void(nvinfer1::IBuilderConfig*, nvinfer1::INetworkDefinition*,
                       nvinfer1::IBuilder*)>;

class TRTModelBuilder {
public:
    TRTModelBuilder(nvinfer1::ILogger& logger) : m_logger(logger) {}

    // 从本地 .engine (Plan) 文件加载
    TRTPtr loadFromPlan(const std::string& enginePath);

    // 从 ONNX 编译并保存为 .engine
    TRTPtr
    buildFromOnnx(const std::string& onnxPath, const std::string& enginePath,
                  TRTBuildConfigFun configFun = nullptr);

private:
    nvinfer1::ILogger& m_logger;
};

// ModelBuilder.cpp
TRTPtr
TRTModelBuilder::loadFromPlan(const std::string& enginePath) {
    std::ifstream file(enginePath, std::ios::binary);
    if (!file.good())
        return nullptr;

    file.seekg(0, std::ios::end);
    size_t size = file.tellg();
    file.seekg(0, std::ios::beg);

    std::vector<char> data(size);
    file.read(data.data(), size);

    auto runtime =
        TRTPtr(nvinfer1::createInferRuntime(m_logger));
    return TRTPtr(
        runtime->deserializeCudaEngine(data.data(), size));
}

TRTPtr
TRTModelBuilder::buildFromOnnx(const std::string& onnxPath,
                               const std::string& enginePath,
                               TRTBuildConfigFun configFun) {
    auto builder =
        TRTPtr(nvinfer1::createInferBuilder(m_logger));
    auto network =
        TRTPtr(builder->createNetworkV2(0U));
    auto config =
        TRTPtr(builder->createBuilderConfig());
    auto parser = TRTPtr(
        nvonnxparser::createParser(*network, m_logger));

    // 如果解析失败，说明 onnx 模型有问题
    if (!parser->parseFromFile(
            onnxPath.c_str(),
            static_cast<int>(nvinfer1::ILogger::Severity::kWARNING))) {
        return nullptr;
    }

    if (configFun) {
        // 调用配置函数
        configFun(config.get(), network.get(), builder.get());
    }

    // 编译模型
    auto plan = TRTPtr(
        builder->buildSerializedNetwork(*network, *config));
    if (!plan)
        return nullptr;

    // 将编译好的 Engine 保存到磁盘，下次直接 load
    std::ofstream outfile(enginePath, std::ios::binary);
    outfile.write(reinterpret_cast<const char*>(plan->data()), plan->size());

    auto runtime =
        TRTPtr(nvinfer1::createInferRuntime(m_logger));
    return TRTPtr(
        runtime->deserializeCudaEngine(plan->data(), plan->size()));
}

使用 OpenCV 进行图片预处理

首先要获得用于推理的图片，当前是用 PyTorch 加载数据集之后使用 OpenCV 直接导出其原始图片，并记录了元数据，记录了每张图片的类型 id 和名称，可以用于后续的推理验证。

要进行推理，需要将图片读取并完成预处理，包括转化成浮点数和归一化，以及将排列顺序调整成 TensorRT 使用的顺序。

一般的图片使用 RGB 的格式，而 OpenCV 则使用 BGR 来存储图片，这使得要将 OpenCV 中的图片喂给 TensorRT，必须先将 BGR 转为 RGB。

除此之外，OpenCV 默认使用 HWC 的顺序排列数据，即按照 RGBRGBRGB的形式排列，而在 TensorRT 中，为了提升访存效率，使用 CHW 布局进行排列，即 RRRGGGBBB 的形式。必须重新排布数据才能进行推理。

之后就是 PyTorch 中训练进行了张量化和归一化，因此要进行推理，我们也需要将原本的 uint8 类型转为 float，再归一化。

目前已实现了一个对 Cifar100 数据集进行预处理的类，并进行了一些性能优化上的尝试。

目前的实现中大量使用了模板元编程，使用模板参数来传递各种静态信息增强通用性，比如通过可变模板参数实现编译期的数组等。

对于类似输入数据的维度，均值和方差等常量，以及不同颜色空间的映射声明模板类和对应的 concept，声明 constexpr 成员函数和变量来传递。

将原本通过 opencv 完成的颜色空间重映射改为在改变排列顺序和归一化时一并进行，效率比原本要再高一些，同时支持不同的颜色空间变换。

// common.h
struct TRTDeleter {
    template <typename T>
    void operator()(T* obj) const {
        if (obj) {
#if NV_TENSORRT_MAJOR < 9
            obj->destroy();
#else
            delete obj;  // TensorRT 10.0+ 推荐做法
#endif
        }
    }
};

template <typename T>
using TRTPtr = std::unique_ptr;

template <typename T>
concept Processor = requires(const cv::Mat& img, float* output) {
    { T::process(img, output) } -> std::same_as<void>;
};

// 张量规格，编译期维度信息
template <size_t... Sizes>
struct TensorSpec {
    static constexpr size_t total_size() {
        size_t size = 1;
        ((size *= Sizes), ...);
        return size;
    }
    static constexpr std::array<size_t, sizeof...(Sizes)> dims() {
        return {Sizes...};
    }
};

template <typename T>
concept TensorSpecType = requires {
    { T::total_size() } -> std::convertible_to<size_t>;
};

// 编译期数组
template <float... elems>
struct FloatArraySpec {
    static constexpr std::array<float, sizeof...(elems)> values() {
        return {elems...};
    }
};

/* 是是否编译期数组规格类型，即可通过values()方法获取std::array
 * N>类型的数组，其中N为元素个数个数 */
template <typename T>
concept FloatArraySpecType = requires {
    {
        T::values()
    } -> std::convertible_tofloat, T::values().size()>>;
};

// 颜色空间映射，编译器索引信息
// 注意：使用RGB表示第一个，第二个和第三个通道的索引位置，哪怕你不是要转成RGB
template <typename T>
concept ChannelMapType =
    requires {
        { T::r } -> std::convertible_to<int>;
        { T::g } -> std::convertible_to<int>;
        { T::b } -> std::convertible_to<int>;
        { T::index() } -> std::convertible_toint, 3>>;
    } && (T::r >= 0 && T::r < 3) && (T::g >= 0 && T::g < 3) &&
    (T::b >= 0 && T::b < 3);

template <int R, int G, int B>
struct ChannelMapSpec {
    static constexpr int r = R;
    static constexpr int g = G;
    static constexpr int b = B;

    static constexpr std::array<int, 3> index() {
        return {R, G, B};
    }
};

using KeepChannelMap = ChannelMapSpec<0, 1, 2>;


// Processor.h
template <size_t... Is>
constexpr auto make_alphas_impl(const std::array<float, sizeof...(Is)>& stds,
                                std::index_sequence) {
    return std::array<float, sizeof...(Is)> {(1.0f / (255.0f * stds[Is]))...};
}

template <size_t... Is>
constexpr auto make_betas_impl(const std::array<float, sizeof...(Is)>& means,
                               const std::array<float, sizeof...(Is)>& stds,
                               std::index_sequence) {
    return std::array<float, sizeof...(Is)> {(-means[Is] / stds[Is])...};
}

template           FloatArraySpecType Std, ChannelMapType ChannelMap = KeepChannelMap>
class ConvertHWC2CHW {
private:
    constexpr static int input_height = InputSpec::dims()[0];
    constexpr static int input_width = InputSpec::dims()[1];
    constexpr static int channel_num = InputSpec::dims()[2];
    constexpr static std::array<int, channel_num> channel_map =
        ChannelMap::index();

    constexpr static std::array<float, channel_num> alphas = make_alphas_impl(
        Std::values(), std::make_index_sequence {});
    constexpr static std::array<float, channel_num> betas =
        make_betas_impl(Mean::values(), Std::values(),
                        std::make_index_sequence {});

public:
    static void process(const cv::Mat& input, float* output) {
        int channel_size = input_height * input_width;

        std::array bgr_channels;
        cv::split(input, bgr_channels);

        for (int i = 0; i < channel_num; ++i) {
            cv::Mat target_slice(
                input_height, input_width, CV_32FC1,
                output + ChannelMap::index()[i] * channel_size);

            bgr_channels[i].convertTo(target_slice, CV_32FC1,
                                      alphas[channel_map[i]],
                                      betas[channel_map[i]]);
        }
    }
};

编写推理类

声明推理类，用于统一管理上下文和流的生命周期，并提供访问的 API。近用于执行推理，数据的输入输出由外部管理，所需参数由外部提供。

推理类在构造时接受 ICudaEngine 对象，并创建其引用。之后通过它创建上下文（IExecuteContext），并创建一个流（CudaStream）。通过对外提供的公共接口由外部分配内存并绑定模型输入输出的内存指针，对外提供的 infer 接口仅运行推理操作，由外部负责及时读取和写入输入输出。infer 函数接受一个回调函数，用于对 context 进行一些配置，如设置动态的 batch size。

using TRTInferConfigFun = std::function<void(nvinfer1::IExecutionContext*)>;

class TRTInference {
protected:
    nvinfer1::ICudaEngine& engine;
    TRTPtr context;
    cudaStream_t stream;

public:
    TRTInference() = delete;

    TRTInference(nvinfer1::ICudaEngine& engine)
        : engine(engine), context(engine.createExecutionContext()) {
        cudaStreamCreate(&stream);
    }

    TRTInference(const TRTInference&) = delete;
    TRTInference& operator=(const TRTInference&) = delete;
    TRTInference(TRTInference&&) noexcept = delete;
    TRTInference& operator=(TRTInference&&) noexcept = delete;

    ~TRTInference() {
        cudaStreamDestroy(stream);
    }

    template <typename... Args>
    bool set_tensor_address(Args&&... args) {
        return context->setTensorAddress(std::forward(args)...);
    }

    template <typename... Args>
    const void* get_tensor_address(Args&&... args) {
        return context->getTensorAddress(std::forward(args)...);
    }

    cudaStream_t get_stream() {
        return stream;
    }

    bool infer(TRTInferConfigFun configFun = nullptr) {
        if (configFun) {
            configFun(context.get());
        }
        return context->enqueueV3(stream);
    }
};

编写 Cifar100 模型的运行类

为 Cifar100 编写运行类，接受模型的文件路径，声明各种模板类型，负责分配显存存储模型的输入输出，以及从 CPU 向 GPU 传递数据的临时缓冲区。封装预处理，向 gpu 传入数据，发送推理任务，从 gpu 读取结果，后处理等流程。推理接口接受图片数组并传回每张图片的分类结果，即对应类别 ID。

支持动态 batch size，在 infer 函数中将输入数组分割成一个个 batch，再批量进行处理。预处理和后处理部分使用 OpenMP 进行简单并行处理。模型构建时设置最小，最优，最大 batch size 分别为 1，64，256。分配显存和内存时按照最大来分配避免重复分配，传递数据和推理时使用动态大小。

// Cifar100CNN.h
class Cifar100CNN {
private:
    std::string onnx_path;
    std::string engine_path;

    TRTPtr engine;
    TRTPtr inference;

    float* input_buffer;
    float* output_buffer;

    void* gpu_input;
    void* gpu_output;

    void set_tensor_addresses();

    void preprocess(std::vector::const_iterator input,
                    size_t batch_size);
    void postprocess(std::vector<int>::iterator output, size_t batch_size);
    void infer(size_t batch_size);
    auto InputData(size_t batch_size);
    auto OutputData(size_t batch_size);

public:
    Cifar100CNN(std::string onnx_path, std::string engine_path,
                TRTLogger& logger, bool always_rebuild = false);
    ~Cifar100CNN() noexcept;
    std::vector<int> infer(const std::vector& input,
                           size_t batch_size = 0);
};

// Cifar100CNN.cpp
using InputImg = TensorSpec<32, 32, 3>;
using OutputRes = TensorSpec<100>;
using Mean = FloatArraySpec<0.5071f, 0.4865f, 0.4409f>;
using Std = FloatArraySpec<0.2673f, 0.2564f, 0.2761f>;
using ChannelMap = ChannelMapSpec<2, 1, 0>;
using Cifar100Processor = ConvertHWC2CHW;

using BatchSize = TensorSpec<1, 64, 256>;
using Input = TensorSpecdims()[2], 3, 32, 32>;
using Output = TensorSpecdims()[2], 100>;

void Cifar100CNN::set_tensor_addresses() {
    inference->set_tensor_address("input", gpu_input);
    inference->set_tensor_address("output", gpu_output);
}

void Cifar100CNN::preprocess(std::vector::const_iterator input,
                             size_t batch_size) {
    size_t img_size = InputImg::total_size();

#pragma omp parallel for
    for (size_t i = 0; i < batch_size; ++i) {
        Cifar100Processor::process(*(input + i), input_buffer + i * img_size);
    }
}

void Cifar100CNN::postprocess(std::vector<int>::iterator output,
                              size_t batch_size) {
    size_t res_size = OutputRes::total_size();

#pragma omp parallel for
    for (size_t i = 0; i < batch_size; ++i) {
        float* output_buffer_idx = output_buffer + i * res_size;
        int class_id = std::distance(
            output_buffer_idx,
            std::max_element(output_buffer_idx, output_buffer_idx + res_size));
        *(output + i) = class_id;
    }
}

void Cifar100CNN::infer(size_t batch_size) {
    inference->infer([batch_size](nvinfer1::IExecutionContext* context) {
        context->setInputShape(
            "input", nvinfer1::Dims4 {(int64_t) batch_size, 3, 32, 32});
    });
}

auto Cifar100CNN::InputData(size_t batch_size) {
    return cudaMemcpyAsync(gpu_input, input_buffer,
                           sizeof(float) * InputImg::total_size() * batch_size,
                           cudaMemcpyHostToDevice, inference->get_stream());
}

auto Cifar100CNN::OutputData(size_t batch_size) {
    return cudaMemcpyAsync(output_buffer, gpu_output,
                           sizeof(float) * OutputRes::total_size() * batch_size,
                           cudaMemcpyDeviceToHost, inference->get_stream());
}

Cifar100CNN::Cifar100CNN(std::string onnx_path, std::string engine_path,
                         TRTLogger& logger, bool always_rebuild)
    : onnx_path(onnx_path), engine_path(engine_path) {
    auto builder = TRTModelBuilder(logger);
    if (always_rebuild || !(engine = builder.loadFromPlan(engine_path))) {
        engine = builder.buildFromOnnx(
            onnx_path, engine_path,
            [](nvinfer1::IBuilderConfig* config,
               nvinfer1::INetworkDefinition* network,
               nvinfer1::IBuilder* builder) {
                auto profile = builder->createOptimizationProfile();
                const char* inputName = network->getInput(0)->getName();
                auto batch_sizes = BatchSize::dims();
                // [Min, Opt, Max]
                profile->setDimensions(
                    inputName, nvinfer1::OptProfileSelector::kMIN,
                    nvinfer1::Dims4 {(int64_t) batch_sizes[0], 3, 32, 32});
                profile->setDimensions(
                    inputName, nvinfer1::OptProfileSelector::kOPT,
                    nvinfer1::Dims4 {(int64_t) batch_sizes[1], 3, 32, 32});
                profile->setDimensions(
                    inputName, nvinfer1::OptProfileSelector::kMAX,
                    nvinfer1::Dims4 {(int64_t) batch_sizes[2], 3, 32, 32});
                config->addOptimizationProfile(profile);

                // 2. 精度设置：虽然 kFP16 弃用，但在 10.0 中作为 BuilderFlag
                // 依然是生效的（会有警告）
                if (builder->platformHasFastFp16()) {
                    config->setFlag(nvinfer1::BuilderFlag::kFP16);
                }
            });
    }
    inference = TRTPtr(new TRTInference(*engine));

    cudaHostAlloc((void**) &input_buffer, sizeof(float) * Input::total_size(),
                  cudaHostAllocDefault);
    cudaHostAlloc((void**) &output_buffer, sizeof(float) * Output::total_size(),
                  cudaHostAllocDefault);
    cudaMalloc(&gpu_input, sizeof(float) * Input::total_size());
    cudaMalloc(&gpu_output, sizeof(float) * Output::total_size());

    set_tensor_addresses();
}

Cifar100CNN::~Cifar100CNN() noexcept {
    cudaFree(gpu_input);
    cudaFree(gpu_output);
    cudaFreeHost(input_buffer);
    cudaFreeHost(output_buffer);
}

std::vector<int> Cifar100CNN::infer(const std::vector& input,
                                    size_t batch_size) {
    size_t input_size = input.size();
    std::vector<int> res(input_size);

    auto batch_sizes = BatchSize::dims();
    if (batch_size == 0) {
        // 使用默认的最优 batch size
        batch_size = batch_sizes[1];
    } else if (batch_size > batch_sizes[2]) {
        // 若超过则使用最大 batch size
        batch_size = batch_sizes[2];
    }

    size_t batches =
        input_size / batch_size + (((input_size % batch_size) == 0) ? 0 : 1);

    for (size_t i = 0; i < batches; ++i) {
        size_t cur_batch_size =
            std::min(batch_size, input_size - i * batch_size);
        preprocess(input.cbegin() + i * batch_size, cur_batch_size);
        InputData(cur_batch_size);
        infer(cur_batch_size);
        OutputData(cur_batch_size);
        cudaStreamSynchronize(inference->get_stream());
        postprocess(res.begin() + i * batch_size, cur_batch_size);

        std::cout << std::format("batch {} with size {} finished\n", i,
                                 cur_batch_size);
    }

    return res;
}

最终测试

使用之前 Pytorch 导出的数据库和元数据进行测试，用 C++读取 JSON 元数据并用 OpenCV 读取图片，通过上面写的 Cifar100 类进行推理，batch size 设置为 128，最终成功率为 69.32%，与训练时基本一致，说明以上各流程没有明显问题。

TensorRT部署YOLO V8模型

2026-04-09T16:00:00.000Z

本文介绍我使用TensorRT部署Yolo模型并实现读取摄像头实时目标检测的过程。

本文源码仓库在这里。

基于 TensorRT-YOLO 部署

安装 TensorRT-YOLO

使用开源框架 TensorRT-YOLO 进行模型的部署。将源码下载下来，正确配置 TensorRT 的安装路径之后可以直接编译成功。

不过这个项目的的导出写得不是很好，明明安装目标时有 EXPORT 却没有安装，最后是自己手动设置的变量。我把缺失的安装部分给它加上了，之后可以正常 find_package 然后链接一下库就完成所有配置了。

准备 YOLO 模型

使用 Python 安装 ultralytics 之后直接导出 yolov8n 模型到 ONNX 格式。之后使用上面 TensorRT-YOLO 项目配套的 trtyolo-export 工具可以将 ONNX 直接编译成 engine 格式。

同时会在Yolo模型的后面增加一个Efficient NMS插件的处理层，在GPU端进行低置信框的过滤和NMS处理。

使用 OpenCV 读取摄像头

这里使用的摄像头之前已经标定过了，根据参数从摄像头读取图像数据后进行畸变校正后传出。

参数保存在 yml 文件中，通过 cv::FileStorage 读取并解析。

读取并校正代码如下：

cv::Mat YoloCamera::read_frame() {
    cv::Mat frame;
    cap >> frame;

    if (frame.empty()) {
        throw FrameCaptureException();
    }

    cv::Mat undist_frame;
    cv::undistort(frame, undist_frame, calib_res.camera_matrix,
                  calib_res.dist_coeffs);

    return undist_frame;
}

YOLO 实时目标监测

将 TensorRT-YOLO 提供的推理参数选项保存在 yml 文件中，创建模型时读取文件再设置。

void YoloCamera::read_infer_option(const std::string& option_file) {
    cv::FileStorage fs(option_file, cv::FileStorage::READ);
    if (!fs.isOpened()) {
        throw FileNotFoundException(CONFIG_FILE);
    }
    cv::FileNode node;
    if ((node = fs["device_id"]).isInt()) {
        infer_option.setDeviceId((int) node);
    }
    if ((node = fs["cuda_memory"]).isInt()) {
        if ((int) node)
            infer_option.enableCudaMem();
    }
    if ((node = fs["managed_memory"]).isInt()) {
        if ((int) node)
            infer_option.enableManagedMemory();
    }
    if ((node = fs["enable_swap_rb"]).isInt()) {
        if ((int) node)
            infer_option.enableSwapRB();
    }
    if ((node = fs["enable_performance_report"]).isInt()) {
        if ((int) node)
            infer_option.enablePerformanceReport();
    }
    if ((node = fs["input_dimensions"]).isSeq()) {
        std::vector<int> dims;
        node >> dims;
        if (dims.size() == 2) {
            infer_option.setInputDimensions(dims[0], dims[1]);
        }
    }
}

预训练的 yolov8 模型使用的是 coco 数据集，搜索其类型名称保存在 yml 文件中，用于后续可视化时的标注。

将 OpenCV 校正过的图像用 TensorRT-YOLO 提供的图片类封装一下，直接进行推理。

推理完成后根据结果使用 OpenCV 绘制简单的框并加上 label，再显示出来。

可视化代码如下：

cv::Mat YoloCamera::visualize(const cv::Mat& frame,
                              const trtyolo::DetectRes& res) const {
    cv::Mat image = frame.clone();
    for (size_t i = 0; i < res.num; ++i) {
        const auto& box = res.boxes[i];
        int cls = res.classes[i];
        float score = res.scores[i];
        const auto& label = labels[cls];
        std::string label_text = label + " " + cv::format("%.3f", score);

        // 绘制矩形和标签
        int base_line;
        cv::Size label_size = cv::getTextSize(
            label_text, cv::FONT_HERSHEY_SIMPLEX, 0.6, 1, &base_line);
        cv::rectangle(image, cv::Point(box.left, box.top),
                      cv::Point(box.right, box.bottom),
                      cv::Scalar(251, 81, 163), 2, cv::LINE_AA);
        cv::rectangle(image, cv::Point(box.left, box.top - label_size.height),
                      cv::Point(box.left + label_size.width, box.top),
                      cv::Scalar(125, 40, 81), -1);
        cv::putText(image, label_text, cv::Point(box.left, box.top),
                    cv::FONT_HERSHEY_SIMPLEX, 0.6, cv::Scalar(253, 168, 208),
                    1);
    }
    return image;
}

手写 C++代码进行部署

基于之前写的 Cifar100CNN 的类修改，去掉动态批大小之后只需要关注预处理和后处理。

介于要适配两种模型，一种支持 TensorRT 的官方插件 Efficient NMS，所以要根据模型类型来修改分配显存和输入输出绑定。加入了成员变量 enable_efficient_nms 来标记模型类型。

和使用 TensorRT-YOLO 的版本一样，也加入了读取 labels 的功能。

class YoloV8n {
private:
    std::string onnx_path;
    std::string engine_path;

    TRTPtr engine;
    TRTPtr inference;

    // 模型是否启用了EfficientNMS插件
    bool enable_efficient_nms;

    float* input_buffer;
    float* output_buffer;

    size_t input_size;
    size_t output_size;

    void* gpu_input;
    void* gpu_output;

    std::vector labels;
    void read_labels(const std::string& file_path);

    void set_tensor_addresses();

    std::vector decode_output();

    void apply_nms(std::vector& results,
                   float iou_threshold = 0.5f);

    void apply_deletterbox(std::vector& results);

    std::vector decode_output_nms();

    void preprocess(const cv::Mat& input);
    std::vector postprocess();
    void infer();
    auto InputData();
    auto OutputData();

public:
    YoloV8n(std::string onnx_path, std::string engine_path, TRTLogger& logger,
            bool enable_efficient_nms_plugin, bool always_rebuild = false);
    ~YoloV8n() noexcept;
    std::vector infer(const cv::Mat& input);
    cv::Mat visualize(const cv::Mat& input,
                      const std::vector& results);
};

Yolo 预处理

目前的摄像头分辨率是 1280x720，而 YoloV8 的最佳分辨率一般为 640x640，需要进行变换，使用 letterbox 方法进行。即先进行缩放，比如 1280x720 缩放为 640x360，空白部分补上黑边。

template 
struct LetterBox {
    static cv::Mat process(const cv::Mat& input) {
        constexpr int input_width = InputSpec::dims()[0];
        constexpr int input_height = InputSpec::dims()[1];
        constexpr int output_width = OutputSpec::dims()[0];
        constexpr int output_height = OutputSpec::dims()[1];

        constexpr float scale =
            std::min(static_cast<float>(output_width) / input_width,
                     static_cast<float>(output_height) / input_height);

        constexpr int resized_width = static_cast<int>(input_width * scale);
        constexpr int resized_height = static_cast<int>(input_height * scale);

        constexpr int x_offset = (output_width - resized_width) / 2;
        constexpr int y_offset = (output_height - resized_height) / 2;

        cv::Mat resized;
        cv::resize(input, resized, cv::Size(resized_width, resized_height));

        cv::Mat output =
            cv::Mat::zeros(output_height, output_width, input.type());

        cv::Rect roi(x_offset, y_offset, resized_width, resized_height);
        resized.copyTo(output(roi));

        return output;
    }
};

Yolo 后处理

Yolo 的后处理相对要复杂一些。

原始的 Yolo 模型的输出结果为 (1, 84, 8400)，及总共 8400 个框，每个框 84 个数据，其中 0～1 为中心点坐标，2～3 为宽和高，4～83 为各个类别的置信率。

Yolo 的后处理主要包括三个步骤，首先是从 80 个类型置信率中得到最大的值作为检测结果，其置信率作为该框的置信率，并过滤到低置信率的框，一般阈值为 0.25；之后是过滤掉重复框，因为 Yolo 检测中一个物体可能有很多个重复框，需要使用 NMS 算法进行去重；之后还需要将框转换回原图片。

解析推理结果并过滤

解析的部分比较简单，唯一需要注意的就是结果的形状为 (84, 8400) 而不是 (8400, 84)，也就是说在内存中是先 8400 个框的第一个元素，然后 8400 个框的第二个元素这样排列的。也就是说一个框的 84 个元素之间都隔着 8399 个元素。

这种跳跃式读取实际上是比较慢的，因为局部性较差，CPU 缓存不命中。一种方法是转置，但是转置其实也很慢，因为需要新分配一块内存再复制一遍。之后还需要再进行过滤，所以虽然写法上看似简洁但性能较差。

所以最终还是选择了跳跃式读取的同时进行过滤，仅将合格的部分记录下来统一读取框的位置，再向外输出。

std::vector YoloV8n::decode_output() {
    std::vector results;
    // 预留50个结果的空间，避免频繁扩容
    results.reserve(50);
    constexpr int COLS = OutputRes::dims()[1];
    constexpr int ROWS = OutputRes::dims()[0];

    // 过滤低置信度的检测结果，并提取边界框和类别信息
    // 采用跳跃式访问，而非先转置输出矩阵，避免不必要的内存复制
    // 使用OpenMP进行并行处理，提升性能
#pragma omp parallel
    {
        // 每个线程创建自己的局部 vector
        std::vector local_results;
        local_results.reserve(10);  // 预留少量空间

#pragma omp for nowait  // nowait 减少同步开销
        for (size_t i = 0; i < COLS; ++i) {
            float max_score = 0;
            int class_id = -1;
            for (size_t j = 4; j < ROWS; ++j) {
                float s = output_buffer[j * COLS + i];
                if (s > max_score) {
                    max_score = s;
                    class_id = j - 4;
                }
            }
            if (max_score > 0.25f) {
                float x_center = output_buffer[0 * COLS + i];
                float y_center = output_buffer[1 * COLS + i];
                float width = output_buffer[2 * COLS + i];
                float height = output_buffer[3 * COLS + i];
                cv::Rect box(x_center - width / 2, y_center - height / 2, width,
                             height);
                local_results.push_back({class_id, max_score, box});
            }
        }

// 关键区域：将局部结果安全地合并到主结果
#pragma omp critical
        {
            results.insert(results.end(), local_results.begin(),
                           local_results.end());
        }
    }

    return results;
}

后来实现了批次处理，因为跳跃访问的主要问题是缓存不明中，CPU 读取连续内存的能力是最强的。所以后面尝试进行优化，将框再进行分批处理，一次同时处理 16 个框，读取时每一次是读取连续的 16 个元素，再统一进行比较，最后同意过滤。

但是这个写法也有问题，一次读取 16 个元素，所以加入了局部数组作为存储，又加了一层循环，代码相对更复杂一些。最终经过测试，在开启多线程优化的前提下两个版本速度相差不多，但是当线程数为 2 和 16 时，原版性能都显著高于优化后的版本。可能是 84*8400 这个数据量仍然在 CPU 的预取承受范围内，所以 CPU 自动进行的优化便已经很快了，而我家的优化反而因为多了一层循环或其他原因 CPU 更难进行优化所以更慢。

NMS 算法实现

NMS 算法本身不算复杂，这里实现为先进行排序，然后从前至后逐个检查 IoU 即重叠率，重叠率高于一定阈值并且是相同类别，则将删除。为优化性能，使用懒删除，为方便将置信率作为标记，被标记要删除的框则将其置信率设为负值，最后通过 erase_if 统一删除。

static inline float calculate_iou(const cv::Rect& a, const cv::Rect& b) {
    float inter_area = (a & b).area();
    if (inter_area <= 0)
        return 0.f;
    float res =
        inter_area / static_cast<float>(a.area() + b.area() - inter_area);
    return res;
}

void YoloV8n::apply_nms(std::vector& candidates,
                        float iou_threshold) {
    if (candidates.empty())
        return;

    // 按置信率排序
    std::sort(candidates.begin(), candidates.end(),
              [](const YoloDetectResult& a, const YoloDetectResult& b) -> bool {
                  return a.confidence > b.confidence;
              });

    // 将要被删除的框的置信率设为负值，避免额外的 bool 标记空间
    for (size_t i = 0; i < candidates.size(); ++i) {
        if (candidates[i].confidence < 0)
            continue;  // 已经被标记删除

        for (size_t j = i + 1; j < candidates.size(); ++j) {
            if (candidates[j].confidence < 0)
                continue;

            if (candidates[i].class_id == candidates[j].class_id) {
                if (calculate_iou(candidates[i].box, candidates[j].box) >
                    iou_threshold) {
                    // 利用置信率字段作为标记位，负值表示被删除
                    candidates[j].confidence = -1.0f;
                }
            }
        }
    }

    // 删除被标记的框，即置信率被设为负值的项
    std::erase_if(candidates, [](const auto& d) { return d.confidence < 0; });
}

启用 EfficientNMS 插件后的结果解析

当启用了 TensorRT 官方的 Efficient NMS 插件之后，过滤低置信框和 NMS 操作可以在 GPU 直接完成，输出结果变为四个 tensor，num_dets int32(1, 1)，det_boxes float32(1, 100, 4)，det_classes int32(1, 100)，det_scores float32(1, 100)，分别是检测到的目标，目标的框，目标的类别和目标的置信率。

设计了一个类用于存储这四个数据，便于管理和表示，至于解析便很简单了，只需要将指向结果缓存区的指针转为该类型，便可直接读取数据，然后直接输出即可。

struct YoloDetectResultNMS {
    int32_t num_dets;
    float det_boxes[100][4];
    float det_scores[100];
    int32_t det_classes[100];
};

std::vector YoloV8n::decode_output_nms() {
    auto output = reinterpret_cast(output_buffer);
    static_assert(sizeof(YoloDetectResultNMS) == (1 + 100 * 4 + 100 + 100) * 4);

    std::vector results;
    results.reserve(output->num_dets);
    for (int i = 0; i < output->num_dets; ++i) {
        int class_id = static_cast<int>(output->det_classes[i]);
        float confidence = output->det_scores[i];
        float x1 = output->det_boxes[i][0];
        float y1 = output->det_boxes[i][1];
        float x2 = output->det_boxes[i][2];
        float y2 = output->det_boxes[i][3];
        cv::Rect box(x1, y1, x2 - x1, y2 - y1);
        results.push_back({class_id, confidence, box});
    }

    return results;
}

DeLetterBox 实现

上面提到，由于预处理时将图片胫骨 LetterBox 算法进行了缩放，传回的结果中的坐标也是按照缩放后的坐标系。要将框映射到原图像中，需要进行 DeLetterBox，算法很简单，只需要简单的线性代数相关知识就很容易理解这就是一个仿射变换，当然哪怕没有也很容易理解。

template 
struct DeLetterBox {
    static cv::Rect process(const cv::Rect& input) {
        constexpr int input_width = InputSpec::dims()[0];
        constexpr int input_height = InputSpec::dims()[1];
        constexpr int output_width = OutputSpec::dims()[0];
        constexpr int output_height = OutputSpec::dims()[1];

        constexpr float scale =
            std::min(static_cast<float>(output_width) / input_width,
                     static_cast<float>(output_height) / input_height);

        constexpr int resized_width = static_cast<int>(input_width * scale);
        constexpr int resized_height = static_cast<int>(input_height * scale);

        constexpr int x_offset = (output_width - resized_width) / 2;
        constexpr int y_offset = (output_height - resized_height) / 2;

        return cv::Rect((input.x - x_offset) / scale,
                        (input.y - y_offset) / scale, input.width / scale,
                        input.height / scale);
    }
};

最终的后处理

根据是否启用了 Efficient NMS 插件选择不同的解析函数，并进行 NMS。最后同意 DeLetterBox 后返回结果。

std::vector YoloV8n::postprocess() {
    std::vector results;
    if (enable_efficient_nms) {
        results = decode_output_nms();
    } else {
        results = decode_output();
        apply_nms(results, 0.45f);
    }
    apply_deletterbox(results);
    return results;
}

绑定输入输出

由于显存如何分配是根据模型的结构决定的，和绑定输入输出耦合度高，因此将显存分配和绑定放到一起。

输入没有区别都是 (1, 3, 640, 640) 的图片，tensor 名称为 images，输出要根据模型类型进行绑定。

原始的 Yolo 输出格式为 (1, 84, 8400)，tensor 名称为 output0。

而使用了 Efficient NMS 的则变为四个 tensor 输出，上面已经介绍过。为了方便分配以及内存拷贝，分配显存时相当于直接分配一个 YoloDetectResultNMS 对象，使用取地址符而不是手动偏移保证地址计算没有错误，然后绑定即可。

void YoloV8n::set_tensor_addresses() {
    // 分配显存和内存，并绑定输入缓冲区地址
    input_size = sizeof(float) * InputImg::total_size();
    cudaHostAlloc((void**) &input_buffer, input_size, cudaHostAllocDefault);
    cudaMalloc(&gpu_input, input_size);
    inference->set_tensor_address("images", gpu_input);

    // 根据是否启用EfficientNMS插件，分配不同的输出缓冲区，并绑定输出地址
    if (enable_efficient_nms) {
        output_size = sizeof(YoloDetectResultNMS);
    } else {
        output_size = sizeof(float) * OutputRes::total_size();
    }

    cudaHostAlloc((void**) &output_buffer, output_size, cudaHostAllocDefault);
    cudaMalloc(&gpu_output, output_size);

    if (enable_efficient_nms) {
        inference->set_tensor_address(
            "num_dets",
            &(reinterpret_cast(gpu_output)->num_dets));
        inference->set_tensor_address(
            "det_boxes",
            &(reinterpret_cast(gpu_output)->det_boxes));
        inference->set_tensor_address(
            "det_scores",
            &(reinterpret_cast(gpu_output)->det_scores));
        inference->set_tensor_address(
            "det_classes",
            &(reinterpret_cast(gpu_output)->det_classes));
    } else {
        inference->set_tensor_address("output0", gpu_output);
    }
}

构造函数输入输出推理

使用 output_size 和 input_size 两个成员变量存储输入输出的数据大小，避免每次都手动计算，传输数据的部分直接这两个变量来指定传输的数据量。

void YoloV8n::infer() {
    inference->infer();
}

auto YoloV8n::InputData() {
    return cudaMemcpyAsync(gpu_input, input_buffer, input_size,
                           cudaMemcpyHostToDevice, inference->get_stream());
}

auto YoloV8n::OutputData() {
    return cudaMemcpyAsync(output_buffer, gpu_output, output_size,
                           cudaMemcpyDeviceToHost, inference->get_stream());
}

YoloV8n::YoloV8n(std::string onnx_path, std::string engine_path,
                 TRTLogger& logger, bool enable_efficient_nms_plugin,
                 bool always_rebuild)
    : onnx_path(onnx_path),
      engine_path(engine_path),
      enable_efficient_nms(enable_efficient_nms_plugin) {
    auto builder = TRTModelBuilder(logger);
    if (always_rebuild || !(engine = builder.loadFromPlan(engine_path))) {
        engine = builder.buildFromOnnx(
            onnx_path, engine_path,
            [](nvinfer1::IBuilderConfig* config,
               nvinfer1::INetworkDefinition* network,
               nvinfer1::IBuilder* builder) {
                // 2. 精度设置：虽然 kFP16 弃用，但在 10.0 中作为 BuilderFlag
                // 依然是生效的（会有警告）
                if (builder->platformHasFastFp16()) {
                    config->setFlag(nvinfer1::BuilderFlag::kFP16);
                }
            });
    }
    inference = TRTPtr(new TRTInference(*engine));

    set_tensor_addresses();

    read_labels(std::string(PACKAGE_ROOT_DIR) + "/config/labels.yml");

    std::cout << std::format(
                     "Model initialized:\nONNX: {}\nEngine: {}\nEfficient NMS "
                     "Plugin: {}\nAlways rebuild: {}",
                     onnx_path, engine_path,
                     enable_efficient_nms ? "Enabled" : "Disabled",
                     always_rebuild ? "True" : "False")
              << std::endl;
}

本地编译Emacs

2026-03-09T16:00:00.000Z

Emacs 支持很多编译时可选的特性，当从包管理器或其他预编译的二进制版本无法满足你的需求时，就需要自己在本地编译 Emacs 的源码。本篇文章记录编译 Emacs 源码的过程。

本文介绍流程在 Docker 创建的纯净的 Ubuntu 24.04 容器中进行实际操作，仅给出 Ubuntu24.04 中的命令，其余操作系统仅供参考。

获取源码

第一步是获取源码，我们可以直接从其官网上获取其源码，我们选择当前最新版本 30.2 作为后续使用的源码。

我们将其解压，即可开始编译。

配置编译选项及依赖

Emacs 的源码使用 Makefile 作为构建系统，使用 Autotools 实现自动化。文档是用的 makeinfo 需要安装 texinfo 编译前先安装基础编译工具链。通过以下命令安装：

1	`sudo apt install build-essential autoconf texinfo`

之后我们就可以运行编译脚本了，在源码根目录运行 ./configure 命令，这会检查你的环境依赖并生成最终的 Makefile，并且会显示最终被启用的特性列表。

如果出现以下错误：

checking for X... no
checking for X... false
configure: error: You seem to be running X, but no X development libraries
were found.  You should install the relevant development files for X
and for the toolkit you want, such as Gtk+ or Motif.  Also make
sure you have development files for image handling, i.e.
tiff, gif, jpeg, png and xpm.
If you are sure you want Emacs compiled without X window support, pass
  --without-x
to configure.

这表示 Emacs 将会不支持图形界面，只有命令行界面，同时也会不支持处理 png 等图片格式。原因是没有检测到系统中有图形界面相关的开发库，如果是在容器中进行编译这是必然的，因为容器内不会安装图形界面，自然也不会有相关的开发库。但哪怕是在桌面系统中，也可能会出现这个问题，因为一般桌面只会安装运行库，而源码编译需要开发库，在 Ubuntu 中即 -dev 后缀的库。

在 Linux 系统上我们一般使用 GTK 作为图形库，我们安装 GTK3 的开发库，以及一些处理图片所需的库，以及 GnuTLS，Emacs 内置的网络模块依赖于它。以及 ncurses 开发的库，用于提供终端支持。

1	`sudo apt install libgtk-3-dev libgif-dev libxpm-dev libgnutls28-dev libncurses-dev`

上述即编译 Emacs 的必须库，确保都安装之后我们再次运行 configure 命令，运行成功后，我们查看末尾当前特性列表的开启情况：

Configured for 'x86_64-pc-linux-gnu'.

  Where should the build process find the source code?    .
  What compiler should emacs be built with?               gcc -g3 -O2
  Should Emacs use the GNU version of malloc?             no
    (The GNU allocators don't work with this system configuration.)
  Should Emacs use a relocating allocator for buffers?    no
  Should Emacs use mmap(2) for buffer allocation?         no
  What window system should Emacs use?                    x11
  What toolkit should Emacs use?                          GTK3
  Where do we find X Windows header files?                Standard dirs
  Where do we find X Windows libraries?                   Standard dirs
  Does Emacs use -lXaw3d?                                 no
  Is Emacs being built for Android?                       no
  Does Emacs use the X Double Buffer Extension?           yes
  Does Emacs use -lXpm?                                   yes
  Does Emacs use -ljpeg?                                  yes
  Does Emacs use -ltiff?                                  yes
  Does Emacs use a gif library?                           yes -lgif
  Does Emacs use a png library?                           yes -lpng16
  Does Emacs use -lrsvg-2?                                no
  Does Emacs use -lwebp?                                  yes
  Does Emacs use -lsqlite3?                               no
  Does Emacs use cairo?                                   yes
  Does Emacs use -llcms2?                                 no
  Does Emacs use imagemagick?                             no
  Does Emacs use native APIs for images?                  no
  Does Emacs support sound?                               yes
  Does Emacs use -lgpm?                                   no
  Does Emacs use -ldbus?                                  yes
  Does Emacs use -lgconf?                                 no
  Does Emacs use GSettings?                               yes
  Does Emacs use a file notification library?             yes (inotify)
  Does Emacs use access control lists?                    no
  Does Emacs use -lselinux?                               yes
  Does Emacs use -lgnutls?                                yes
  Does Emacs use -lxml2?                                  no
  Does Emacs use -lfreetype?                              yes
  Does Emacs use HarfBuzz?                                yes
  Does Emacs use -lm17n-flt?                              no
  Does Emacs use -lotf?                                   no
  Does Emacs use -lxft?                                   no
  Does Emacs use -lsystemd?                               no
  Does Emacs use -ltree-sitter?                           no
  Does Emacs use the GMP library?                         yes
  Does Emacs directly use zlib?                           yes
  Does Emacs have dynamic modules support?                yes
  Does Emacs use toolkit scroll bars?                     yes
  Does Emacs support Xwidgets?                            no
  Does Emacs have threading support in lisp?              yes
  Does Emacs support the portable dumper?                 yes
  Does Emacs support legacy unexec dumping?               no
  Which dumping strategy does Emacs use?                  pdumper
  Does Emacs have native lisp compiler?                   no
  Does Emacs use version 2 of the X Input Extension?      yes
  Does Emacs generate a smaller-size Japanese dictionary? no

这是一个很基础的 Emacs，很多特性没有支持，这里介绍一下比较重要的几个特性，其余特性保持默认即可，已经是推荐选项。

图形系统

首先是图形系统，目前使用 X11 和 Gtk3，如果你正在使用 X11 则不用管，但如果你只用 Wayland，并且希望 Emacs 可以原生运行在 Wayland 上，可以通过加入--with-pgtk参数设置。同时需要安装 Wayland 的开发库，之前安装 GTK 开发库时已经作为依赖被安装。结果显示如下表示成功。

1	`What window system should Emacs use? pgtk`

上面 Xpm 和 X Double Buffer Extension 都是 X11 下才会生效的特性，当使用 PGTK 时会自动关闭，无需在意。

图片支持

Emacs 原生支持处理图片，你可以看到上面已经包含了 gif，png，jpeg，tiff，webp 等格式的原生支持都一起用，但是 -lrsvg-2 显示为 no 表示矢量图形即 svg 渲染未启用，这是由于系统中缺少这个开发库，安装后一般会自动启用，这里建议安装并启用。

而 -llcms2 也是未启用，该库与图片色彩管理相关，主要影响图片浏览。该特性以来满足时默认开启，建议安装以启用。

1	`sudo apt install librsvg2-dev liblcms2-dev`

在之前（Emacs 26 以前），往往使用 ImageMagick 进行图片相关的处理，如缩放等，但是在新版本中推荐不使用它而是使用各种原生 api，比如上面的 libjpeg，libpng 等，以及 Cairo 来替代。Cairo 是一个跨平台的开源 2D 矢量图形渲染库，建议使用它而非 ImageMagick，安装 gtk 时一般已经安装了它的开发库，确保上面 -lcairo 为 yes。而

在 Linux 上并没有统一的图片 API 而是通过一个个动态库实现，因此 native APIs for images 显示为 no，这是正常的，无需理会。

原生编译

在 Emacs 28 之后，添加了一项新的特性成为原生编译（Native Comp），用于 ELisp 的运行。ELisp 原先是先编译为字节码再通过虚拟机运行。而原生编译则是通过 libgccjit 将 ELisp 的字节码直接转化为机器指令，即 AOT。强烈建议将其开启。

首先安装 libgccjit，建议安装与系统默认版本 gcc 相同版本的。之后运行 configure，加入如下参数。

1 2	`sudo apt install libgccjit-13-dev ./configure --with-pgtk --with-native-compilation=aot`

杂项

强烈建议开启 sqlite3 的支持，为一些插件提供数据库支持。如果在系统中安装了 sqlite3 的开发库，该选项将会默认开启。

还有 xml2 的支持，Emacs 内置的一些功能，如浏览器，RSS 阅读器等功能，会需要 xml 解析功能，强烈建议安装相应的开发库，会默认开启。

-lotf 这一项为 no，表示不会使用 libotf 这个库来处理字体，但是我们已经启用了 HaffBuzz，其功能更加强大，即使没有也无需在意。如果系统了安装该开发库，该选项会默认启用，启用了也没有坏处。

-lsystemd 这一项为 no，如果要启用需要安装对应开发库。启用后可以和 systemd 更好集成，一般没什么用，默认启用。

-ltree-sitter 强烈建议启用，安装对应开发库之后会自动启用。该特性用于 tree-sitter 支持，其用于解析代码的 AST，让 Emacs 可以理解代码的结构，非常重要。

XWidget 相关支持即通过 webkit2gtk 来实现将浏览器嵌入到 Emacs 中，webkit2gtk 非常沉重，且容易导致 Emacs 崩溃，一般没有必要启用。

还有一个参数，虽然不在特性列表上，但是可能会在末尾进行警告，与电子邮件相关。 Emacs 默认使用 movemail，这是一个过时的不安全的 POP3 客户端，Emacs 会推荐你用更安全更现代的来替代它，比如 Gnu Mailutils。一般不必在意，目前主流的 Emacs 邮件客户端这两个都不需要。

其余特性一般要么已经过时，要么没有必要，无需在意。

安装命令：

1	`sudo apt install libsqlite3-dev libotf-dev libsystemd-dev libtree-sitter-dev`

最终列表

Configured for 'x86_64-pc-linux-gnu'.

  Where should the build process find the source code?    .
  What compiler should emacs be built with?               gcc -g3 -O2
  Should Emacs use the GNU version of malloc?             no
    (The GNU allocators don't work with this system configuration.)
  Should Emacs use a relocating allocator for buffers?    no
  Should Emacs use mmap(2) for buffer allocation?         no
  What window system should Emacs use?                    pgtk
  What toolkit should Emacs use?                          GTK3
  Where do we find X Windows header files?                Standard dirs
  Where do we find X Windows libraries?                   Standard dirs
  Does Emacs use -lXaw3d?                                 no
  Is Emacs being built for Android?                       no
  Does Emacs use the X Double Buffer Extension?           no
  Does Emacs use -lXpm?                                   no
  Does Emacs use -ljpeg?                                  yes
  Does Emacs use -ltiff?                                  yes
  Does Emacs use a gif library?                           yes -lgif
  Does Emacs use a png library?                           yes -lpng16
  Does Emacs use -lrsvg-2?                                yes
  Does Emacs use -lwebp?                                  yes
  Does Emacs use -lsqlite3?                               yes
  Does Emacs use cairo?                                   yes
  Does Emacs use -llcms2?                                 yes
  Does Emacs use imagemagick?                             no
  Does Emacs use native APIs for images?                  no
  Does Emacs support sound?                               yes
  Does Emacs use -lgpm?                                   no
  Does Emacs use -ldbus?                                  yes
  Does Emacs use -lgconf?                                 no
  Does Emacs use GSettings?                               yes
  Does Emacs use a file notification library?             yes (inotify)
  Does Emacs use access control lists?                    no
  Does Emacs use -lselinux?                               yes
  Does Emacs use -lgnutls?                                yes
  Does Emacs use -lxml2?                                  yes
  Does Emacs use -lfreetype?                              yes
  Does Emacs use HarfBuzz?                                yes
  Does Emacs use -lm17n-flt?
  Does Emacs use -lotf?                                   yes
  Does Emacs use -lxft?
  Does Emacs use -lsystemd?                               yes
  Does Emacs use -ltree-sitter?                           yes
  Does Emacs use the GMP library?                         yes
  Does Emacs directly use zlib?                           yes
  Does Emacs have dynamic modules support?                yes
  Does Emacs use toolkit scroll bars?                     yes
  Does Emacs support Xwidgets?                            no
  Does Emacs have threading support in lisp?              yes
  Does Emacs support the portable dumper?                 yes
  Does Emacs support legacy unexec dumping?               no
  Which dumping strategy does Emacs use?                  pdumper
  Does Emacs have native lisp compiler?                   yes
  Does Emacs use version 2 of the X Input Extension?      no
  Does Emacs generate a smaller-size Japanese dictionary? no

到此，所有参数配置基本结束。可以进行编译了。

在特性之外，如果要指定安装路径，只需要在 configure 中加入如下参数：

1	`./configure --with-pgtk --with-native-compilation=aot --prefix=/path/to/install`

构建部署

剩下的过程就是构建了，建议使用多线程并行编译加快速度。使用 nproc 命令获取核心数量。构建完成后安装，如果显示权限不足就加上 sudo 或者改到用户目录。

1	`make -j$(nproc) && make install`

使用Pandoc和Latex将Markdown转为漂亮的PDF

2025-06-29T16:00:00.000Z

Pandoc是一个强大的文档转换工具，可以将Markdown文件转换为多种格式，包括PDF。结合Latex，我们可以生成高质量的PDF文档。本文将介绍如何使用Pandoc和Latex将Markdown转换为漂亮的PDF。

前言

Markdown是一种轻量级标记语言，广泛用于编写文档。通常情况下，我们阅读Markdown都是将其转换为网页使用浏览器来阅读，目前绝大多数Markdown阅读器都是采用此种方式。

当我们想要将Markdown文档保存为PDF文件时，如果通过转为HTML再打印为PDF，页面将会显得简陋，比如没有页眉页脚等，难以满足我们的要求。

而Latex是一个非常强大的排版系统，可以将tex文件编译成美观的的PDF文档，非常适合印刷物风格的文档。（当然Word也很好，但是惯用Word的人，大概直接就用Word写了吧。）

我们可以通过Pandoc将Markdown文档转换为latex格式，再使用Latex编译器将其编译成PDF文档。这样可以充分利用Latex的排版能力和Markdown的简洁，生成高质量的PDF文件。对于电脑上有Latex环境的人来说，这是很方便的。

我们可以通过Pandoc将Markdown转为latex再编译，也可以由pandoc自动完成转换和编译直接生成pdf。

如果觉得Pandoc的默认样式不够美观，Pandoc也支持自定义模板。如果要添加一些pandoc原生没有的功能，我们还可以自己编写过滤器，由pandoc调用，进行拓展。

下面将介绍Pandoc的基础用法以及模板Eisvogel的使用和调试。

安装Pandoc

要安装Pandoc，推荐到其Github仓库直接下载。大多数包管理器中都有pandoc但是版本可能较旧。

Pandoc基础用法

pandoc命令行的基础命令如下：

1	`pandoc [options] [input-file]...`

options中常用的主要如下：

-f FORMAT, -r FORMAT --from=FORMAT, --read=FORMAT 指定输入格式FORMAT，如markdown，latex等
-t FORMAT, -w FORMAT --to=FORMAT, --write=FORMAT 指定输出格式FORMAT，如pdf，latex，docx等
-o FILE --output=FILE，指定输出文件名
-s[true|false] --standalone[=true|false] 指定是否生成独立的文档，若生成latex，为true时生成包含preamble，为false时没有。不加该选项则为false，加该选项默认值为true
--pdf-engine=PROGRAM 生成pdf时指定要使用的engine，如果通过latex作为中间媒介，则选择latex的编译器，默认为pdflatex亦可选择使用lualatex，xelatex等
--number-sections 生成的文档中是否自动编号章节，默认为false

例如如果我们有一个Markdown文件example.md，想要将其转换为PDF文件example.pdf，可以使用以下命令：

1	`pandoc -f markdown -t pdf -o example.pdf --pdf-engine=lualatex example.md`

使用Eisvogel模板

用于Pandoc的模板可以到网站Pandoc-Templates上找，其中Eisvogel是一个非常流行的模板，提供了美观的排版和丰富的功能。

要使用模板，只需在Pandoc命令中加入参数--template=FILE，其中FILE是模板文件的路径。

或者，我们也可以将模板文件放到~/.local/share/pandoc/templates（Linux）或~\AppData\Roaming\pandoc\templates（Windows）文件夹中，Pandoc会默认在上面的文件夹中搜索模板文件。

Eisvogel模板提供了两个模板文件，一个.latex一个.beamer，我们要转换latex时使用.latex文件即可。

加上模板，上面的例子就变成了

1	`pandoc -f markdown -t pdf -o example.pdf --pdf-engine=lualatex --template=eisvogel.latex example.md`

Pandoc会通过指定的模板将Markdown文档转换为Latex文档再使用指定的pdf-engine将其编译为pdf。

设置字体

如果照着上面做，但是生成的PDF文件中所有中文字体都是方块，不用惊慌，这是正常的，因为我们没有设置中文字体，而默认的只有英文字体，这些字体中没有中文字符。

要解决这个问题，我们只需要在我们的Markdown文件的Front-matter中指定即可。比如我们要使用Google的Noto CJK系列字体，就可以在Markdown的开头（前面不要加任何东西）加入这几行：

---
CJKmainfont: Noto Serif CJK SC
CJKsansfont: Noto Sans CJK SC
CJKmonofont: Noto Sans Mono CJK SC
---

这样在生成的latex文件中便会设置这些字体为相应的中文字体。其中CJKmainfont即中文正文字体，CJKsansfont即中文无衬线字体，常用于标题，CJKmonofont即中文等宽字体，一般用于一些代码块。

也可以通过此方法指定英文字体和数学字体

mainfont: Libertinus Serif
sansfont: Libertinus Sans
monofont: Libertinus Mono
mathfont: Libertinus Math

其它设置

Eisvogel模板还创建了一些其它的变量，用于控制显示效果，比较常用的如下：

titlepage 是否创建标题页，默认是false
toc-own-page 是否将目录放在单独一页，默认是false
listings-no-page-break 是否禁止在列表中分页，默认为false
header-left 页眉左侧内容，默认为标题
header-center 页眉中间内容，默认为空
header-right 页眉右侧内容，默认为日期
footer-left 页脚左侧内容，默认为作者
footer-center 页脚中间内容，默认为空
footer-right 页脚右侧内容，默认为页码

更具体的列表可以到Eisvogel的README中查看。

使用过滤器

Pandoc支持自定义过滤器。Pandoc的处理过程是先读取解析Markdown文件，生成一个抽象语法树（AST），然后将AST转换为目标格式的文档。我们可以编写过滤器处理AST对象并将其转换为处理后的AST对象或直接生成原始目标片段比如Latex代码。

要调用过滤器，只需在Pandoc命令中加入--filter=PROGRAM选项，其中PROGRAM是过滤器程序的路径，过滤器程序应为可直接执行的程序，比如脚本或二进制。Pandoc更鼓励使用lua语言来编写过滤器，其在与Pandoc一起工作时性能上更有优势，要调用lua过滤器，只需在Pandoc命令中加入--lua-filter=SCRIPTPATH或-L SCRIPTPATH选项，其中SCRIPTPATH是lua脚本的路径。

也可以将程序或脚本放在/pandoc/filters目录下，类似于上面的templates文件夹，该文件夹会被Pandoc默认搜索。

以下将推荐几个常用的过滤器。

pandoc-crossref

pandoc-crossref是一个用于交叉引用的过滤器。原生的Pandoc和Markdown只支持使用链接来引用，无法进行自动编号等任务。而通过使用该过滤器，我们可以在Markdown文档中使用{type:label}的格式创建标记，再使用@type:label的格式来创建引用。在转换为latex时，pandoc-crossref会正确的将这些标记和引用转换为latex中合法的表达式并添加前缀。

比如对于图片可以这样写：

1
2
3

![caption](image.png){#fig:label}

图 @fig:label 显示了一个图片

在最终生成的Latex文档中，fig:label会成为该图片的label，@fig:label会被转换为latex的引用语句\ref{fig:label}。Latex会为其自动编号。

Pandoc默认所使用的Markdown是Pandoc拓展后的格式，表格前后如果有这样一行形似Listing: Listing caption或: Listing caption，那么Listing caption将会成为这个表格的caption。我们也可以将标记放在这一行。

如果要对section使用引用，必须令pandoc启用--number-sections参数，不然没有编号latex无法令引用生效。（在Latex中如果第一个标题不是一级标题，那么Latex会给其加一个前缀0.，如果我们希望使其变为1.，除了修改生成的latex之外可以在front-matter中添加numberSections: true，这样pandoc-crossref会自动处理这种情况，加一个隐式的一级标题。不过如果你想要2.，只能自己再将latex中的1改成2。）

Pandoc-crossref将引用转换为latex的引用时会自动加一个前缀，默认情况下前缀即类型名，比如@fig:label会变成fig.~\ref{fig:label}。如果我们想要更改这个前缀，可以通过在front-matter中设置相应的变量。

下面是一个示例文档，涉及了小节、公式、表格、代码块和图像的引用，并设置了字体和引用的前缀。

---
CJKmainfont: Noto Serif CJK SC
CJKmonofont: Noto Sans Mono CJK SC
CJKsansfont: Noto Sans CJK SC
mainfont: Libertinus Serif
mathfont: Libertinus Math
monofont: Libertinus Mono
sansfont: Libertinus Sans
codeBlockCaptions: true
secPrefix: 小节
tblPrefix: 表格
eqnPrefix: 公式
figPrefix: 图
lstPrefix: 列表
---

# 示例 {#sec:example}

@sec:equation 是一个示例小节，展示了如何在文档中使用公式、表格和代码块。

@sec:table 是一个示例小节，展示了如何在文档中使用表格。

@sec:code-block 是一个示例小节，展示了如何在文档中使用代码块。

## 公式 {#sec:equation}

$$
e = \lim_{x \to \infty} \left( 1 + \frac{1}{x} \right)^x
$$
{#eq:natural-number}

@eq:natural-number 是自然数e的定义。

## 表格 {#sec:table}

| Option | Explanation |
| :--- | :------ |
| `-L SCRIPTPATH` | 使用脚本`SCRIPTPATH` |
| `-F PROGRAM` | 使用程序`PROGRAM` |
: 过滤器相关参数 {#tbl:options}

@tbl:options 展示了与过滤器相关的参数。

## 代码块 {#sec:code-block}

有两种风格的代码块：一般风格和表格风格。

### 一般风格 {#sec:code-block-general-style}

```{#lst:c-hello-world .c caption="C Hello World"}
#include <stdio.h>

int main() {
    printf("Hello, world!");
    return 0;
}
```
@lst:c-hello-world 是C语言的一个简单示例。

> 注意：caption不能省略，否则无法生成正确的引用。

### 表格风格 {#sec:code-block-talbe-style}

在Markdown文档的front-matter中将`codeBlockCaptions`设为`true`可以允许下面的写法，即类似表格的写法：

```cpp
#include <iostream>

int main() {
    std::cout << "Hello, world!" << std::endl;
    return 0;
}
```
: C++ Hello World {#lst:hello-world}

@lst:hello-world 是C++版本的Hello World代码。

## 图 {#sec:figure}

![Pandoc Logo](pandoc.png){#fig:pandoc-logo}

@fig:pandoc-logo 是Pandoc一个流行的非官方的logo，[链接](https://github.com/tarleb/pandoc-logo)。

以下是示例的渲染结果：

更具体的文档可以到pandoc-crossref的官方文档中查看。

diagram

现在很多Markdown解释器都支持在文档中插入Mermaid和Plantuml来绘制各种类型的图表。由于latex本身并不能渲染这些类型的图表，所以我们需要其他方法将这些图表放进latex中。

最简单的方法自然是先将图表渲染为图片，再插入文档中，之后便与一般图片无异。Pandoc已经有不少这一类的过滤器，这里介绍其中一个：diagram.

该过滤器支持多种图表格式，包括Mermaid，Plantuml，TikZ，GraphViz，Asymptote和cetz。

它会将这些类型的代码块通过相对应的工具渲染之后将渲染结果插入原位置。

首先我们下载它的最新的release版本，将其中diagram.lua文件复制到filters文件夹下面即可。

这里主要介绍Mermaid。

在我之前的一篇文章CMake基础教程也曾画过一张简单的Mermaid流程图，这里以它为例：

flowchart LR    A[源代码] --> |预处理| B[处理后源代码]    B --> |编译器编译| C[汇编]    C --> |汇编器编译| D[目标文件]    D --> E[链接器]    F[其他目标文件] --> E    G[库文件] --> E    E --> |链接| H[可执行文件或库文件]

首先，该过滤器本身并不执行写入文件，也就说生成的图片并不会被保存，如果生成的是latex，那么最终我们只会获得一个指向不存在文件的链接。所以我们必须在pandoc命令中添加一个参数--extract-media=DIR，其中DIR是图片被保存的文件夹。如果是HTML的话，则可以使用参数--embed-resources。（不过要html有大把的解释器可以直接保存HTML文件，你大概不会用pandoc）

其次，生成的图片的文件名默认是hash值，毫无辨识度，我们可以在文档中指定其将会生成的文件名。

最后，我们还可以在文档中指定图表的caption和label。如果我们想要将其和pandoc-crossref配合使用，那么我们可以将label指定为fig:label的格式，后面引用就与原本的没有区别。

这里根据上面的Mermaid流程图写一个示例：

---
CJKmainfont: Noto Serif CJK SC
CJKmonofont: Noto Sans Mono CJK SC
CJKsansfont: Noto Sans CJK SC
figPrefix: 图
mainfont: Libertinus Serif
mathfont: Libertinus Math
monofont: Libertinus Mono
sansfont: Libertinus Sans
---

# C/C++的编译过程 {#sec:cc-compilation-process}

C/C++的编译过程通常如下：

```{.mermaid filename="cc-compile-process-flowchart" caption="C/C++的编译流程图" #fig:cc-compile-process}
flowchart LR
    A[源代码] --> |预处理| B[处理后源代码]
    B --> |编译器编译| C[汇编]
    C --> |汇编器编译| D[目标文件]
    D --> E[链接器]
    F[其他目标文件] --> E
    G[库文件] --> E
    E --> |链接| H[可执行文件或库文件]
```

@fig:cc-compile-process 显示了C/C++的编译流程图。

这里我们只能是会用一般风格来设置代码块的属性，因为diagram.lua的加入表格风格的写法会失效。这里filename的值即保存的文件名，caption用于设置caption，而label的设置则是直接使用了pandoc-crossref的写法，也可以使用label属性显示设置，最终的效果是一样的。

要对其引用，则就像之前一样使用@fig:cc-compile-process即可。

这是渲染效果图：

CMake专题教程-导入导出

2025-05-16T14:00:00.000Z

本文将介绍如何直接导入二进制文件，或导出项目，使得其他项目可以通过CMake的find_package直接导入我们的项目并基于其开发。

虽然CMake已经是事实上的标准，但我们有时还是会遇到只有二进制和头文件还没有模组文件和配置文件的情况（比如windows下我们通过cmake使用EasyX时就只能手动导入）。这时我们可以通过cmake将其导入，使其成为一个IMPORTED目标。

而实际上，库的配置文件就是一个cmake脚本，其可以将库导入成为导入库目标。find_package会找到这些配置文件并运行。

现在我们将先介绍如何导入，这部分比较简单。之后介绍如何导出项目。

导入

导入分为两种情况，导入可执行文件和导入库。一下将分别介绍。

导入可执行文件

导入可执行文件也使用add_executable命令，语法如下

1	`add_executable( IMPORTED [GLOBAL])`

默认情况下，导入目标仅在当前和子文件夹中生效，要使其全局生效，可以在最后添加GLOBAL关键字。

创建导入目标之后，要为其设置可执行文件的路径，一般直接设置其IMPORTED_LOCATION属性的值（需要绝对路径，我们可以使用cmake一些变量的值构建出来）。

1	`set_target_properties(<target> PROPERTIES IMPORTED_LOCATION path/to/myexe)`

导入的可执行目标在add_custom_command()一类的命令中引用比较方便，这些命令需要需要一个可执行文件来进行一些操作，比如调用clang-format对头文件进行排版。

导入库

导入库和导入可执行文件差不多，也是先创建导入目标再设置相应属性的值。

1	`add_library( SHARED\|STATIC IMPORTED [GLOBAL])`

设置IMPORTED_LOCALTION属性的值以使cmake找到该库文件。

在Windows平台，动态库dll还需要导入库方可链接，导入库的后缀通常为.lib，导入库的位置通过IMPORTED_IMPLIB属性指定。

导出

导出通常是导出库。CMake的 install 命令提供了相应的支持，可以在安装库的同时生成导出目标，之后我们可以安装该导出目标。这个导出目标安装结果是一个CMake脚本文件，用于导入该库（即创建导入库）。

之后为了使CMake可以便捷的找到这些导出目标，我们还需要一个配置文件用于包含这些CMake脚本，这个配置文件通常由模板生成，我们需要创建一个模板文件，用CMake填充，并将生成的完整文件一同安装。

除此之外，我们在创建目标时还需要考虑到在构建过程中和被导入时的包含目录是不同的，所以我们在给目标添加包含目录时要添加两个不同情况下的路径。

包含目录

以下面的语句为例。

target_include_directories(
    demo
    PUBLIC
        "$"
        "$"
)

$<...> 称作生成器表达式，它们在构建时会被替换为相应的值。我们添加了两个生成器表达式

$ ：用于指定构建过程中的包含目录，不能像之前那样使用相对路径，但我们可以通过 CMAKE_CURRENT_SOURCE_DIR 这个变量获取当前 CMakeLists.txt 文件所在的路径，再相对这个路径进行指定。
$ ：用于指定安装后的包含目录，可以使用相对路径，相对于 CMAKE_INSTALL_PREFIX 。

不要忘记将公开的头文件也安装到指定位置。

导出目标

我们在使用 install 命令安装目标时，可以通过 EXPORT 参数同时创建导出目标，命名习惯是 libraryName-targets 。命令类似下面

install(
    TARGETS demo
    EXPORT demo-targets
)

我们可以在多个 install 命令中使用同一个 EXPORT 名称，这样会将多个目标导出到同一个导出目标中。

之后我们需要安装导出目标，这样会将生成的导入脚本安装到指定位置，其他项目就可以通过运行这些CMake脚本创建导入目标。命令如下

install(
    EXPORT demo-targets
    FILE demo-targets.cmake
    NAMESPACE demo::
    DESTINATION lib/cmake/demo
)

我们使用install(EXPORT ...) 命令来安装导出目标，FILE 参数指定导出目标的脚本文件名。

NAMESPACE 用于指定命名空间，包含在该导出目标中的目标导入后其名称前会被加上命名空间作为前缀，一般使用C++的命名习惯，使用两个冒号 :: 作为间隔。导入后像这样引用 link_library(demo::demo)。当然也可以留空，这样导入后的目标的名称前不会加任何前缀。

DESTINATION 参数指定导出目标的安装位置，一般放在 lib/cmake/libraryName 目录下。

配置文件

之后要生成配置文件， find_package 命令会寻找这个文件作为库个配置文件。这个文件一般用于包含我们导出的那些导出目标文件。

模板

首先我们需要先写一个模板文件，命名为 Config.cmake.in，类似下面

@PACKAGE_INIT@

include(CMakeFindDependencyMacro)
find_dependency(demo_dep REQUIRED)

include("${CMAKE_CURRENT_LIST_DIR}/demo-targets.cmake")

check_required_components(demo)

第一行将会被处理并替换为相应的初始化内容。

第二、三行用于包含依赖的包。如果我们的库有依赖，那么我们不仅在构建时需要处理好，在导出时也需要在配置文件里面处理好依赖。首先我们需要包含 CMakeFindDependencyMacro 模块，这个模块提供了 find_dependency 函数用于查找依赖的包。我们可以通过 REQUIRED 参数来指定该依赖是必须的。find_dependency 的用法与 find_package 基本相同，但一般只推荐在配置文件使用。

第四行用于包含我们安装的导出文件，我们通过 CMAKE_CURRENT_LIST_DIR 变量来获取当前处理的文件的路径，也就是该配置文件的路径。

第五行用于检查是否包含了必要的组件。我们目前没有使用组件功能，因此只有一个组件也就是 demo

生成

CMake提供了一个 configure_package_config_file 函数用于生成配置文件。要使用这个文件我们需要先包含CMake提供的工具 CMakePackageConfigHelpers。这个命令可以通过模板文件生成配置文件。

include(CMakePackageConfigHelpers)
configure_package_config_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in"
    "${CMAKE_CURRENT_BINARY_DIR}/demo-config.cmake"
    INSTALL_DESTINATION lib/cmake/demo
)

第一个参数是模板文件的路径，第二个参数是生成的配置文件的路径，我们将其放在当前构建文件夹而不是直接放在安装目录，第三个参数 INSTALL_DESTINATION 是安装位置，一般在 lib/cmake/libraryName。

安装

最后我们将配置文件安装到我们刚刚指定的安装位置（上一个命令虽然指定了但没有执行安装）。

install(
    FILES "${CMAKE_CURRENT_BINARY_DIR}/demo-config.cmake"
    DESTINATION lib/cmake/demo
)

到此配置就完成了。

完整代码示例

CMakeLists.txt：

# 创建目标
add_library(demo SHARED demo.cpp)

# 链接依赖库
target_link_libraries(demo PUBLIC demo_dep)

# 添加包含目录
target_include_directories(
    demo
    PUBLIC
        "$"
        "$"
)

# 安装库
install(
    TARGETS demo
    EXPORT demo-targets
)

# 安装头文件
install(DIRECTORY include/ DESTINATION include)

# 安装导出
install(
    EXPORT demo-targets
    FILE demo-targets.cmake
    NAMESPACE demo::
    DESTINATION lib/cmake/demo
)

# 生成配置文件
include(CMakePackageConfigHelpers)
configure_package_config_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/Config.cmake.in"
    "${CMAKE_CURRENT_BINARY_DIR}/demo-config.cmake"
    INSTALL_DESTINATION lib/cmake/demo
)

# 安装配置文件
install(
    FILES "${CMAKE_CURRENT_BINARY_DIR}/demo-config.cmake"
    DESTINATION lib/cmake/demo
)

Config.cmake.in：

@PACKAGE_INIT@

include(CMakeFindDependencyMacro)
find_dependency(demo_dep REQUIRED)

include("${CMAKE_CURRENT_LIST_DIR}/demo-targets.cmake")

check_required_components(demo)

总结

本文简单介绍了如何使用CMake进行导入导出。足以让我们开发一些简单的共享库并使其他开发者可以方便地使用。

对于开发一些更复杂的库乃至框架，可能需要拆分成多个组件，本文并未涉及。

CMake进阶教程

2025-05-15T08:00:00.000Z

上一篇文章CMake基础教程中介绍了CMake的一些基础用法，本文是该系列的进阶教程，将会介绍一些CMake的进阶用法，帮助我们更好地管理更复杂的项目。

CMake的进阶使用

之前已经介绍了如何使用CMake添加目标并为其配置头文件包含目录和依赖库，但并没有涉及如何使用第三方库，以及更精细的配置。本节将会在这些方面进一步深入。

上一节已经解读了MineSweeper的msutils和ui两个模块的CMakeLists.txt，本节将主要根据qt_ui模块的CMakeLists.txt来介绍。

这是qt_ui模块的CMakeLists.txt

find_package(Qt6 COMPONENTS Core Gui Widgets Svg REQUIRED)

set(CMAKE_AUTOMOC ON)
set(CMAKE_AUTORCC ON)

set(SOURCES
    src/main.cpp
    src/mainwindow.cpp
    src/diff_menu.cpp
    src/cust_diff_form.cpp
    src/game_field.cpp
)

set(HEADERS
    include/mainwindow.hpp
    include/diff_menu.hpp
    include/cust_diff_form.hpp
    include/game_field.hpp
)

set(RUNTIME_LIBS Qt6::Core Qt6::Gui Qt6::Widgets Qt6::Svg)

set(RESOURCES resources.qrc)

add_executable(MineSweeper-qt ${SOURCES} ${HEADERS} ${RESOURCES})
target_link_libraries(MineSweeper-qt PRIVATE msutils ${RUNTIME_LIBS})
target_include_directories(MineSweeper-qt PRIVATE include)

install(TARGETS MineSweeper-qt DESTINATION bin)

if(${CMAKE_SYSTEM_NAME} STREQUAL "Windows")
    if(NOT DEFINED QT_INSTALL_PATH)
        message(
            SEND_ERROR
            "You must define variable QT_INSTALL_PATH, which is the path where your Qt installed\n"
            "You can pass it by -D or set it in your CMakePresets.json"
        )
    endif()
    install(
        FILES ${QT_INSTALL_PATH}/plugins/platforms/qwindows.dll
        DESTINATION bin/plugins/platforms
    )
    install(
        FILES ${QT_INSTALL_PATH}/plugins/iconengines/qsvgicon.dll
        DESTINATION bin/plugins/iconengines
    )
    set_target_properties(MineSweeper-qt PROPERTIES WIN32_EXECUTABLE TRUE)
    install(IMPORTED_RUNTIME_ARTIFACTS ${RUNTIME_LIBS} DESTINATION bin)
endif()

使用第三方库

上一篇文章中介绍了如何链接库，但链接的只是我们自己创建的库，而真正开发时自然少不了需要使用第三方库的时候。

使用第三方库，最常用的还是使用find_package函数来查找。

其基础的语法是

1	`find_package( [] [REQUIRED] [COMPONENTS ...])`

其寻找库的方式分为两种，模块模式和配置模式。

模块模式

模块模式通常使用外部提供而不是库本身提供的Find.cmake文件来按照特定方式去寻找模块。会在所有在变量CMAKE_MODULE_PATH中列出的目录中寻找。如果我们要使用非标准方式提供的模块文件，则只需要将其所在目录添加到该变量中即可。

CMake会设置相应的变量来存储查找结果，变量比较多，详情可以参阅官方文档，这里只介绍几个

_FOUND：是否找到
_INCLUDE_DIRS：模块中所有包含目录的最终集合
_LIBRARIES：模块中所有的库

如果是按照这种方式查找的，我们可以通过这三个变量判断库有没有找到，并将其包含目录和库全部添加到我们的目标上。

这种模式已经被逐渐弃用，现在主流的是使用配置模式。其使用更符合Modern CMake的基于目标的实现形式。

配置模式

在此模式下，CMake 搜索名为-config.cmake或Config.cmake的文件。如果指定了版本详细信息，它还会查找-config-version.cmake或ConfigVersion.cmake文件，去做版本相关的处理。这些文件通常在lib/cmake/PackageName下面。

CMake确定路径结构时常常需要使用相对路径，其会将某个路径作为Prefix，以这些路径作为当前目录取相对路径。比如之前我们设置CMAKE_INSTALL_PREFIX变量为某个值，就是以这个路径作为当前目录取相对路径来确定安装目标位置。

CMake搜索配置文件时也会以一系列路径作为前缀路径来确定配置文件的位置，这些前缀路径存储在CMAKE_PREFIX_PATH变量中，在Linux中其默认值为/usr，通过包管理器安装的C/C++库往往都会将配置文件放到/usr/lib/cmake下面包名对应的文件夹中，这些可以被CMake默认搜索到。当我们使用其他方法将库安装到非标准位置时，只需要将其Prefix附加到变量CMAKE_PREFIX_PATH中。

比如我们从源码编译一些库并安装到~/.local下（安装时指定CMAKE_INSTALL_PREFIX为~/.local），要调用时就可以将~/.local添加到CMAKE_PREFIX_PATH中，一般不建议在CMakeLists.txt中直接硬编码，而是通过设置环境变量或在预设文件中设置该变量，又或者调用cmake时手动传入。

该模式下，允许包将自己分为多个组件(Component)，一个组件相当于一个子包，其中也可以包含多个目标。一个组件共享一个配置文件，便于选择性安装和包配置。

组件不等于目标，一个组件可能含有多个目标，上面Qt6::Gui是Qt6 Gui组件中的一个目标，虽然同名，但不是一个概念。一些比较小的库往往不使用组件，这时候如果以为组件就是目标而擅自在find_package中加上COMPONENTS target REQUIRED可能会导致找不到组件而报错。

一个包往往会有一个以包名命名的名称空间，引用包中一个目标一般可以通过PackageName::Component实现。而如果包中添加了组件，那么每一个组件可能也有各自名称空间，但也有可能设置为和包共用名称空间。这由库的开发者决定。

上面的CMakeLists.txt中使用了find_package函数来查找Qt6，便是使用了配置模式。Qt6是个庞大的框架，我们使用其中四个组件，要确保这些组件被找到的方式便是加上COMPONENTS component1 ...，这些组件如果有一个没有找到，则视为这个包没有找到。最后的REQUIRED表示这是必须的，找不到无法完成配置。

控制语句

这是msutils模块的CMakeLists.txt的后半部分内容

if(${CMAKE_CXX_COMPILER_ID} STREQUAL "MSVC")
    target_compile_options(msutils PUBLIC /W4)
elseif(${CMAKE_CXX_COMPILER_ID} STREQUAL "GNU")
    target_compile_options(msutils PUBLIC -Wall -Wextra -Wpedantic)
elseif(${CMAKE_CXX_COMPILER_ID} STREQUAL "Clang")
    target_compile_options(msutils PUBLIC -Wall -Wextra -Wpedantic)
endif()

由于C/C++有众多编译器，每个编译器支持的编译选项也不同，因此我们通常需要根据编译器的不同来选择不同的编译参数。上面部分就使用了if语句来分情况添加编译选项。

CMake的if语句写法大致如上，通过STREQUAL函数来比较两个字符串是否相同，内置变量CMAKE_CXX_COMPILER_ID表示C++使用的编译器名字。具体列表见官网。

我们还可以像qt_ui的CMakeLists.txt中那样通过CMAKE_SYSTEM_NAME变量判断操作系统（交叉编译的话，该值应是目标系统）。具体列表见官网。

编译选项(compile option)

在编译时，编译器提供了很多选项（options），我们可以通过CMake为目标设置特定的选项。

我们使用target_compile_options函数来设置编译选项。语法上与之前介绍的两个没有什么区别，只是后面的列表中是编译器的参数，无需使用字符串，直接写出来空格隔开。

上面我们便为msutils设置了编译时打印所有warnings的选项。

在msutils中我们使用了PUBLIC作用域，因此链接了该静态库的其他两个可执行文件也都会开启这些选项。

安装(install)

CMake要配置安装一般使用install命令，该命令可以安装多种对象，本文将介绍以下这些。

install(TARGETS <target>... [...])
install(IMPORTED_RUNTIME_ARTIFACTS <target>... [...])
install({FILES | PROGRAMS} <file>... [...])
install(DIRECTORY ... [...])

安装命令较为复杂，但大多都是写开发库和框架时需要的，本文中不会涉及，因此删去大部分参数，只保留少数常用的参数。

比如所有的安装命令都有指定文件访问权限的参数，本文中都将其删去。要了解其详细用法，请参考官网文档

目标安装

这是最常用到的命令，将目标安装到指定路径下。路径若使用相对路径，则相对CMAKE_INSTALL_PREFIX变量的值，该值在linux系统下一般默认为/usr或/usr/local。

基础语法如下

install(TARGETS <target>...
        [option>...]
        [ option>...]...
        )

其中包含很多内容，我们主要使用DESTINATION

用来指定输出目录。但对于一般的静态库、动态库或可执行文件，这并不是必要的，因为一般默认值就是推荐值。

其中表示目标中对象的类型，亦包括很多种，但我们主要介绍三种：

ARCHIVE：静态库或动态库的导入库。
LIBRARY：动态库（除了DLL）。
RUNTIME：可执行文件或DLL。

第一次设置是为所有类型设置。第二次设置是为指定类型单独设置选项。

qt_ui中便使用此命令安装MineSweeper-qt目标，并指定了输出目录为bin（实际上并不需要指定，因为这就是默认值）。

Windows下动态库默认安装到bin，和可执行文件在同一个目录，因此通常不会有找不到动态库的问题。在linux默认安装到lib，如果安装到非标准位置，你需要将该位置下的lib文件夹加入到ld的搜索路径中，才能保证动态库被正确调用。

动态库依赖安装

我们的程序若使用了动态库，且该动态库没有安装到系统全局中，我们可能需要在安装自己的程序时，将其依赖的动态库也安装到对应位置上。

如果这个动态库是我们项目中的一个目标，自然很简单，直接将其作为目标安装即可。但如果是通过find_package导入的第三方库，是无法通过这个方法安装的。

比如上面qt_ui在windows下时，由于一般windows下面安装qt都不会将qt安装到系统全局中，所以我们必须在安装程序的同时安装其依赖的qt相关动态库文件。

CMake提供了相应的安装命令，其基础语法如下

install(IMPORTED_RUNTIME_ARTIFACTS <target>...
        [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
         [DESTINATION ]
        ] [...]
        )

整体与安装目标的命令一样，该命令用于安装运行时工件，最常用的便是用于安装动态库依赖（该命令不会安装动态库的导入库）。

上面qt_ui便通过此命令安装了qt6相关动态库。

文件安装

如果要安装一些文件，可以使用命令

1
2
3

install( <file>...
        TYPE  | DESTINATION 
        [RENAME ])

FILES和PROGRAMS使用相同的形式，PROGRAMS一般用于安装脚本文件，与FILES的区别在于其可以设置执行权限。

我们应该在指定TYPE和DESTINATION中二选一，若指定了类型，则会根据类型决定安装位置。常用类型有

Type	Destination
`BIN`	`bin`
`LIB`	`lib`
`INCLUDE`	`include`
`SYSCONF`	`etc`

上面qt_ui在windows下将会通过此命令安装Qt6的一些必须的plugins到安装路径中。（可以通过指定环境变量让程序找到这些plugins，但直接自己装上一劳永逸）。

文件夹安装

要安装文件夹的基础命令如下

install(DIRECTORY dirs...
        TYPE  | DESTINATION 
        [FILES_MATCHING]
        [PATTERN  | REGEX ] [...])

DIRECTORY可以分别设置目录权限和文件权限，并且可以使用匹配机制只安装文件夹下匹配到的文件。

比如如果我们想要将qt_ui模块下的resources文件夹中的svg图片都安装到指定位置（原项目使用qrc文件，通过rcc工具将资源文件直接打包进可执行文件中）可以这样写

1 2	`install(DIRECTORY resources DESTINATION share/MineSweeper FILES_MATCHING PATTERN "*.svg")`

编译特性(compile feature)

编译特性是编译器支持的特性，比如C++11、C++14、C++17标准，或者对constexpr、decltype、final的单独支持等。我们可以通过target_compile_features函数来设置编译器特性。

1	`target_compile_features(<target> [...])`

编译器支持的特性可以通过变量CMAKE_CXX_COMPILE_FEATURES或CMAKE_C_COMPILE_FEATURES获取。所有的已知的特性都可以通过CMAKE_CXX_KNOWN_FEATURES或CMAKE_C_KNOWN_FEATURES来查询。

比如要为msutils启用C++20的特性，可以这样写target_compile_features(msutils PRIVATE cxx_std_20)。

单个特性主要是C++11和C++17的，为其单独设置在现在已经没有太大的必要。因此这个命令主要用于指定标准。最后实际上是通过传递-std=标志实现。

编译定义(compile definition)

编译定义主要指宏的定义。为C/C++源文件动态的注入宏的值。基础命令如下

1
2
3

target_compile_definitions(<target>
   [items1...]
  [ [items2...] ...])

比如我们可以通过target_compile_definitions(msutils PRIVATE FOO=1)来为msutils添加一个宏定义。该宏定义会在预编译时注入到源文件中。

也可以使用add_compile_definitions函数来添加。

属性(property)

CMake中属性可以影响到方方面面，从编译到构建过程到测试等都会有影响，CMake的所有信息基本都保存在各种对象的属性中。属性分为多种，有全局属性、目录属性、目标属性测试属性、源文件属性等等。

比如我们通过各种命令为目标添加的包含目录，最终都会被存储到目标的INCLUDE_DIRECTORIES属性中去。链接的库都会被记录到LINK_LIBRARIES属性中去。

还有一些其他的，起到特定作用的属性。比如上面qt_ui中当操作系统是windows时，会将MineSweeper-qt的WIN32_EXECUTABLE属性设为TRUE。这个属性为TRUE时会为程序构建一个带有WinMain入口的可执行文件，这使得其成为GUI程序而不是控制台程序。

读取和设置单个属性的命令为get_property()和set_property()。或者使用set_target_properties, set_source_files_properties, set_tests_properties, set_directory_properties为单个目标、源文件、测试、目录设置属性。将set改为get即对应的读取属性的命令。

这里只介绍最为常用的设置目标属性，其语法如下。

1
2
3

set_target_properties( ...
                      PROPERTIES  
                      [ ] ...)

全部的属性列表见官网。其他命令的具体用法可自行到CMake官网查询。

输出信息

有时我们想要在CMake的输出中查看一些信息，可以使用message命令。该命令可以输出一些信息到终端中，语法如下

1	`message([] "message text" ...)`

中可以指定输出的类型，常用的有STATUS、WARNING、AUTHOR_WARNING、SEND_ERROR、FATAL_ERROR、VERBOSE等。具体列表见官网。

比如我们想要查看MineSweeper-qt的LINK_LIBRARIES属性的值，可以这样写

1 2	`get_property(ms_qt_link_libs TARGET MineSweeper-qt PROPERTY LINK_LIBRARIES) message(VERBOSE "LINK_LIBRARIES: ${ms_qt_link_libs}")`

生成构建系统时加上参数--log-level VERBOSE，cmake就会输出上面的信息。如果没有输出，删除原本的构建系统重新运行再看看。

输出结果中应有这一行

1	`-- LINK_LIBRARIES: msutils;Qt6::Core;Qt6::Gui;Qt6::Widgets;Qt6::Svg`

总结

以上就是本文全部内容。目前介绍了如何使用CMake进行更细致的配置，如何使用第三方库，如何将程序安装到目标位置等等。

但如果想要开发的不是一般工程，而是开发库，甚至是大型的框架，这些显然是不够的。

但我掌握的内容暂时就到这里了，我也正在学习中，后续随着我的学习，可能还会再写一些专题教程。

CMake基础教程

2025-05-11T07:00:00.000Z

CMake 是一个跨平台的开源构建工具，用于自动化编译、测试和安装软件项目。本文将介绍CMake的基础部分。

什么是CMake

CMake 是一个跨平台的开源构建工具，用于自动化编译、测试和安装软件项目。

在C/C++构建过程中，我们知道必须要有一个编译器。但在实际应用中，除了编译器之外，我们往往还需要构建工具，甚至元构建工具来构建我们的项目。

要了解这些概念我们首先需要了解C/C++语言的编译过程。

C/C++的编译过程

C/C++的编译过程通常如下：

flowchart LR    A[源代码] --> |预处理| B[处理后源代码]    B --> |编译器编译| C[汇编]    C --> |汇编器编译| D[目标文件]    D --> E[链接器]    F[其他目标文件] --> E    G[库文件] --> E    E --> |链接| H[可执行文件或库文件]

预处理

预处理阶段会展开所有的宏，将头文件粘贴到include语句位置。

以GCC编译器为例，预处理的命令为

1	`gcc -E input.c -o output.i`

编译

经预处理的源代码会被编译器编译成汇编语言。汇编语言经汇编器生成目标文件。

现在市面上主流的编译器有三个，GCC, Clang, MSVC。

其中我们最常用的是GCC，其原本用于linux系统，移植到到Windows上则是MinGW。MSVC是微软开发的编译器，仅用于Windows系统，也就是Visual Studio使用的编译器。Clang是LLVM项目的编译器，最初用于Mac OS X，现已移植到Windows和Linux上。

以GCC编译器为例，生成目标文件的命令为

1	`gcc -c input.c -o output.o`

Linux系统下的目标文件后缀为.o，Windows系统下的目标文件后缀为.obj。

链接

原则上我们需要单独编译每一个源文件，并生成一个单独目标文件，这个过程中实际上是独立的，也就是说编译的过程中，各个源文件是感知不到其他源文件的。

我们通常在头文件声明变量、函数或类等，但是其定义可能分散在数个源文件中，那么每个源文件中的内容大概率是不完整的。比如在该源文件中调用的函数其定义在另一个源文件中，在编译时，只要有声明，编译器便不会报错，不会在意某个函数的定义是否存在。

链接器的作用就是将这些目标文件链接在一起，生成一个可执行文件或库文件。这个阶段，链接器会为各个目标文件中声明的变量、函数等等在所有目标文件中寻找定义，最终链接成一个完整的可执行文件或库文件。

以GCC编译器为例，链接几个目标文件的命令为

1	`gcc a.o b.o -o c`

通常我们想要编译几个源文件时，可以这样写命令

1	`gcc a.c b.c c.c -o d`

当项目非常小且没有什么依赖项时，这样似乎足够了。但是当项目变得比较庞大，我们要编译的源文件从几个变成几十个，要生成的东西从一个可执行文件变成数个库文件和数个可执行文件，那么一个一个敲命令来编译就显得效率很低而且易错、不易维护。

要解决这样的问题，很多人就会说了，写一个shell脚本不就好了。这正是下面一节要说的。

构建工具

什么是构建工具，构建工具是用于构建C/C++项目的工具（当然也可以是别的语言），运行一种特定的脚本文件来构建项目。

比如Linux上的make，通过运行Makefile来构建项目。我们只需要编写Makefile,而编写Makefile要比我们手写普通shell要方便得多，因为它有有更好的可拓展性、可维护性。

这就使得我们编译大型项目也能得心应手，只需要写好Makefile，后续构建只需要一行命令即可。

但是问题是，构建工具没有统一的标准，堪称百花齐放，各自与各自的平台深度绑定，往往互不兼容，导致难以迁移。

比如MSVC自带的构建系统NMake，仅在Windows下面可以用。

虽然也有像Ninja这样的跨平台构建系统，但还有一个问题是，这类脚本虽然比直接敲命令方便太多，但是也算不上好写，相当繁琐。

于是另一类工具诞生了，即下一节要介绍的元构建工具。

元构建工具

元构建工具是一种用于生成构建脚本或配置文件的工具，它位于构建系统的更高层次，用于自动化构建过程的配置和管理。

我们用元构建工具写一个配置文件，根据这个配置文件元构建工具可以生成指定构建工具的构建脚本再调用对应构建工具来构建项目。

使用元构建系统，配置可读性更高、更易维护，功能也更加强大。

当前主流的元构建工具便是CMake，当然也有其他一些元构建工具，比如xmake和bazel。但是目前CMake仍可以说是事实上的标准。使用的更广泛。

说了这么多，我们终于可以进入正题了，下面将介绍CMake的使用方法。

CMake工作流

这一节将介绍使用CMake的工作流。

以我自己写的一个简单小项目MineSweeper为例子，读者可以将该项目clone下来，尝试根据下面的介绍将其编译出来。

如果读者要使用该项目，请先根据该项目中的README.md文件先安装依赖。

编写CMakeLists.txt

CMakeLists.txt是CMake的配置文件，这个名字是固定的，是CMake的配置文件，虽然后缀是txt但实际上是一个脚本，使用一个独立的语言（它甚至是图灵完备的）。

后文中会介绍这个文件如何写。现在我们在该项目的根目录中可以看到一个CMakeLists.txt文件。我们要通过它构建这个项目。

生成构建系统

接下来我们要做的是生成构建系统。即通过cmake生成指定的构建系统的配置文件。

CMake可以生成多种构建系统，构建工具在cmake中被称为生成器generator，在linux下默认的为Unix Makefiles。推荐使用Ninja，不过需要单独安装

命令格式为cmake path，path指我们最外层CMakeLists.txt所在的目录。这会在我们当前目录下输出生成的构建系统。一般不推荐在项目根目录直接运行这个命令，不然生成结果会与源码混合，不利于管理。我们一般专门创建一个文件夹用来放生成结果。一般命名为build或out。

我们可以通过参数-B指定输出目录，-S指定源代码目录。我们也可以通过-G指定生成器。

我们也可以传递一些cmake变量的值，比如后面部署安装这一步默认安装到系统全局中（linux下即/usr下面），如果我们不希望这样，而是希望安装到我们自己的用户目录下的.local下，我们可以传递CMAKE_INSTALL_PREFIX变量来实现。语法为在变量名前加-D（无空格），在后面加=后面跟变量值。

1	`cmake -S . -B build -G Ninja -DCMAKE_INSTALL_PREFIX=/home/$USER/.local`

执行完成之后，我们会在当前目录下看到一个build文件夹，里面就是cmake生成的构建系统。如果你使用的是Unix Makefiles, 那么你将在里面看到一个Makefile文件。如果你使用的是Ninja，就会在里面看到build.ninja文件。这些便是对应构建系统的构建脚本。

构建

之后的步骤就是调用构建工具来构建项目了。一般需要配置的在此之前都已完成，我们只需要运行

1	`cmake --build build`

--build后面跟的是我们在上一步中指定的输出目录。

你也可以调用对应构建系统的构建工具来运行。比如Makefile可以直接调用make命令。

完成之后进入build文件夹就可以看到编译结果。一般没有在CMakeLists.txt中指定输出目录的话，输出结果的目录结构与源代码的结构是对应的（结构由CMakeLists.txt路径决定）。

比如在上面那个项目中，build中会有一个src文件夹，src下面有msutils，qt_ui，ui三个文件夹，这三个文件下面就是三个对应的CMakeLists.txt中配置的动态库文件和可执行文件。

部署安装

构建完成之后，如果想要把构建结果安装到我们自己的系统中，就可以使用cmake提供的安装功能（需要在CMakeLists.txt中写相应的配置，不然没法用）将编译出的结果（不仅仅是二进制文件）安装到指定的目录中。

默认的安装目录是/usr或/usr/local（linux），我们也可以通过CMAKE_INSTALL_PREFIX变量来指定安装目录。

1	`cmake --install build`

build是我们在之前指定的输出目录。

或者你也可以调用对应构建系统的构建工具来运行，比如Makefile可以使用make install来安装。

如果安装的是某些开发库，那么不仅仅二进制文件，可能还会有头文件或者CMake库配置文件（帮助CMake加载库的配置文件）被安装。

项目结构示例

上一节我们试着使用cmake编译运行了一个项目，现在我们将要尝试分析这个项目的结构和管理方式。

本节将会提供一种组织项目目录的结构，并结合上文给出的项目作讲解。

模块分离

根目录下放置一个顶层CMakeLists.txt，和一个src文件夹，我们项目的代码分模块放在src下面。

每个模块单独占一个文件夹，每个文件夹下放置一个CMakeLists.txt，用于本模块的配置。这样我们就隔离了模块之间的配置，防止互相干扰，便于管理。

比如这个项目的src文件夹下面有三个模块， msutils，ui，qt_ui。其中msutils是一个静态库，提供扫雷的底层处理。ui和qt_ui分别是基于Qt和终端编写的界面，为可执行文件。

头文件与源文件分离

C/C++项目中，我们一般将头文件与源文件进行分离，分别放入include，src文件夹中，便于管理。

CMake的基本使用

接下来本节将会以上面项目为例讲解CMake的基本使用。

基础设置

首先是项目的一些基本设置，比如要求的cmake版本、项目名称、使用的语言、使用的标准等等。

cmake_minimum_required(VERSION 3.16)
project(
    MineSweeper
    VERSION 1.0
    DESCRIPTION "A MineSweeper game written in C++ with Qt6"
    LANGUAGES CXX
)
set(CMAKE_CXX_STANDARD 17)

add_subdirectory(src/msutils)
add_subdirectory(src/ui)
add_subdirectory(src/qt_ui)

上面第一行要求cmake的版本至少要是3.16。

第二行project函数接受的第一个参数表示项目名称，这个是必须的，之后所有内容都是可选的。

如果想要指定当前项目的版本，可以加上VERSION major.minor.patch.tweak，当然实际使用中版本更迭除了major都是可选的，根据实际更迭去写就好。比如这个项目只是象征性的写了一个1.0。

如果想要给项目添加一点描述，那么就是加上DESCRIPTION "your description"。

后面如果想要指定使用的语言，比如C或C++或都有，都有可以添加LANGUAGES C CXX，只用一个就只填那个就行。

这些在函数参数列表中使用的全大写的关键字只是用来划分参数的，没有实际意义。

第三行，用来指定C++的标准，同理也可以指定C的标准，set(CMAKE_C_STANDARD 11)。

变量

CMake的脚本语言中也有变量的概念。上面的set函数就是用来设置变量的，CMake中所有的变量都是全局的，除非你在函数中使用set(VAR value PARENT_SCOPE)来设置父作用域的变量。

赋值语句也很简单，set(VAR VAL)，VAR是变量名，VAL是变量值。变量值可以是字符串、数字、列表等。如果是列表，元素之间只需要空格隔开即可。

要对变量取值，使用${VAR}即可。

其实CMake的变量其实本质上都是简单的字符串替换，和shell脚本类似。

添加子文件夹

其后的三行使用add_subdirectory(path)函数添加子文件夹，path是子文件夹的路径。这个函数会在path下查找CMakeLists.txt文件并执行。你需要确保path文件夹下面存在一个CMakeLists.txt。

这相当于添加子项目，层数可以无限深。

子文件夹下的CMakeLists.txt文件会在父文件夹的CMakeLists.txt文件执行完后执行，并继承所有变量。但不同的子项目之间变量是隔离的。

TOP面向目标编程

之后我们开始分别分析子模块的CMakeLists.txt文件。在此之前我们要先了解一个重要的概念：Target目标。

Modern CMake可以说是面向目标编程（Target-oriented programming），而目标实际上就是可执行文件、或是库。Modern CMake的设计理念是将每个可执行文件或库视为一个目标（Target），并通过设置目标的属性和依赖关系来管理构建过程。

具体要设置的东西，其实无非就是这个目标包括哪些源文件、头文件搜索路径、要链接的库、编译参数、编译选项、安装路径等等，以及一些属性。所以只要我们理清了这些，CMake可以很简单。

我们现在分析一下该项目的ui和msutils模块的CMakeLists.txt文件。

executable可执行目标

我们先来分析ui模块的CMakeLists.txt文件。这是其前三行。

1
2
3

add_executable(MineSweeper src/main.cpp src/ui.cpp)
target_link_libraries(MineSweeper PRIVATE msutils)
target_include_directories(MineSweeper PRIVATE include)

第一行命令使用add_executable函数添加一个可执行文件目标，MineSweeper是目标名称，后面是源文件列表。

这样就创建了一个名为MineSweeper的可执行文件目标，后续以MineSweeper来引用这个目标。

library库目标

之后分析msutils的CMakeLists.txt文件。这是其前两行。

1 2	`add_library(msutils STATIC src/Cell.cpp src/Grid.cpp src/Sweeper.cpp) target_include_directories(msutils PUBLIC include)`

第一行命令使用add_library函数添加一个库目标，msutils是目标名称，STATIC表示该库为静态库，若要生成动态库则使用SHARED，后面是源文件列表。

库目标的创建与可执行文件目标类似，后续以msutils来引用这个目标。其他的语法也差不多。

包含目录

有过C/C++多文件编程经验的读者都知道，编译器在编译时需要知道头文件的位置，需要设置头文件的搜索路径。

上面两个目标，我们需要为其添加其各自模块的include文件夹到搜索路径中去。

注意到msutils模块因为是用于被其他模块使用的模块，所以其头文件放在了include/ms下，这样我们在其他模块中引用时需要写成#include 的形式方能调用。这是管理大型项目必要的技巧，虽然以这个示例项目的体量其实并不必要。

作用域

target_include_directories函数的第一个参数是目标名称，第二个参数是作用域，PUBLIC表示该目录对所有依赖于该目标的目标可见，PRIVATE表示仅对该目标可见，INTERFACE表示仅对依赖于该目标的目标可见。之后是路径列表。

注意：所有路径，包括之前指定源文件的路径，若是写成相对路径的格式都是相对于该命令所在的CMakeLists.txt所在的路径，变量CMAKE_CURRENT_SOURCE_DIR的值便是该路径。

msutils的头文件设置为PUBLIC，因此MineSweeper链接了msutils之后，会将msutils添加的路径自动添加到其自己的头文件搜索路径。若是PRIVATE，则MineSweeper模块中将不会自动添加。若为INTERFACE，则是msutils本身不添加但MineSweeper添加。

全局添加

除了使用target_include_directories之外，我们还可以使用include_directories函数。该函数不需要指定target和作用域，会将路径直接添加到其后的所有目标上。

这并不符合Modern CMake的理念，但是如果你觉得这确实很方便，也不妨使用。

链接库

链接库与添加头文件搜索目录类似，使用target_link_libraries和link_libraries即可。参数为库目标列表。

总结

CMake的基础使用到这里就结束了。本文介绍了CMake的基本概念、工作流、基本使用方法和一些常用函数。读者可以根据自己的需求进行扩展。

能够熟练使用上面介绍的几个简单函数，就足以使用cmake来管理构建一些简单的没有外部依赖的项目了。

更深入的部分，比如调用第三方库、编译选项、目标属性、接口库、控制语句、安装等，读者可以关注后续的CMake进阶教程。

Vim教程-基础篇

2025-05-08T16:44:00.000Z

本系列教程适合零基础想要快速入手的(neo)vim初学者，同时作为LazyVim教程的前置教程。

前言

很多人对vim的印象是密密麻麻的vim键位图，认为vim指令繁多，难以记忆。但事实上，这些并不需要特别去记忆，我们不需要背完键位表再开始使用，而是在使用的过程中逐渐熟悉我们常用的命令，再根据需要去拓展我们原本不熟悉的命令。

Vim除了键位繁多之外，给人的印象是，没有一眼就看出怎么用的界面引导，而又不想为了一个操作专门去搜索教程。网上的教程也往往是大肆罗列各种命令，令人头大。

以及，vim没有IDE那样的完善的集成好的开发环境。

事实上这些问题确实存在，但又不是完全无法克服。

vim有很多优秀的插件，可以提供方便又强大的功能，也有一些成熟的、开箱即用的配置框架。依托于LSP的兴起，Vim的编程体验不说比肩IDE，也足以满足大多数人的大多数要求。

同时vim能带来更高的可拓展性，用户可以根据自己的需要定制自己的编辑器，享受随心所欲的编辑体验。

本教程包括三个部分，第一部分介绍vim的基础知识，第二部分介绍LazyVim和其中包含的各类插件，第三部分引导读者进行简单的配置。

本文将介绍vim的基础知识，帮助读者熟悉vim中的一些常见概念。

如何阅读本文

本文简单地介绍了一些vim中的常见概念，读者不必牢牢记住所有内容，只需大致理解其逻辑即可。可以在原生的vim中稍作尝试，体验各种操作的细节。

本文主要为后续教程作铺垫，下面罗列命令，仅仅是为了让读者知道有这么一回事儿，大多数命令都不是刚需的。

后续教程会引导用户安装配置框架，届时会借助插件获取更方便快捷的体验，会用一些被广泛接受的快捷键替换原生命令。

模式

vim的特点是有多个模式，在不同的模式中进行不同的操作，这样可以缓解快捷键不够用的问题，也可以使我们不必像Emacs那样大量的使用Ctrl、Alt键，减少小指的压力。

vim共计有6中模式，分别为Normal（正常）、Command（命令）、Insert（插入）、Visual（可视），Replace（替换）和Terminal（终端）。。

该篇主要讲解Normal、Command和Insert模式。

Normal模式

Normal模式是我们进入vim后的默认模式。我们仅在有需求时进入其他模式，其余时间皆停留在Normal下。大多数操作都在Normal下完成。

此时我们输入的按键不会被解读为输入的字符，而是被解读为指令。因此我们不必大量使用Ctrl等按键也可以实现方便的输入指令。

该模式下我们主要进行移动光标到我们需要的位置以便后续其他操作或者仅仅阅读文字信息。

Normal模式下我们可以通过简单的按键进行光标的移动，以及一些回退等操作。

方向键

按键	操作
`h`	左
`l`	右
`j`	下
`k`	上

跳转

按键	操作
`$`	跳转到行尾
`0`	跳转到行首
`^`	跳转到行首非空字符
`gg`	跳转到buffer第一行
`G`	跳转到buffer最后一行

单词跳转

按键	操作
`w`, `b`	跳转到下一个，上一个单词开头
`e`, `ge`	跳转到下一个，上一个单词末尾

回退，再执行

按键	操作
`u`	回退上一次操作
	重新执行上一次操作

删除

案件	操作
`d + 跳转命令`	删除当前位置到跳转目标之间的内容
`dd`	删除当前行
`x`	删除光标下文字

搜索

Normal模式下，可以进行搜索，按/后可以开始输入搜索内容，输入完后按下回车执行，可以使用按键快速在搜索结果之间跳转。支持正则表达式。

按键	操作
`n`, `N`	跳转到下一个，上一个搜索结果

Command模式

vim除了按下按键发送指令外，还可以直接输入命令来执行。vim有一套自己专门的脚本语言vimscript，我们在命令模式下输入的便是这种语言，但我们一般只需要输入最简单的命令即可。

在Normal模式要输入命令，只需要按下:即可进入Command模式，此时我们可以开始输入命令，命令一般会显示在左下角。

这里先介绍必要的几个命令

命令	含义
`:q`	退出
`:w`	写入，即保存
`:open filename`	打开文件，若不存在则创建

在:和命令之间加!表示在终端中运行。在命令后加!表示强制执行。

在q和w之后加字母a表示all，即退出全部、保存全部的意思。

在退出时，可能会询问是否要保存内容，若不想保存可以可以使用:q!强制退出。

Insert模式

Insert模式是进行字符输入的模式，在Insert模式下大多数快捷键失效，输入的按键会被解读为字符，与一般的文本编辑器无异。

从Normal模式切换到Insert模式有很多种方式，我们只需根据自己的习惯掌握对应的方式即可。

按i，会在当前光标位置之前开始插入字符。比如如果当前光标（一般是方块状）落在这一句的‘比’字上，按i将在‘比’字之前插入字符。
按a，会在当前光标位置之后开始插入字符。
按o，会在光标所在行的下一行开始插入。
按I，会在当前行的开头开始插入。
按A，会在当前行的结尾开始插入。
按O，会在当前行的上一行开始插入。
按c + 跳转命令，和d相似，但会在删除内容后进入insert模式。

要退出Insert模式回到Normal模式，只需要按下即可，或者使用也可以。

是内置快捷键，与相同，由于一般离手比较远，所以很多人不喜欢，这个快捷键便出现了。

Visual模式

Visual模式用于选中文本，按v可进入Visual模式，vim会选中进入处到当前光标之间的文本内容。在visual模式下，可以使用normal模式下相同的方式进行光标的移动。

Visual模式下可以使用一些按键对选中的文本进行操作，一般操作后自动退回Normal模式。

按键	含义
`y`	复制选中内容到寄存器
`d`	删除选中的内容，并复制到寄存器
`p`	粘贴当前寄存器的内容覆盖选中内容，再将选中内容复制到寄存器
`c`	删除选中的内容，并进入Insert模式

Vim内部有一个独立的寄存器，用于保存在vim中复制的内容，与系统剪贴板并不互通。

若要与系统剪贴板互通，需要设置寄存器，再使用其他命令进行复制粘贴。本教程不打算涉及这方面，而推荐使用插件来实现vim与系统剪贴板互通。

Replace模式

介绍这个模式前先介绍一个与它关系紧密的命令。在Normal模式下，按下r键再输入一个字符，这个字符会替换光标下原本的字符。比如你将光标移动到Normal的N上，按下rn会将N替换为n。

如果按下R键，会进入Replace模式。在该模式下，你可以想Insert模式下那样输入字符，但是你输入的内容会取代那个位置原本的内容，而不是插入。使用键推出该模式。

比如你可以将光标移动到以上段的Insert的I上，按下R之后，输入Normal，Insert就会被Normal覆盖（字符数量一样）。

Terminal模式

neovim或新版vim支持内部打开终端。使用:term COMMAND来打开终端，其中COMMAND为要执行的命令，比如bash，zsh等。Terminal模式下，你的操作都会被传递给终端，可以和终端进行交互。

要退出该模式，输入快捷键。之后终端页面将会变成一个只读的缓冲区（缓冲区见下节），你可以使用vim的命令去操作，和你操作只读文件没什么不同，你可以自由的浏览和复制其中内容。

要再进入Terminal模式，只需按下i键即可。

Vim的组成

Vim中有Tab（标签页）、Buffer（缓冲区）、Window（窗口）三个概念。

Vim的高效主要来自于其独特的模式编辑，但也与其Tab、Buffer、Window的紧密结合有关。

Buffer缓冲区

Buffer缓冲区用于存储内容，比如我们打开的文件，它的内容会被vim读取并存储在一个buffer中。

Vim中可以同时打开多个buffer，存储不同的内容，互相独立。我们可以在不同的buffer之间切换，实现多文件同时修改。

我们也可以将一些其它的文本内容加载到buffer中方便查看，比如当前的目录信息，tags列表，帮助文档等等。

buffer命令

按键	含义
`:ls`	显示所有buffer
`:bp`	切换上一个buffer
`:bn`	切换下一个buffer
`:bd`	删除buffer，后加索引删除指定buffer，不加删除当前buffer

Window窗口

Window窗口用于显示buffer的内容，我们调用退出命令时退出的实际上是当前Window。所有windows被退出后，回到终端。

我们进入vim时会默认打开一个window，称为主window。

每个window只能显示一个buffer的内容，因此当我们打开多个文件、有多个buffer之后，只有最后一个buffer的内容会被显示在主window上。

但我们可以将主window分割为多个小window，实现同时查看编辑多个buffer，或者多个window可以同时显示或编辑同一个buffer不同位置的内容。

当我们有多个window时，输入指令:q会关闭当前window，我们关闭一个window并不会删除该window正在显示的buffer。

因此我们使用vim时可以分割一小部分window用于显示一些内容，左侧显示当前目录树、右侧显示tags列表，下部显示终端等等。

Vim中可见的一切都是buffer和window，因此我们可以使用相同的操作逻辑操作可见的所有内容。这种基于TUI的界面的操作模式与其他基于GUI的编辑器相比，或许显得简陋，但也更具有连贯性，更加随心所欲。

Vim的编辑键位很多其他编辑器/IDE都有不错的插件实现，但往往仅仅局限于文本编辑区，其他部分仍然遵循原本的GUI操作。

window跳转

按键	含义
`h`	跳转到左侧window
`l`	跳转到右侧window
`j`	跳转到下册window
`k`	跳转到上册window

window分割

按键	含义
`:split`	水平(上下)分割window
`:vsplit`	垂直(左右)分割window

在分割后可以添加文件名，会在分割出的新window中打开该文件，否则会显示当前buffer。

Tab标签页

Tab就是标签页。Tab保存的是buffer和window的布局信息。

即window的分割情况，包括window的数量、位置、长宽等，以及每个window中显示哪一个buffer。

多个tab之间的buffer是互通的，仅仅window布局不同。

比如我们编辑一个文件时可能打开了很多其他window，我们希望保留这些布局但又需要打开新的文件、新的window，就可以创建新的tab，在不同tab之间可以随意转换，轻松驾驭复杂布局，不用每次都重新打开。

如果读者熟悉tmux，就会发现两者管理方式有很多共通之处。tmux中一个打开的shell就相当于vim中一个buffer，tmux中的panel则相当于vim中window，tmux的window则相当于vim的tab。不过tmux中的终端实例和panel是

对于熟悉其他编辑器的用户来说，可能会尝试这样使用vim的tab：在每个tab中分别打开一个文件，切换tab来实现切换文件。这样做是可行的，但并不是惯常用法。

惯常做法是通过buffer的切换来切换文件，因为切换tab会切换window布局，因此单纯想要切换正在修改的文件没必要切换tab。

标签页命令

按键	含义
`:tabs`	显示所有标签页
`:tabnew`	创建新标签页
`:tabp`	切换上一个标签页
`:tabn`	切换下一个标签页
`:tabc`	删除当前标签页

cwd

Vim和shell一样有CWD的概念，在vim中运行一些命令，比如:open，需要使用相对路径的，都是根据vim的CWD来的。

你可以运行:pwd来查看cwd，使用:cd来切换。

在vim中每个tab的cwd是独立的，不会同步改变。

你可以设置让cwd跟随当前buffer改变，始终让当前buffer中的文件所在目录为cwd。一般不推荐这样做，如果你要运行一些项目级的命令，比如lsp相关，这通常需要知道你的项目根目录。

键位与宏

Vim的模式编辑使得vim中用户的所有操作都可以通过一系列按键事件表示。Vim中我们可以将一系列按键映射为一个键，按下这个键便相当于按顺序按下被映射到的一系列键。

因此我们可以直接将输入命令映射为一个键，比如将:bp (``表示回车键) 映射到H，这样我们按下Shift + h时，便相当于我们输入了:bp`之后按下回车，实现buffer切换。

又比如我们可以将jj映射到这样我们在Insert模式只需连按两下j就可以退出插入模式。

有关如何设置快捷键的问题，我们在后续的教程中会涉及。

Leader键

Vim中还有一个特殊的按键机制，称为Leader键。Leader键可以被用户指定为哪个键，而在键位映射中使用指代这个键。

我们使用vim的过程中会出现快捷键越来越多，按键序列可能会越来越长，而且很多快捷键其实并不常用，如果绑定在字母按键上，容易误触。

于是我们有了一一个解决方案，就是统一指定一个键作为前缀键，用来存放相对没那么常用的功能。而只将最常用的部分功能映射到普通字母上。

以Leader开头的快捷键往往是按照键的意义，进行分级分类。比如buffer相关的操作，都以b开头，相当于这些快捷键都被分到b这一分类中。类似的widnow相关的分到w，tab相关的分到，terminal相关的分到t。

又比如可以将一些常用插件，其相关的快捷键占用一个一级字母前缀，没那么常用的，和几个同类型的占用一个一级字母下的二级字母，或者快捷键数量不多的话混合起来。

Leader键可以由用户指定值，那么我们就既可以随我们心意去设置，也不必担心某个插件使用的Leader键和我们不同。

Vim中一般不使用Alt, Ctrl也很少使用，对我们的小指非常友好。

LocalLeader

Vim中除了Leader之外还有LocalLeader，特点是仅对当前buffer有效。这常用于某些只在特定场合下使用的快捷键，比如只对某个文件类型有用的快捷键。

若是有快捷键只在特定的场合下有效，那么就没有必要将其作为全局快捷键，因此另外使用一个键作为此类快捷键的前缀键是合适的。这同时使得同一个快捷键可以在不同场合下映射到不同的操作。

同时此类快捷键应当是只在特定场合下才加载的，关于如何在特定场合下加载快捷键，或者说加载配置，后面介绍autocmd时会详细介绍。

宏

Vim中同样提供宏的功能，并且相当便捷和强大。

由于在vim中所有操作基本都可以靠一系列按键事件来完成，因此vim中记录宏也就是记录我们按下的按键，在我们使用宏时原样敲一遍。

我们只需要按q+字母之后敲下一个个按键或者输入命令（快捷键包括以Leader开头的都可以正常使用）这些指令就会被绑定到对应字母上，之后@+字母就可以播放对应字母中绑定的宏。

被绑定的宏可以在vim中随意使用，甚至可以在不同的buffer中使用，但只会保存至当前vim实例退出。

重复

Vim中可以通过在指令前输入数字来将指令重复执行指定次数。比如，按下3j，表示向下移动光标三次，3dd表示删除当前行及其下两行。

这对于宏也同样适用。比如3@a，表示播放字母a中绑定的宏三次。

总结

到这里基础篇就已经介绍完毕。读完本篇你应该已经对vim有了大致的了解。在下一篇中，将会介绍LazyVim的安装和配置，届时会介绍上面的操作在LazyVim中如何实现。

Docker基础教程

2025-04-02T06:00:00.000Z

Docker是一种虚拟容器应用这使我们可以在性能损失很小的情况下，方便地创建并管理虚拟环境。本教程涵盖Docker的基础操作，帮助初学者快速上手。

1 安装Docker

要安装docker需要添加Docker的源，推荐使用清华的镜像源来安装。

根据清华镜像站中的使用教程一般顺利完成docker的安装。

2 配置nvidia gpu支持

要在docker容器中调用nvidia gpu，无需在容器内安装nvidia显卡驱动，而可以令容器调用宿主机的显卡驱动，秩序宿主机正确安装显卡驱动即可。要完成这一点需要安装nvidia提供的nvidia-container-toolkit和nvidia-container-runtime，并正确配置daemon。

2.1 安装nvidia-container-toolkit和runtime

首先需要添加相关的仓库源。根据nvidia官方教程，指令如下：

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

之后使用apt安装即可。

1 2	`sudo apt update sudo apt install -y nvidia-container-toolkit nvidia-container-runtime`

2.2 配置docker daemon

要使用nvidia显卡还需要配置docker daemon的runtime，修改/etc/docker/daemon.json文件，添加如下内容：

{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}

之后重启docker服务即可。

1	`sudo systemctl restart docker`

3 容器与镜像基础操作

Docker容器是由Docker镜像创建的运行实例，镜像是一个只读的模板，容器是镜像的运行实例。容器可以被启动、开始、停止、删除、暂停等。

一个容器相当于一个独立于宿主机的系统环境，我们可以像在宿主机上一样在容器内实现各种操作，比如安装软件、运行程序等等。

我们可以保存容器的状态成一个镜像，也可以运行镜像创建一个与该镜像创建时的容器一模一样的新容器。

3.1 获取镜像

要获取镜像文件，有三种方式，第一种是直接拉取云端的镜像或加载被保存到本地的离线镜像文件，第二种是从已存在的容器创建镜像，第三种是通过编写Dockerfile创建镜像。

拉取镜像的命令为，若运行容器时使用了本地没有的镜像，会先尝试拉取该镜像。

1	`sudo docker pull image_name`

3.2 查看镜像

docker镜像名称通常由两部分组成，一个是仓库名，一个是tag，写成repo:tag的形式。比如ubuntu:22.04, ubuntu:latest。

要查看本地的镜像可以使用下面命令。

1	`sudo docker images`

输出结果类似下面。

1
2
3

REPOSITORY                      TAG                   IMAGE ID       CREATED        SIZE
osrf/ros                        noetic-desktop-full   f19749f1e3da   5 months ago   3.44GB
ubuntu                          20.04                 6013ae1a63c2   5 months ago   72.8MB

3.3 运行容器

运行容器需要使用命令run，格式为

1	`docker run [OPTIONS] IMAGE [COMMAND] [ARG...]`

以下列举常用的选项：

-d 表示后台运行
-e ENVVAR=VAL 添加环境变量的值，ENVVAR为环境变量名，VAL为值
--name container_name 为容器指定一个名字
-it 表示交互式运行终端，默认为bash，在[COMMAND]位置可以指定具体命令，如zsh。
-p host_port:container_port 映射端口，host_port为宿主机端口，container_port为容器端口
--device DEVICE_PATH 挂载宿主机设备，是容器可以访问该设备，一般为/dev目录下的
--privileged 给予容器高权限(不太安全，使容器拥有破坏宿主机环境的能力)

例如，要运行一个ubuntu容器，可以使用下面命令。

1	`sudo docker run --name ubuntu20 -it ubuntu:20.04 bash`

3.4 查看容器信息

查看信息可以使用ps命令，格式为

1	`sudo docker ps -a`

输出类似下方

1 2	`CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 3c02dd5ef563 mysql:latest "docker-entrypoint.s…" 12 days ago Exited (0) 6 days ago rdnb_mysql`

3.5 从容器运行程序

对于一个正在运行的容器，我们可以在宿主机中通过exec命令运行容器内的程序。

1	`docker exec [OPTIONS] CONTAINER COMMAND [ARG...]`

-e, -d, -it依旧可以使用，CONTAINER为容器名称，COMMAND为要运行的命令，ARG为命令的参数。

例如我们想打开一个容器中的终端

1	`sudo docker exec -it ubuntu20 bash`

3.6 其他常用命令

docker start CONTAINER 启动容器
docker stop CONTAINER 停止容器
docker restart CONTAINER 重启容器
docker rm CONTAINER 删除容器
docker image rm IMAGE 删除镜像

3.7 保存容器到镜像

我们可以使用commit指令保存容器当前状态到镜像

1	`docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]`

例如将名称为ubuntu20的容器保存为名为myenv:ubuntu20

1	`sudo docker commit ubuntu20 myenv:ubuntu20`

3.8 镜像迁移

Docker镜像可以保存到.tar文件，并且加载被保存在文件中的镜像。这使得docker容器便于部署和分发。

保存到文件

1	`docker save -o image.tar image_name`

从文件加载

1	`docker load -i image.tar`

4 运行GUI程序

要运行docker容器内的GUI程序，一般使用xorg进行。这需要容器内安装了x server，将GUI界面通过宿主机桌面上显示。一般ubuntu系统的容器已默认安装。

4.1 配置宿主机权限

要在宿主机上显示容器内的GUI界面，需要配置宿主机的权限，使得容器可以访问宿主机的桌面。

下面这行命令直接允许所有的本地访问。

1	`xhost +local:`

4.2 配置容器参数

要运行GUI程序，需要在运行容器时添加相应参数，使得容器可以正常访问宿主机的桌面显示图形界面。

-e "DISPLAY=$DISPLAY" 将环境变量DISPLAY设置为主机显示器;
--mount type=bind,src=/tmp/.X11-unix,dst=/tmp/.X11-unix 将主机X服务器套接字挂载到相同路径下的容器内;
--device=/dev/dri:/dev/dri 允许容器直接访问主机上的直接渲染(DRI) 设备。

例如，要运行一个ubuntu容器并运行终端，可以使用下面命令。

1	`sudo docker run -e "DISPLAY=$DISPLAY" --mount type=bind,src=/tmp/.X11-unix,dst=/tmp/.X11-unix --device=/dev/dri:/dev/dri -it ubuntu:20.04`

之后在容器内运行GUI程序一般可以直接在宿主机上打开。

5 调用nvidia gpu加速容器

5.1 使容器可以访问宿主机显卡

要调用nvidia gpu，需要在运行容器时添加相应参数，使得容器可以正常访问宿主机的显卡。

一般需要添加以下参数：

--gpus all 使得容器可以访问宿主机的显卡
--runtime=nvidia 使用nvidia runtime
-e NVIDIA_DRIVER_CAPABILITIES=all 设置环境变量，开启所有nvidia驱动功能

例如打开一个需要调用gpu并且要打开图形界面的容器可以使用如下命令。

sudo docker run -e "DISPLAY=$DISPLAY" --mount type=bind,src=/tmp/.X11-unix,dst=/tmp/.X11-unix --device=/dev/dri:/dev/dri --gpus all --runtime=nvidia -e NVIDIA_DRIVER_CAPABILITIES=all -it ubuntu:20.04

无需在容器内安装nvidia显卡驱动，在容器内可以通过调用nvidia-smi来确认是否可以正常调用宿主机显卡驱动来访问显卡。

5.2 容器中配置cuda、cudnn等

要在容器中使用cuda等工具，推荐做法是直接使用已经配置好cuda、cudnn等工具的镜像，nvidia官方提供了相关镜像。官网

但如果确实需要自己安装cuda等工具，就像在宿主机上安装一样直接在容器中安装即可。

注意：不建议使用包管理器安装，这往往会同时安装nvidia显卡驱动，导致驱动版本不兼容问题。推荐做法是使用nvidia的安装程序安装，并选择不安装驱动。

6 数据可持久化

容器是一个独立的环境，容器内的数据在容器删除后会丢失。为了保存数据，docker提供了数据可持久化的方法。

6.1 复制文件

Docker提供了cp命令，可以在宿主机和容器之间复制文件或文件夹。格式如下：

1	`docker cp SRC DST`

会将SRC文件或文件夹复制到DST文件或文件夹，宿主机上的文件直接写路径即可，容器内的文件需要在容器内路径前加上CONTAINER:。

6.2 卷

Docker可以通过创建卷(volume)将数据可持久化，卷可以被映射为容器内的某个文件夹，该文件夹下的文件都会被保存到宿主机上，不会随着容器被删除而消失，可以重新挂载。

多个容器挂载相同的卷可以用来共享数据。

6.2.1 运行时挂载卷

在运行容器时可以使用-v参数来创建卷，格式如下：

-v volume_name:container_path

如果volume_name不存在，docker会自动创建一个新的卷。

如果要将宿主机的某个文件夹映射到容器内的某个文件夹，可以使用下面格式，这并不会创建卷。

-v host_path:container_path

卷其他操作

Docker中卷相关的命令以docker volume开头，

docker volume create 创建卷
docker volume ls 列出所有卷
docker volume rm 删除卷
docker volume inspect 查看卷信息
docker volume prune 删除所有未被使用的卷

7 网络network

Docker可以为容器配置network，使得容器间通过网络访问更加方便。挂载同一个network的docker容器处于同一个网络环境内，可以通过network的名字作为域名来互相访问。

例如，容器A和B挂载了名叫abnet的network，那么在A中访问http://abnet:3000可以访问B中localhost:3000上的服务。在B中也同理。

我们使用-p暴露端口将容器内端口映射到到宿主机的一个端口上。

7.1 运行时挂载network

要在运行容器时为其挂载network只需要加上参数即可，如果该名称网络不存在则会创建一个新的。

1	`--network NETWORK_NAME`

Docker默认创建三个network，host，bridge，none。使用host网络，则容器使用宿主机的网络环境，没有自己独立的网络环境。none则表示不配置网络。

默认的网络为bridge，每个容器有自己独立的网络环境，包括ip地址等。我们可以创建新的使用bridge模式的网络，实现更好的隔离以避免端口冲突。

7.2 管理network

要管理所有的network，需使用docker network相关命令

docker network ls 列出网络
docker network inspect NETWORK 查看网络详细信息
docker network connect NETWORK CONTAINER 将容器连接到某个网络
docker network disconnect NETWORK CONTAINER 解除连接
docker network create NETWORK 创建网络，默认使用bridge模式

8 Dockerfile构建镜像

上面提到，我们使用可以使用Dockerfile构建脚本来构建镜像。

8.1 Dockerfile语法

Dockerfile脚本实际上是基于某个镜像，再通过在容器中运行shell命令来完成容器配置。

我们创建一个文件夹，该文件夹下创建名为Dockerfile的文件

Dockerfile语法十分简单，常用命令为

RUN COMMAND 在容器内终端中运行COMMAND命令，
WORKDIR PATH 将当前目录设置为PATH，推荐使用，不推荐用cd
COPY SRC DST 复制文件或文件夹，前者为宿主机上的路径，后者为容器内路径，无需加前缀
FROM REPO:TAG 选择基于哪个镜像，若本地没有该镜像则尝试拉取
USER USERNAME 指定之后RUN等命令的执行用户
SHELL [command, args...] command和args均为字符串，指定后面RUN使用的shell，如使用zsh(确认已安装)则为SHELL ['/usr/bin/zsh', '-c']。

8.2 构建镜像

将当前目录设置为上面创建的文件夹，运行以下命令即开始创建名为repo:tag的镜像。

1	`sudo docker build . -t repo:tag`

会一步一步运行Dockerfile中的命令，并且默认每一步都会保存一个缓存。如果你修改了一行命令，那么build时会加载该行命令前的缓存，从这一行开始构建。

9 其它配置

9.1 配置用户权限

Docker命令仅能由root用户和docker用户组中的用户运行。要使普通用户也可运行docker命令，除了使用sudo命令外，还可以将该用户加入到docker权限组。

使用如下命令可将当前用户添加到docker用户组，之后可以正常运行docker命令。

1	`sudo usermod -aG docker $USER`

9.2 Docker Desktop卸载残留

若安装过Docker Desktop但又卸载，在用户目录下可能残留配置和数据文件。当我们将当前用户加入到docker用户组之后，尝试直接运行docker命令时，可能会错误地尝试加载这些配置文件而产生错误。

例如提示无法连接至/home/username/.docker/desktop/docker.sock。

要解决该问题，只需删除用户目录下的.docker文件夹。