Project Scaffolding
The scaffolding system generates a complete project structure from templates, giving new components a working build system, CI configuration, and standard project files from the start. The generated files implement the component protocol defined in ADR-0004 — Workspace and Component Protocol and the build system conventions from ADR-0005 — CMake as the Build System.
Usage
Create a directory, initialize a Git repository, and run make init:
mkdir mylib && cd mylib
git init
make -C /path/to/ideal-cmake-modules init NAME=mylib DESC="A sample library"
Variables
| Variable | Default | Description |
|---|---|---|
DESC | (required) | Short description |
DIR | Working directory | Output directory |
MAINTAINER | Carlos Prado Garcia <cpradog@cpradog.com> | Package maintainer |
NAME | (required) | Component name |
REPO_NAME | ideal-<NAME> | Repository name in sr.ht |
REPO_URL | https://git.sr.ht/~cpradog/<REPO_NAME>/ | Repository URL |
Override defaults by passing them on the command line:
make -C /path/to/ideal-cmake-modules init NAME=mylib DESC="My library" REPO_NAME=my-custom-repo
Generated files
| File | Description |
|---|---|
.build.yml | SourceHut CI manifest |
.clangd | Clangd language server configuration |
.editorconfig | Editor formatting settings (UTF-8, 2-space indent, 120 cols) |
.gitignore | Git ignore rules for build artifacts |
CMakeLists.txt | Project definition with IdealCmakeModules dependency |
CMakePresets.json | Configure, build, and test presets for all standard workflows |
LICENSE | EUPL-1.2 with Ideal Plugin Exception |
Makefile | GNU Make wrapper around CMake presets |
README.md | Project README with build instructions |
Makefile targets
The generated Makefile provides targets that wrap the corresponding CMake presets and build targets:
| Target | Description |
|---|---|
build | Configure and build (default) |
test | Run the test suite |
tidy | Run clang-tidy with auto-fix |
check | Run tidy and tests |
coverage | Build and generate coverage report |
pot-update | Extract translatable strings into .pot |
po-update | Update all .po files from the template |
docs | Generate documentation |
push-docs | Deploy documentation to portal |
install | Install to configured prefix |
uninstall | Uninstall |
dist | Create source tarball |
apk | Build APK package |
clean | Clean build artifacts |
distclean | Remove all generated files |
Pass PRESET= to select a build preset (default release), and V=1 for verbose output.
Presets
The CMakePresets.json defines configure, build, and test presets for all standard workflows. All presets
inherit from a hidden base preset that sets the build directory to build/<preset> and disables all optional
features by default.
| Preset | Build type | Testing | Features |
|---|---|---|---|
asan | Debug | On | AddressSanitizer, UndefinedBehaviorSanitizer |
ci | Debug | On | Documentation |
coverage | Debug | On | Code coverage instrumentation |
debug | Debug | On | Full debug symbols |
dev | RelWithDebInfo | On | Optimized with debug info |
docs | Release | Off | Documentation generation |
release | Release | Off | Optimized release build (default) |
tsan | Debug | On | ThreadSanitizer |
ubsan | Debug | On | UndefinedBehaviorSanitizer |
Select a preset by passing PRESET= to Make:
make build PRESET=dev
make test PRESET=dev
make build PRESET=asan
make test PRESET=asan
The default preset is release.
CI pipeline
The .build.yml manifest defines a SourceHut CI pipeline that runs on Alpine
Linux edge. The pipeline is divided into two phases.
The first phase runs on every push:
| Step | Description |
|---|---|
build | Builds the project with make build PRESET=ci |
test | Runs the test suite with make test PRESET=ci |
build_docs | Generates documentation and validates links |
The second phase only runs on release branches (main and stable/*). All other branches stop after the
first phase.
| Step | Description |
|---|---|
version | Determines the next version from conventional commits |
dist | Creates a source tarball and uploads it as a CI artifact |
deploy_docs | Publishes documentation to the portal repository |
package | Builds an APK package and publishes it to the Ideal APK repository |
The version step uses the version bump script to derive the next version from the commit history.
On main, prerelease versions are tagged with an rc suffix. On stable/* branches, only non-breaking changes
are allowed. If the computed version matches the current tag, the pipeline stops — there is nothing to release.
What's next
After running make init:
- Add your source code under
src/and headers underinclude/. - Edit
CMakeLists.txtto define your targets. - Build with
make build.