Why ncmake

Why ncmake

Packaging a Nextcloud app is a solved problem — there are good tools for it already. ncmake exists because it makes a few different design bets, and this page is honest about which they are, how it compares to the established krankerl, and which files an ncmake app no longer has to carry.

The design bets

Nothing on your host. make build runs composer and npm in throwaway containers picked from the app's own declared PHP and Node versions. You need no PHP, no Node, no version manager — only podman or docker (or RUNTIME=bare if you insist on host tools). You can build a PHP 8.1 app on a machine that has only PHP 8.4, or no PHP at all.

Nothing to configure. ncmake reads what it needs from the files an app has anyway — appinfo/info.xml, composer.json, package.json, .gitignore (see How ncmake understands your app). A standard app needs no build config of its own: drop in the bootstrap stub, run make, done. An app that genuinely deviates sets a single variable in ncmake.mk (see Per-app tuning).

Keep model, not ignore model. What ships is defined as an allowlist of the standard runtime paths, each only when it exists (see Building and packaging). A new dev file cannot leak into a release, because it is not on the list; a missing runtime directory fails loudly instead of shipping a broken app. .nextcloudignore still exists, but only to trim within that set (test ballast inside a shipped vendor package), not as the sole line of defence.

One tool, shared and self-updating. The real Makefile lives once in a per-machine cache and is fetched by a dozen-line stub. Update ncmake and every app on the machine follows — there is no copy of build logic to maintain per repository. NCMAKE_REF pins a version when you want to freeze it.

The workflow lifecycle, not just packaging. ncmake installs your CI workflows from their upstream templates, tracks which are yours and which drifted, and can open a pull request to update them on a schedule (see Workflows and Workflow updater). Releasing is a flow of its own: a validated version bump, a changelog generated from your conventional commits, a signed tag, the tarball, and App Store publishing that signs the exact bytes the store will fetch (see Releasing and App Store).

Compared to krankerl

krankerl is the established CLI for packaging and publishing Nextcloud apps — a Rust binary by Christoph Wurst, and a good tool. ncmake covers the same ground for packaging, signing and publishing, so the differences are in how, not whether:

	krankerl	ncmake
Form	a compiled Rust binary you install (AUR, .deb, cargo install)	a Makefile fetched by a committed stub into a per-machine cache
Build steps	listed in krankerl.toml ([package] before_cmds, e.g. composer install, npm run build)	auto-detected from composer.json / package.json; overridable in ncmake.mk
Build environment	the commands run on your host	throwaway containers on the app's declared PHP/Node version; host needs no toolchain
Shipped file set	a full copy filtered by .nextcloudignore (an exclude list)	an allowlist of runtime paths, with .nextcloudignore trimming within it
Packaging is reproducible	yes — it stages into build/artifacts, not the working tree	yes — it stages into build/stage, and the same staging feeds dist, rsync and cp
Version bump	krankerl version major|minor|patch	make version (validates against the latest tag, branches, syncs lockfiles)
Changelog	—	make changelog generates the section from conventional commits
Sign & publish	krankerl sign, krankerl publish (--nightly)	make sign, make publish (GH=1, NIGHTLY=1), signing the downloaded bytes
CI workflows	—	installed, tracked and auto-updated from upstream templates

The honest summary: if you want a single native binary that packages and publishes and you are happy to keep a krankerl.toml and a local toolchain, krankerl does that well. ncmake trades the binary for a shared Makefile, removes the per-app config and the host toolchain, and adds the CI-workflow and release lifecycle around the packaging. Both stage their build for reproducibility, both sign the app store upload; neither is a fork or reimplementation of the other.

DRY: which files an ncmake app stops carrying

The whole point of deriving everything from the app is that the app stops carrying redundant scaffolding. With ncmake in place, these are gone:

• krankerl.toml or any equivalent build-recipe file — the build steps come from composer.json and package.json.
• A hand-written Makefile full of build logic — the repository carries only the dozen-line stub, identical across every app.
• Bespoke packaging or exclude scripts — the keep model plus .nextcloudignore define the shipped set.
• A per-app release.yml that re-lists the build steps, the includes and the excludes — the copy-paste that sits, and quietly rots, in countless Nextcloud apps: the CI packaging drifts away from what the maintainer builds locally, and one day a release ships a file set nobody deployed. ncmake's release.yml carries no app-specific data at all. The shipped set comes from the keep model plus .nextcloudignore, the build is make build && make dist, and the tarball is found by glob, so the workflow is byte-identical across every ncmake app. Local build and CI release are the same code path by construction — they cannot disagree, because there is only one of them. The packaging is reasoned out once and lives in one place, instead of being re-derived, and silently diverging, in every repository.
• Hand-maintained .github/workflows/* — they are installed from upstream templates and kept current by the workflow updater; only genuinely app-specific workflows are written by hand.
• The github-actions ecosystem in dependabot.yml — the updater owns .github/workflows/, so that entry comes out (npm and Composer stay under Dependabot).
• Routine CHANGELOG.md editing — the release section is generated from the conventional commits since the last tag, then yours to extend by hand.

What stays is the app itself, and one stub. That is the DRY principle the whole of ncmake is built on: a fact lives in exactly one place, and everything else is derived from it.