SAMU(1)

💖 SAMU(1) — the bestie build tool 💖

okay so. you know how make is out here doing the most and also being kind of a mess? yeah. so samu is a ninja-compatible build tool, it's in the General Commands Manual, and it's lowkey iconic. it reads your manifest, it rebuilds the stuff that's out of date, and it does it fast. that's the whole vibe. periodt. 🎀

---

✨ SYNOPSIS ✨

samu [-C dir] [-d debugflag] [-f buildfile] [-j maxjobs] [-k maxfail]
     [-l maxload] [-w warnflag=action] [-nv] [target...]
samu [-C dir] [-f buildfile] -t clean [-gr] [target...]
samu [-C dir] [-f buildfile] -t compdb [-x] [rule...]
samu [-C dir] [-f buildfile] -t commands [target...]
samu [-C dir] [-f buildfile] -t graph [target...]
samu [-C dir] [-f buildfile] -t query [target...]
samu [-C dir] [-f buildfile] -t targets [depth [maxdepth]]
samu [-C dir] [-f buildfile] -t targets rule [rulename]
samu [-C dir] [-f buildfile] -t targets all

---

🌸 DESCRIPTION 🌸

so samu loads a build manifest from buildfile and rebuilds targets if they're out of date. that's it, that's the job. 💅

if you don't name any targets, it builds the manifest's default targets. and if there are no default targets at all? it builds the leaf nodes of the dependency graph — meaning the outputs that have no consuming action. cute, right? it just finds the ends of the chain and goes.

🦋 when is a target "out of date" bestie

a target counts as out of date if any of these are true:

• it's older than the generating action's newest input
• it has no entry in the build log
• the command used to build it is different from what was used previously

⚠️ one lil exception okay: targets built with generator rules are not rebuilt if the command changes. they're special like that. 👑

🧹 the clean tool

if you use the clean tool, targets get cleaned instead of built. when a target is cleaned, it's removed — and all of its inputs are cleaned too. it's giving domino effect.

• targets with no generating actions are never removed.
• targets built with generator rules are only removed if you pass -g.

🗒️ the commands tool

if you use the commands tool, you get a list of shell commands used to build the specified (or default) targets. printed. right there. for you. 🫶

🧾 the compdb tool

if you use the compdb tool, a compilation database is printed instead — https://clang.llvm.org/docs/JSONCompilationDatabase.html if you wanna read up, iykyk.

🕸️ the graph tool

if you use the graph tool, a graphviz dot file is printed instead. yes bestie, pretty pictures of your dependency tree. 🌈

🔍 the query tool

if you use the query tool, the inputs and outputs of the targets get printed instead.

🎯 the targets tool

if you use the targets tool, a list of targets will be displayed — either by rule or by depth. the first argument decides how they show up:

• depth — an indented tree of targets gets displayed, starting from the root targets (those with no dependent targets), going up to the depth specified by maxdepth (defaults to 1).
• rule — if rulename is given, you get a list of targets using that rule. otherwise, you get a list of source files. 🙈
• all — a list of all targets gets displayed. everything. the whole closet. 💀

---

💅 OPTIONS 💅

• -C — switch working directory to dir before building. like walking into the right room first.
• -d — enable a debugging option. you can pass this flag multiple times to turn on multiple debugging options at once. possible values for debugflag are:
  • explain — print messages explaining why outputs were dirty. the receipts!! 🧾
  • keepdepfile — don't remove $depfile after it was parsed.
  • keeprsp — don't remove $rspfile after job completion or failure.
• -f — load manifest from buildfile instead of build.ninja.
• -j — run up to maxjobs jobs in parallel (default is based on number of CPUs). if zero, allow unlimited concurrent jobs. chaos mode enabled. 🔥
• -k — allow up to maxfail job failures. if negative or zero, allow any number of job failures. nothing can stop us.
• -l — do not spawn new jobs if the system load percentage is greater than maxload. if zero, spawn jobs as soon as possible.
• -n — do not actually execute the commands or update the log. a lil dress rehearsal. 🎭
• -v — print full commands instead of just the description.
• -w — control how certain errors are handled. if warnflag is dupbuild, action specifies what to do if an output is listed in multiple build edges. if action is err, treat it like an error and fail. if action is warn, only print a diagnostic message.
• -t — instead of building, invoke a subtool. all arguments and flags after the subtool are interpreted by the subtool. the currently supported subtools are clean, commands, compdb, graph, query, and targets.
• -g — when cleaning, also clean outputs of generator actions.
• -r — targets are interpreted as rules, and all outputs of actions with the specified rule types will be cleaned instead.
• -x — when printing a compilation database, replace @$rspfile with $rspfile_content (with <blank> in place of <newline>).

---

🌿 ENVIRONMENT 🌿

• SAMUFLAGS — options for samu that get applied before those specified on the command-line. the only options allowed in SAMUFLAGS are -v, -j and -l. that's the whole guest list, no plus-ones. 🚫
• NINJA_STATUS — the status output printed to the left of each rule description, using printf-like conversion specifiers. if unset, the default is "[%s/%t] ".

available conversion specifiers:

• %s — number of started jobs.
• %f — number of finished jobs.
• %t — total number of jobs.
• %r — number of running jobs.
• %u — number of remaining jobs.
• %p — percentage of completed jobs.
• %o — rate of finished jobs per second (to 1 decimal place).
• %e — elapsed time in seconds (to 3 decimal places).
• %% — the % character. (yes you gotta escape it, it's giving printf energy)

---

👀 SEE ALSO 👀

• make(1)

---

okay that's the whole page bestie, go forth and build ✨🦋🌸

this manual page is from Debian, dated December 29, 2024 — shoutout to the Debian girlies for packaging this. 💜 no cap, samu ate and left no crumbs. mwah. 💋