Great question—scaling a C++ project with multiple moving parts (libraries, executables, bindings, docs, etc.) is no small feat, and it makes total sense to want a consensus-driven approach instead of piecing together random solutions from different corners. Let me walk you through the community-approved structure and build system integrations that’ll keep your project maintainable as it grows.

Start with a root layout that keeps concerns separated—this makes navigation, onboarding, and builds way easier. Here’s a standard structure the C++ community relies on:

• src/: All source code, split into purpose-specific subdirectories
  • lib/: Shared/static libraries (each library gets its own subdir, e.g., lib/network/, lib/utils/)
  • bin/: Executable applications (one subdir per app, like bin/cli_tool/, bin/gui_app/)
  • bindings/: Language bindings (e.g., bindings/python/ for pybind11, bindings/java/ for JNI)
• include/: Public header files (mirror the src/lib/ structure so consumers can #include <network/client.hpp>)
• docs/: Documentation (split into api/ for Doxygen-generated code docs, user/ for guides/tutorials)
• tests/: Unit/integration tests (mirror the src/ structure—tests/lib/network/ for network library tests)
• cmake/: CMake helper scripts (custom modules, toolchain files, reusable functions)
• configs/: Configuration files (build-time headers, app-specific JSON/YAML settings)
• scripts/: Utility scripts (code formatting, linting, release automation)
• README.md, LICENSE, CHANGELOG.md: Root-level metadata for new contributors and users

• Encapsulate libraries strictly: Each library should follow the single-responsibility principle. Avoid circular dependencies—if two libs need to interact, create a shared interface library or use dependency injection instead.
• Public vs. private headers: Only expose necessary headers in include/; keep internal implementation headers in src/lib/<module>/internal/ so they’re not visible to consumers.
• Semantic versioning: Use MAJOR.MINOR.PATCH versioning for libraries. If using CMake, set the VERSION property on library targets and add API compatibility checks if needed.
• Isolate bindings: Keep language bindings separate from core logic. Use tools like pybind11, SWIG, or Cython, and make bindings depend on core libraries (never the other way around).

CMake is the most widely adopted build system for modern C++ projects, and it plays seamlessly with the structure above. Here’s how to wire it up:

Root CMakeLists.txt #

Start with a root script that sets up the project, compiler standards, and global settings:

cmake_minimum_required(VERSION 3.16)
project(MyBigProject VERSION 1.0.0 LANGUAGES CXX)

# Enforce modern C++ standard (adjust to your needs)
set(CMAKE_CXX_STANDARD 17)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
set(CMAKE_CXX_EXTENSIONS OFF)

# Include helper scripts (e.g., for compiler warnings, dependency finding)
include(cmake/CompilerWarnings.cmake)
include(cmake/FindExternalDependencies.cmake)

# Add subdirectories to build
add_subdirectory(src/lib/network)
add_subdirectory(src/bin/cli_tool)
add_subdirectory(tests)
add_subdirectory(docs) # If building docs via CMake (e.g., Doxygen)

Library CMakeLists.txt (e.g., src/lib/network/) #

Each library gets its own script to define targets, headers, and dependencies:

add_library(network SHARED
    src/client.cpp
    src/server.cpp
)

# Link external dependencies (e.g., Boost.Asio)
target_link_libraries(network PRIVATE Boost::asio)

# Define include paths (public for consumers, private for internal code)
target_include_directories(network
    PUBLIC
        $<INSTALL_INTERFACE:include>
        $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include>
    PRIVATE
        ${PROJECT_SOURCE_DIR}/src/lib/network/internal
)

# Set version properties for shared libraries
set_target_properties(network PROPERTIES
    VERSION ${PROJECT_VERSION}
    SOVERSION ${PROJECT_VERSION_MAJOR}
)

# Install rules for packaging/distribution
install(TARGETS network
    LIBRARY DESTINATION lib
    ARCHIVE DESTINATION lib
    RUNTIME DESTINATION bin
)
install(DIRECTORY ${PROJECT_SOURCE_DIR}/include/network
    DESTINATION include
)

Executable CMakeLists.txt (e.g., src/bin/cli_tool/) #

Executables depend on core libraries and follow similar patterns:

add_executable(cli_tool
    src/main.cpp
    src/command_handler.cpp
)

# Link against your core libraries
target_link_libraries(cli_tool PRIVATE network utils)

# Install the executable to system bins
install(TARGETS cli_tool DESTINATION bin)

Testing with CTest #

Integrate tests using CTest and frameworks like Google Test:

# In tests/CMakeLists.txt
include(CTest)
add_subdirectory(lib/network)

# In tests/lib/network/CMakeLists.txt
add_executable(network_tests
    client_tests.cpp
    server_tests.cpp
)

target_link_libraries(network_tests PRIVATE network GTest::GTest GTest::Main)

# Register test with CTest
add_test(NAME NetworkTests COMMAND network_tests)

While CMake is more modern, Autotools is still used in legacy or Unix-focused projects. For a similar structure:

• Use configure.ac at the root to set up the project, check system dependencies, and define build flags.
• Each library/executable gets a Makefile.am in its subdirectory. For example, src/lib/network/Makefile.am lists sources, include paths, and linked libraries.
• Public headers in include/ are included via AM_CPPFLAGS to ensure accessibility.
• Tests can be run with make check using frameworks like Check or Google Test.

• CI/CD integration: Use GitHub Actions, GitLab CI, or Jenkins to run builds, tests, and linting on every commit—catch issues early.
• Code style enforcement: Use clang-format and clang-tidy to keep code consistent. Add scripts in scripts/ to auto-format code before commits.
• Dependency management: Use CMake’s FetchContent for small external dependencies, or package managers like Conan, vcpkg, or Spack for larger ecosystems.
• Documentation sync: Keep docs up to date with code—use Doxygen for API docs and Sphinx for user guides. Add a docs/CMakeLists.txt to build docs as part of the project.
• Release automation: Write scripts to tag versions, generate changelogs, and create packages (DEB, RPM, tarballs) using CPack (for CMake) or Autotools’ make dist.

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