Getting started

Getting started

Adding ncmake to an app is a single committed file. This page covers the two ways to install it, how the shared Makefile keeps itself current, what to put in your app's own README, and the badge.

🧩 The bootstrap stub (recommended)

Put the bootstrap stub into the root of your app repository, once:

curl -fLO https://raw.githubusercontent.com/ernolf/ncmake/main/bootstrap/Makefile
git add Makefile

The stub is a dozen lines that never change. It fetches the real Makefile into a per-machine cache and includes it from there. Every developer who clones your app and runs make automatically gets the current ncmake, on every machine, for every app, from one shared cache.

The stub is the only thing you install by hand. Everything else ncmake contributes to your repository — the CI workflows (see Workflows) — is installed and updated through make targets once the stub is in place.

Important

Only the stub lands in your repository. The stub file you committed stays byte-identical forever; the fetched Makefile lives in ~/.cache/ncmake/, outside of every project. Running make creates or modifies nothing in your checkout (apart from the usual build outputs such as build/, js/ and vendor/, which belong in your .gitignore anyway, as in every Nextcloud app). git status stays clean; there is nothing extra to ignore.

How the cache stays current. At most once per day (NCMAKE_TTL_MIN, default 1440 minutes) the cached Makefile checks upstream with a conditional GET (ETag): unchanged or offline keeps the cache, a new version replaces it and is used from the next run on. make self-update forces a refresh at any time.

Pinning a version. By default the stub follows the main branch. To pin your app to a fixed ncmake version, set NCMAKE_REF in the stub to a tag:

NCMAKE_REF ?= v1.0.0

📄 The full copy (self-contained alternative)

If you prefer a repository without any fetch-at-build-time behavior, commit the full Makefile instead:

curl -fLo Makefile https://raw.githubusercontent.com/ernolf/ncmake/main/core/Makefile

A committed copy never modifies itself. make self-update downloads the newest version over it; review the diff and commit it like any other change.

🔍 What happens when you run make

flowchart TD
    A["make <target>"] --> B{Stub or full copy?}
    B -- stub --> C{"~/.cache/ncmake/<br>Makefile present?"}
    C -- no --> D[fetch once from GitHub]
    C -- yes --> E{"older than<br>NCMAKE_TTL_MIN?"}
    E -- yes --> F["conditional GET (ETag):<br>new version → refresh cache<br>unchanged/offline → keep cache"]
    E -- no --> G
    D --> G[include cached Makefile]
    F --> G
    B -- full copy --> H[use the committed Makefile as is]
    G --> I[run the target]
    H --> I

Loading

The first make after a fresh git clone needs network once (to fill the cache); after that everything works offline.

📝 The Installation section for your app's README

Every ncmake app's install instructions should read the same and stay short: one line for the App Store, one that points at the shared install guide. Do not repeat tarball or make steps in the app README — they live in the guide, in one place, so a change is made once.

If the app is in the App Store:

## Installation

The app is published in the [App Store](https://apps.nextcloud.com/apps/<app>). Install it through [Nextcloud's app management UI](https://docs.nextcloud.com/server/latest/admin_manual/apps_management.html#managing-apps) (**Apps** → search for **<App name>** → Install) or with `occ app:enable <app>`.

It is built with [ncmake](https://github.com/ernolf/ncmake). To build and install it from source — release tarball, `make rsync` or `make cp` — see the [installation guide](https://github.com/ernolf/ncmake/wiki/Installation).

If it is not (yet) in the App Store, drop the first paragraph:

## Installation

This app is not yet in the App Store. It is built with [ncmake](https://github.com/ernolf/ncmake). To build and install it from source — release tarball, `make rsync` or `make cp` — see the [installation guide](https://github.com/ernolf/ncmake/wiki/Installation).

Replace <app> with the app id and <App name> with the app's display name (the exact term users search for in the App Store). Anything genuinely app-specific — a migration note, a link to the app's own developer docs — follows as its own subsection.

🏅 Show that your app uses ncmake

If ncmake is useful to you, add the badge to your app's README:

[![built with ncmake](https://cdn.jsdelivr.net/gh/ernolf/ncmake@main/img/ncmake-badge.svg)](https://github.com/ernolf/ncmake)

The badge is a small SVG served from this repository through the jsDelivr CDN and links here; it is purely cosmetic and reports nothing back. To actually find the apps that use ncmake, search GitHub's code search for the fetch URL every stub carries — that signal does not depend on the badge:

https://github.com/search?q=%22raw.githubusercontent.com%2Fernolf%2Fncmake%22&type=code

The same from the command line needs a recent gh (2.10 or newer, for the search command):

gh search code 'raw.githubusercontent.com/ernolf/ncmake' --json repository --jq '.[].repository.nameWithOwner' | sort -u

Note

Both queries hit code-search indexes that only contain public repositories GitHub has already picked up, so a freshly created consumer can take weeks to appear. The bootstrap stub is committed regardless, so a consumer becomes findable the moment its repo is indexed.

Next steps

• How ncmake understands your app — what ncmake reads from your app's own files
• Building and packaging — make build, the keep model, deploying to a test instance
• Step by step — the whole life of an app with ncmake, in order