screen_cast/.agents/skills/cpp-meson-build/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
cpp-meson-build	Guidelines for C++20 development and Meson build management in the screen_cast project. Read before changing source files, build files, dependencies, or toolchain configuration.	false

cpp-meson-build

Guidelines for C++20 development and Meson build management in the screen_cast project.

Scope

Use this skill for:

• Adding or changing C++ source files, headers, or namespaces.
• Modifying meson.build files, compiler flags, or targets.
• Adding or updating dependencies (system libraries, pkg-config, subprojects).
• Toolchain, sanitizer, static-analysis, or formatter configuration.

Meson conventions

• Keep meson.build files declarative and readable.
• Prefer dependency() with pkg-config names over manual -l flags.
• Pin required C++ standard: cpp_std = 'c++20'.
• Put one target per meson.build file where practical.
• Use include_directories('include') for the public API headers.
• Declare unit tests with test() and keep them deterministic.

Dependency verification

Before adding a new dependency:

• verify the pkg-config file exists on the target system (e.g. pkg-config --exists libavcodec);
• check that the required headers compile;
• update meson.build and this skill's references/ if needed.

Error handling

• Prefer std::expected<T,E>, std::optional<T>, or std::error_code over exceptions for recoverable failures.
• Use RAII wrappers; avoid raw owning pointers.
• Keep headers minimal and forward-declare where possible.

Modern C++ guidelines

All project code must use C++20 idioms:

• Ownership: use std::unique_ptr and std::shared_ptr; no raw new/delete or raw owning pointers.
• Optional values: use std::optional<T> instead of sentinel values or out-parameters.
• Fallible operations: use std::expected<T,E> or std::error_code for recoverable errors; avoid exceptions for control flow.
• Views: use std::span<T> for non-owning buffers and std::string_view for read-only strings.
• Compile-time: prefer constexpr/consteval where possible.
• Type safety: prefer enum class, std::variant, and std::optional over bare integers or bool flags.
• Concurrency: prefer std::jthread, std::stop_token, and standard synchronization primitives.
• Containers: use standard containers; avoid C arrays and raw buffers.
• Formatting/time: use <format> / std::format and <chrono>.
• Algorithms: prefer std::ranges over hand-rolled loops where it improves clarity.
• Callables: avoid std::function unless type erasure is required.
• Concepts: use requires clauses to express interface contracts where beneficial.

Reject C-style patterns (printf, sprintf, manual memory management with malloc/free, raw arrays) when a standard-library equivalent exists.

Useful commands

meson setup build
meson compile -C build
meson test -C build --print-errorlogs
meson configure build

References

• meson.build (project root)
• meson_options.txt (if present)
• docs/ARCHITECTURE.md
• docs/PHASES.md