perfect-helloworld

A (deliberately over-engineered) reference-grade C "Hello World" project.

This is what a modern, best practice-oriented C project might look like in 2026. The project is aimed at developers looking for a opinionated and modern starting point.

Feedback and constructive criticism are welcomed!

Non-goals

• Being the smallest or simplest C "Hello World" example
• Avoiding modern tooling for portability

Features

• Meson build system
• Prioritizes Clang instead of GCC
• Cross-compilation support
• Nix flake for dependency management
• MIT license
• GitHub Actions CI
• Standard project structure (docs/, include/, src/, tests/, scripts/)
• Uses llvm-vs-code-extensions.vscode-clangd instead of ms-vscode.cpptools
• Doxygen support
• Pkg-config (generates .pc file)
• Unit testing support via Unity testing framework

Pre-commit hooks

The following checks are enforced via prek (a lightweight alternative to pre-commit):

• clang-format
• clang-tidy
• meson format
• nix flake check
• nix fmt
• IWYU
• cppcheck
• REUSE
• jq (for JSON formatting);

Building from source

git clone https://github.com/synalice/perfect-helloworld
cd perfect-helloworld
meson setup builddir/
meson compile -C builddir/
meson install -C builddir/

Building with Nix

git clone https://github.com/synalice/perfect-helloworld
cd perfect-helloworld
nix build .#default.out
nix build .#default.dev
nix build .#default.doc

Using Nix devShell

Nix can automatically install all dependencies, toolchain and setup the whole development environment. To do that run

nix develop

Cross-compilation

To cross-compile the project, run this script

./scripts/cross-compile.sh aarch64-multiplatform out

Warning

Invoking it for the first time may take some time, because Nix will download or build some parts of the cross toolchain.

Tip

To cross-compile for different host architectures, replace aarch64-multiplatform with riscv64 or something else. Read more here.

Tip

To build the dev or doc derivation, replace out with dev or doc.

AddressSanitizer aka ASan aka Sanitizers

To build the project with AddressSanitizer configure the project like this

meson setup --reconfigure -Db_sanitize=address,undefined,leak -Db_lundef=false builddir/

Note

Without -Db_lundef=false Meson complains with the following warning message:

WARNING: Trying to use ['address', 'undefined', 'leak'] sanitizer on Clang with b_lundef.
This will probably not work.
Try setting b_lundef to false instead.

License

This project is under the MIT license.