hppod

hppod means:

• hpp = header-only hpp
• pod = Portable Offline Development

Together: hppod = header-only + portable offline development.

It is a modern C++ project template focused on practical offline development: vendor dependencies in-repo, keep build rules simple, and make cross-platform or cross-toolchain work predictable.

Why hppod

• Portable by default: third-party headers are stored in third_party/, so the project is easy to move and build in restricted environments.
• Offline-friendly: no hard requirement on system package managers or internet access during build.
• CMake-first workflow: standard options for executable/library/examples and C++ standard switching.
• Dependency layering: dependencies can be gated by minimum C++ standard.
• Distribution-ready layout: build/install flow supports bin, examples, include, lib, etc, and docs.

Quick Start

cmake -S . -B build -DPROJECT_CXX_STANDARD=17
cmake --build build -j

Supported C++ standards: 11, 14, 17, 20.

CLI Workflow (hppod)

The project includes a root script: ./hppod.

Add a dependency scaffold

./hppod dep new asio \
  --source "https://think-async.com/Asio/" \
  --version "1.30.2" \
  --license "Boost Software License 1.0" \
  --cxx 11

This creates:

• third_party/asio/include/
• third_party/asio/VERSION.md

Then manually place library headers under third_party/asio/include/.

Useful commands:

./hppod dep list
./hppod dep list --cxx 17
./hppod dep new mylib --force

Add an example scaffold

./hppod eg new my_example

This creates:

• examples/my_example/main.cpp
• examples/my_example/README.md

Overwrite existing example entrypoint:

./hppod eg new my_example --force

Create a new project from this template

Use:

./hppod deploy /path/to/new_project \
  --name my_project \
  --deps asio,CLI11,nlohmann

Or batch-select dependencies by C++ standard:

./hppod deploy /path/to/new_project \
  --name my_project \
  --cxx 17

This deploys a full hppod-style project (including cmake/, examples/, toolchains/, docs/, and .gitignore), rewrites project identifiers, and keeps only selected dependencies.

Build, Cross-Compile, and Distribution

Native build

cmake -S . -B build -DPROJECT_CXX_STANDARD=20
cmake --build build -j

Cross-compilation

cmake -S . -B build-arm \
  -DCMAKE_TOOLCHAIN_FILE=toolchains/arm-linux-gnueabihf.cmake \
  -DARM_GNUEABIHF_GCC=/path/to/arm-linux-gnueabihf-gcc \
  -DARM_GNUEABIHF_GXX=/path/to/arm-linux-gnueabihf-g++ \
  -DARM_GNUEABIHF_SYSROOT=/path/to/arm-sysroot \
  -DPROJECT_CXX_STANDARD=17
cmake --build build-arm -j

Or AArch64:

cmake -S . -B build-aarch64 \
  -DCMAKE_TOOLCHAIN_FILE=toolchains/aarch64-linux-gnu.cmake \
  -DAARCH64_LINUX_GNU_GCC=/path/to/aarch64-linux-gnu-gcc \
  -DAARCH64_LINUX_GNU_GXX=/path/to/aarch64-linux-gnu-g++ \
  -DAARCH64_LINUX_GNU_SYSROOT=/path/to/aarch64-sysroot \
  -DPROJECT_CXX_STANDARD=17
cmake --build build-aarch64 -j

Distribution layout in build tree

By default (PROJECT_STAGE_DISTRIBUTION=ON), outputs are staged under:

• build/bin for main executables
• build/examples for example executables
• build/include and build/lib for library distribution (when applicable)
• build/etc and build/docs copied from source tree if present

Recommended packaging flow

For clean release artifacts, prefer install tree over zipping raw build/:

cmake -S . -B build -DPROJECT_CXX_STANDARD=17
cmake --build build -j
cmake --install build --prefix /tmp/hppod-stage

Then package /tmp/hppod-stage.

Suggested Coding Conventions

• Prefer header-only friendly design for reusable utility modules when reasonable.
• Keep public API headers under include/<namespace>/....
• Keep runtime app logic in src/, split by module (src/<module>/...).
• Register third-party libs in cmake/Dependencies.cmake and document metadata in third_party/<lib>/VERSION.md.
• Avoid mixing C and C++ styles in the same module unless required by external C libraries.
• Use target-based CMake patterns (target_include_directories, target_link_libraries) and avoid global compile flags.
• Keep examples minimal and focused: one feature, one executable.