---
name: cpp-meson-build
description: |
  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.
disable-model-invocation: 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

```sh
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`