CMake未在C++项目中构建Protobuf源文件的诊断方法

项目背景 #

这是一个使用Protobuf和CMake构建的C++测试项目，目录结构如下：

protobuf-example/
  proto/
    CMakeLists.txt
    message.proto
  CMakeLists.txt
  main.cpp

各文件内容：

proto/CMakeLists.txt #

set(PROTO_FILES message.proto)
set(GENERATED_PROTO_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated)
file(MAKE_DIRECTORY ${GENERATED_PROTO_DIR})

protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS ${PROTO_FILES})

add_library(proto_files STATIC ${PROTO_SRCS})

target_include_directories(proto_files PUBLIC ${Protobuf_INCLUDE_DIRS} ${CMAKE_CURRENT_BINARY_DIR})

target_link_libraries(proto_files PUBLIC ${Protobuf_LIBRARIES})

message.proto #

syntax = "proto3";

message Person {
  string name = 1;
  int32 age = 2;
  string email = 3;
}

根目录CMakeLists.txt #

cmake_minimum_required(VERSION 3.10)
project(ProtobufExample LANGUAGES CXX)

find_package(Protobuf REQUIRED)

add_executable(protobuf_example main.cpp)

target_link_libraries(protobuf_example PRIVATE proto_files)

main.cpp #

#include <iostream>
#include <fstream>
#include "message.pb.h"

void serializePerson(const std::string& filename) {
    Person person;
    person.set_name("John Doe");
    person.set_age(30);
    person.set_email("john.doe@example.com");

    std::ofstream output(filename, std::ios::binary);
    if (!person.SerializeToOstream(&output)) {
        std::cerr << "Failed to serialize data." << std::endl;
    }
}

void deserializePerson(const std::string& filename) {
    Person person;
    std::ifstream input(filename, std::ios::binary);
    if (!person.ParseFromIstream(&input)) {
        std::cerr << "Failed to parse data." << std::endl;
    } else {
        std::cout << "Name: " << person.name() << "\n"
                  << "Age: " << person.age() << "\n"
                  << "Email: " << person.email() << std::endl;
    }
}

int main() {
    GOOGLE_PROTOBUF_VERIFY_VERSION;

    const std::string filename = "person.data";

    serializePerson(filename);
    deserializePerson(filename);

    google::protobuf::ShutdownProtobufLibrary();
    return 0;
}

编译时出现错误：

fatal error: message.pb.h: No such file or directory

且build/proto/generated目录为空，说明protobuf_generate_cpp未生成对应的C++文件，可按以下步骤诊断：

诊断步骤 #

1. 检查根目录CMake是否加载子目录 #

根目录CMakeLists.txt中缺少add_subdirectory(proto)，这会导致proto子目录的构建逻辑完全不会被执行，proto_files库和Protobuf代码生成步骤都不会运行。这是最可能的核心问题，需在find_package(Protobuf REQUIRED)之后添加：

add_subdirectory(proto)

2. 验证Protobuf代码生成路径配置 #

当前proto/CMakeLists.txt指定了GENERATED_PROTO_DIR但未传递给protobuf_generate_cpp，默认生成的头文件会放在proto子目录的二进制目录下，而非generated子文件夹。可修改代码生成命令，显式指定输出目录：

protobuf_generate_cpp(PROTO_SRCS PROTO_HDRS
    OUT_DIR ${GENERATED_PROTO_DIR}
    ${PROTO_FILES}
)

同时更新头文件包含路径，确保主项目能找到生成的头文件：

target_include_directories(proto_files PUBLIC 
    ${Protobuf_INCLUDE_DIRS} 
    ${GENERATED_PROTO_DIR}
)

3. 确认Protobuf包是否被正确找到 #

重新运行CMake时，查看控制台输出，确认是否有类似-- Found Protobuf: /path/to/protobuf的提示。如果没有，说明CMake未找到Protobuf，需：

• 确认Protobuf已正确安装
• 设置环境变量Protobuf_DIR指向Protobuf的CMake配置文件目录（通常是/usr/lib/cmake/protobuf或安装路径下的对应目录）
• 运行CMake时显式指定：cmake .. -DProtobuf_DIR=/path/to/protobuf/cmake

4. 手动测试protoc代码生成 #

直接用protoc命令生成代码，验证.proto文件是否合法：

cd proto
protoc --cpp_out=./generated message.proto

如果命令能成功生成message.pb.h和message.pb.cc，说明.proto文件语法没问题，问题出在CMake配置；如果命令失败，检查.proto文件的语法（比如是否使用了中文引号、语法错误等）。

5. 查看CMake构建详细日志 #

重新运行CMake和编译命令，开启 verbose 模式查看详细日志：

# 进入构建目录
cd build
# 重新生成Makefile并查看详细日志
cmake .. --verbose
# 编译并查看详细过程
make --verbose

通过日志确认protobuf_generate_cpp是否被执行，是否有错误信息被忽略。

6. 检查CMake版本兼容性 #

当前指定的最低CMake版本是3.10，protobuf_generate_cpp在旧版本中可能存在行为差异。建议升级CMake到3.15及以上版本，或查阅对应CMake版本的Protobuf模块文档，确认命令语法是否正确。

内容的提问来源于stack exchange，提问作者user2138149