GNU Make notes

1 files changed, 732 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e7f1d4f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,732 @@
+# GNU Make
+
+Notes, idioms, and worked examples for [GNU Make](https://www.gnu.org/software/make/) — the tool for describing how files are built from other files.
+
+Everything is explained inline below. The handful of demos worth running end‑to‑end live under [`examples/`](examples/).
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Rules](#rules)
+- [Recipes](#recipes)
+- [Variables](#variables)
+- [Automatic variables](#automatic-variables)
+- [Functions](#functions)
+- [Conditionals](#conditionals)
+- [Prerequisites and rebuild semantics](#prerequisites-and-rebuild-semantics)
+- [Special targets and directives](#special-targets-and-directives)
+- [Running make](#running-make)
+- [Gotchas](#gotchas)
+- [Visualising the dependency graph](#visualising-the-dependency-graph)
+- [Worked examples](#worked-examples)
+
+---
+
+## Introduction
+
+GNU `make` defines a language for describing the relationships between files. Using `make` forces you to think about each component and how the pieces fit together.
+
+A Makefile is a list of **rules**. A rule has three parts — a **target**, its **prerequisites**, and a **recipe**:
+
+```
+target: prereq1 prereq2
+<tab>command
+<tab>command
+```
+
+- The **target** is usually the file to create.
+- The **prerequisites** (also called dependencies) are files that must exist and be up to date before the target can be built.
+- The **recipe** is the shell command(s) that build the target from its prerequisites.
+
+If a prerequisite has its own rule, `make` builds it first. `make` only rebuilds a target when it is missing or older than one of its prerequisites — this is the whole point: it does the minimum work needed to bring things up to date.
+
+> **The tab rule.** Every recipe line *must* start with a real tab character, not spaces. This trips up everyone at least once. If you must use something else, set [`.RECIPEPREFIX`](https://www.gnu.org/software/make/manual/html_node/Special-Variables.html) (e.g. `.RECIPEPREFIX = >`).
+
+The examples below assume a small sample dataset:
+
+```bash
+mkdir data; for i in {1..4}; do echo ${i} > data/${i}.fa; done
+```
+
+---
+
+## Rules
+
+A rule defines a target and its prerequisites (if any). There are several kinds:
+
+1. **Explicit rules** name a specific target — the most common kind.
+2. **Pattern rules** use the `%` wildcard instead of explicit filenames, so the rule applies to any target matching the pattern.
+3. **Implicit rules** are pattern or suffix rules built into Make's database (e.g. how to make `%.o` from `%.c`).
+4. **Static pattern rules** are pattern rules restricted to a specific list of targets: `targets: pattern: prereq-pattern`.
+
+*Suffix rules* also exist but are obsolete — pattern rules are clearer and more general.
+
+### Explicit and pattern rules
+
+A small C build shows both an explicit rule and a pattern rule working together:
+
+```makefile
+CC     := gcc
+CFLAGS := -Wall -O2
+
+# Pattern rule: any %.o can be built from the matching %.c.
+# -c compiles without linking.
+%.o: %.c
+	$(CC) $(CFLAGS) -c $< -o $@
+
+# Explicit rule: link the objects into the final binary.
+hello: main.o util.o
+	$(CC) $(CFLAGS) $^ -o $@
+```
+
+`make hello` builds `main.o` and `util.o` via the pattern rule, then links them. (`$<`, `$@` and `$^` are *automatic variables* — see [below](#automatic-variables).)
+
+### The default goal
+
+Running `make` with no target builds the **default goal**: the first *normal* target in the file. Make skips targets whose names start with a dot (special targets like `.PHONY`) and pattern rules when choosing it, so neither becomes the default. By convention the default goal is a phony `all` target that depends on everything you normally want built:
+
+```makefile
+all: hello
+```
+
+You can set it explicitly with `.DEFAULT_GOAL := some_target`.
+
+### Multiple targets and grouped targets
+
+Listing several targets in one rule means the recipe runs **once per target**, with `$@` set to whichever is being built:
+
+```makefile
+# `make first.txt` makes first.txt; `make second.txt` makes second.txt.
+first.txt second.txt:
+	@echo "Generating: $@"
+	touch $@
+```
+
+When a single recipe produces *all* the listed files at once, use a **grouped target** with `&:` (GNU Make 4.3+). The recipe runs only once for the whole group:
+
+```makefile
+# Both files are produced together by one invocation.
+fifth.txt sixth.txt &:
+	@echo "Generating fifth.txt and sixth.txt together"
+	touch fifth.txt sixth.txt
+```
+
+---
+
+## Recipes
+
+A **recipe** is the set of shell commands Make runs to update a target. Each line is indented with a tab.
+
+### Each line runs in its own shell
+
+By default Make runs every recipe line in a *separate* shell, so `cd`, shell variables, and other state do **not** carry from one line to the next:
+
+```makefile
+broken:
+	cd /tmp
+	pwd          # prints the original directory, NOT /tmp
+
+working:
+	cd /tmp && pwd   # prints /tmp
+```
+
+Use a trailing backslash to continue one command across lines in a single shell:
+
+```makefile
+also_working:
+	cd /tmp && \
+		pwd
+```
+
+### .ONESHELL
+
+`.ONESHELL:` (GNU Make 3.82+) runs an entire recipe in one shell, so multi‑line recipes share state naturally:
+
+```makefile
+.ONESHELL:
+my_target:
+	cd /tmp
+	pwd          # now this prints /tmp
+```
+
+Note that `.ONESHELL` is **global** — it affects every recipe in the Makefile, so don't mix it with demos that rely on separate‑shell behaviour.
+
+### Line prefixes
+
+| Prefix | Effect |
+|--------|--------|
+| `@` | Suppress echoing of the command (Make normally prints each command before running it) |
+| `-` | Ignore a non‑zero exit status from the command |
+| `+` | Run the command even under `make -n` (dry run) |
+
+They combine, e.g. `-@cmd` silences output *and* ignores errors:
+
+```makefile
+errors:
+	@echo "--- ignoring a failing command ---"
+	-false
+	@echo "Make continued past 'false' because of the - prefix"
+```
+
+### Escaping `$`
+
+Make expands `$(VAR)` and `${VAR}` **before** the shell sees the line. To pass a literal `$` to the shell (for shell variables, `awk`, etc.) escape it as `$$`:
+
+```makefile
+demo:
+	@echo "Make variable: $(MY_VAR)"
+	@SHELL_VAR="hello"; echo "Shell variable: $$SHELL_VAR"
+```
+
+### Canned recipes (`define` / `endef`)
+
+A **canned recipe** is a reusable command sequence stored in a variable. Define it once, expand it with `$(name)` wherever it's needed. Automatic variables like `$@` inside it resolve to the *calling* rule's target:
+
+```makefile
+define log_start
+	@echo "=== Starting: $@ ==="
+	@date
+endef
+
+define log_end
+	@date
+	@echo "=== Finished: $@ ==="
+endef
+
+target_a:
+	$(log_start)
+	@echo "Building target_a"
+	$(log_end)
+
+target_b:
+	$(log_start)
+	@echo "Building target_b"
+	$(log_end)
+```
+
+See the manual on [recipes](https://www.gnu.org/software/make/manual/html_node/Recipes.html) and [canned recipes](https://www.gnu.org/software/make/manual/html_node/Canned-Recipes.html).
+
+---
+
+## Variables
+
+### Assignment operators
+
+| Operator | Name | When the right‑hand side is expanded |
+|----------|------|--------------------------------------|
+| `=` | recursive (lazy) | Every time the variable is **used** (late binding) |
+| `:=` (and POSIX `::=`) | simple (immediate) | Once, **at the point of definition** (early binding) |
+| `?=` | conditional | Like `=`, but the assignment happens **only if the variable is not already set** |
+| `+=` | append | Appends to the current value (or sets it, if previously unset) |
+| `:::=` | immediate‑with‑escape (4.4+) | Expanded immediately, then results re‑escaped; rarely needed |
+
+> **Common confusion:** `:=` is the *immediate* operator (value fixed when defined); `?=` is the *set‑only‑if‑undefined* operator. They are not interchangeable.
+
+```makefile
+A  = $(B)      # recursive: A re-expands $(B) every time A is used
+B := hello     # simple: evaluated once, here
+C ?= default   # conditional: only assigned if C has no value yet
+D += more      # append to D
+```
+
+### Late vs early binding
+
+The difference between `=` and `:=` is *when* references inside the value are resolved:
+
+```makefile
+BAR  := initial
+SIMP := $(BAR)   # := captures "initial" right now
+REC   = $(BAR)   # = just stores the reference $(BAR)
+BAR  := changed  # reassign BAR
+
+# When expanded later:
+#   SIMP -> "initial"   (snapshot taken at definition)
+#   REC  -> "changed"   (resolved at use, sees the new BAR)
+```
+
+This matters most with `$(shell ...)`: a recursive variable re‑runs the command on every expansion, a simple one runs it once:
+
+```makefile
+NOW_EQ      = $(shell date +%s)   # re-runs `date` every time NOW_EQ is used
+NOW_SIMPLE := $(shell date +%s)   # runs `date` once, at parse time
+```
+
+### Override precedence
+
+When the same variable is set in more than one place, the priority is:
+
+```
+command line  >  Makefile  >  environment  >  built-in default
+```
+
+This is the *default* ordering. `make -e` (`--environment-overrides`) flips the middle two, making environment variables win over Makefile assignments.
+
+`?=` is convenient for *overridable defaults*, because it backs off if any higher‑priority source already set the value:
+
+```makefile
+CC ?= gcc        # `make CC=clang` wins; otherwise CC is gcc
+```
+
+To make a Makefile assignment win even over the command line, use `override`:
+
+```makefile
+override USER := Mr. President   # `make USER=...` cannot change this
+```
+
+### Variable scope
+
+A variable is global by default, but can be scoped to a target or a pattern:
+
+```makefile
+VAR = global scope
+
+# Target-specific: VAR has this value only while building scoping_local
+# (and its prerequisites).
+scoping_local: VAR = local scope
+scoping_local:
+	@echo "In $@, VAR is $(VAR)"
+
+# Pattern-specific: applies to any target matching the pattern p%
+p%: VAR = set with wildcard
+```
+
+### Environment variables
+
+Make imports the environment as variables. A variable that isn't set expands to the empty string:
+
+```makefile
+echo_env:
+	@echo "Hello $(USER), your home is $(HOME)"
+	@echo "This env var does not exist: [$(DOESNOTEXIST)]"
+	@echo "Exported var PACIFIC=[$(PACIFIC)]"   # run `export PACIFIC=ocean` first
+```
+
+---
+
+## Automatic variables
+
+Inside a recipe, Make sets these to describe the rule being built. They are the key to writing generic rules:
+
+| Variable | Meaning |
+|----------|---------|
+| `$@` | The target name |
+| `$<` | The first prerequisite |
+| `$^` | All prerequisites, duplicates removed |
+| `$+` | All prerequisites, duplicates kept, in order |
+| `$?` | Prerequisites that are newer than the target |
+| `$*` | The stem matched by `%` in a pattern rule |
+| `$(@D)` / `$(@F)` | The directory / file parts of `$@` |
+
+```makefile
+target: one two three four five
+	@echo "$$@  target name:                 $@"
+	@echo "$$<  first prereq:                 $<"
+	@echo "$$^  all prereqs:                  $^"
+	@echo "$$?  prereqs newer than target:    $?"
+	@echo "second prereq via word:           $(word 2,$^)"
+	@echo "all but the first prereq:         $(filter-out $<,$^)"
+```
+
+Note that `$(filter-out $<,$^)` removes *every* prerequisite equal to `$<` (a value match, not a positional one); because `$^` de‑duplicates, that happens to mean "all but the first" here. `$(@D)` is handy when a tool needs the *directory* containing a file rather than the file itself.
+
+---
+
+## Functions
+
+Make has built‑in functions for text processing; they expand to strings before recipes run.
+
+### Text and list functions
+
+Assuming `BAMS := $(wildcard *.bam)`:
+
+| Function | Purpose | Example |
+|----------|---------|---------|
+| `$(wildcard pat)` | Files matching a glob | `$(wildcard *.bam)` |
+| `$(patsubst pat,repl,text)` | Pattern substitution over words | `$(patsubst %,%.bai,$(BAMS))` |
+| `$(subst from,to,text)` | Plain (non‑pattern) string substitution | `$(subst -,_,$(BAMS))` |
+| `$(addprefix p,names)` | Prepend a prefix to each word | `$(addprefix raw-,$(BAMS))` |
+| `$(addsuffix s,names)` | Append a suffix to each word | `$(addsuffix .bai,$(BAMS))` |
+| `$(filter pat,text)` | Keep words matching the pattern(s) | `$(filter sample1%,$(BAMS))` |
+| `$(filter-out pat,text)` | Drop words matching the pattern(s) | `$(filter-out sample1%,$(BAMS))` |
+| `$(sort list)` | Sort words and remove duplicates | `$(sort $(BAMS))` |
+| `$(notdir names)` | Strip the directory part | `$(notdir path/to/x.bam)` → `x.bam` |
+| `$(dir names)` | Keep only the directory part | `$(dir path/to/x.bam)` → `path/to/` |
+| `$(basename names)` | Strip the suffix | `$(basename x.bam)` → `x` |
+| `$(suffix names)` | Keep only the suffix | `$(suffix x.bam)` → `.bam` |
+
+A common idiom — derive one file list from another:
+
+```makefile
+fastas := $(wildcard data/*.fa)
+# data/1.fa data/2.fa ... -> result/1.bam result/2.bam ...
+bams   := $(patsubst %,result/%.bam,$(basename $(notdir $(fastas))))
+```
+
+You can also use a **substitution reference**, a shorthand for the common `patsubst` case `$(VAR:pattern=replacement)`:
+
+```makefile
+BOOST_LIBRARIES := system filesystem regex
+# -> -lboost_system -lboost_filesystem -lboost_regex
+LDFLAGS += $(BOOST_LIBRARIES:%=-lboost_%)
+```
+
+### foreach
+
+`$(foreach var,list,text)` expands `text` once per word in `list`:
+
+```makefile
+# Wrap each BAM in brackets: [a.bam] [b.bam] ...
+BAMS_BRACKETS := $(foreach f,$(BAMS),[$(f)])
+```
+
+Combined with **computed variable names** (`$($(x)_SUFFIX)`), `foreach` can drive a small data model:
+
+```makefile
+BATCHES   = batch1 batch2
+batch1_ID = ID1
+batch2_ID = ID2
+batch1_DIR = dir_batch1
+batch2_DIR = dir_batch2
+
+# Expands to: dir_batch1 dir_batch2
+all: $(foreach batch,$(BATCHES),$($(batch)_DIR))
+
+$(BATCHES):
+	@echo "Processing $@ using ID $($@_ID) into $($@_DIR)"
+	mkdir -p $($@_DIR)
+```
+
+(For generating whole *rules* dynamically rather than just lists, reach for `$(eval ...)`.)
+
+### shell
+
+`$(shell cmd)` runs a command and captures its output: embedded newlines become spaces, and the trailing newline is stripped:
+
+```makefile
+DATE := $(shell date +%F)
+```
+
+Remember the timing rule from [Variables](#variables): with `:=` the command runs once at parse time; with `=` it re‑runs on every expansion.
+
+### Diagnostics: info, warning, error
+
+These print during parsing (not in a recipe). `$(error ...)` aborts the build:
+
+```makefile
+$(info  CFLAGS is $(CFLAGS))      # informational message
+$(warning Debugging enabled)      # warning, build continues
+$(error Cannot continue)          # print the message and abort parsing
+```
+
+See [Conditionals](#conditionals) for the common `ifndef`/`$(error)` pattern used to guard against unset variables.
+
+### User‑defined functions
+
+Define a function as a variable; call it with `$(call name,arg1,arg2,...)`, where `$1`, `$2`, … are the arguments:
+
+```makefile
+make_date = $1-$2-$3
+today    := $(call make_date,2022,09,15)   # -> 2022-09-15
+
+# Abort the build if a required command is missing.
+assert-command-present = $(if $(shell command -v $1),,$(error '$1' is missing))
+$(call assert-command-present,samtools)
+```
+
+---
+
+## Conditionals
+
+`ifeq` / `ifneq` compare two expanded values. `ifdef` / `ifndef` test whether a variable is **defined to a non‑empty value, without expanding it first** — so `ifdef foo` is true for `foo = $(bar)` even when `$(bar)` itself expands to empty. To test the *expanded* value for emptiness, use `ifeq ($(VAR),)` (shown below). Conditionals are evaluated when the Makefile is **parsed**, not when a recipe runs.
+
+```makefile
+my_target:
+ifeq ($(COND),1)
+	echo Condition 1
+else ifeq ($(COND),2)
+	echo Condition 2
+else
+	echo Condition else
+endif
+```
+
+A frequent pattern is the **emptiness test** — note the empty first argument:
+
+```makefile
+# True when BOOST_ROOT is set to something non-empty.
+ifneq (,$(BOOST_ROOT))
+  BOOST_INCLUDEDIR ?= $(BOOST_ROOT)/include
+endif
+```
+
+And a guard that aborts early if a required variable is unset:
+
+```makefile
+ifndef PACIFIC
+$(error Variable PACIFIC is not set)
+endif
+```
+
+### Requiring a minimum Make version
+
+Several features in these notes need a recent Make (`.ONESHELL` 3.82+, grouped `&:` targets 4.3+, `:::=` 4.4+). Guard for them at parse time using the built‑in `$(MAKE_VERSION)`:
+
+```makefile
+need := 4.3
+ok   := $(filter $(need),$(firstword $(sort $(MAKE_VERSION) $(need))))
+ifeq (,$(ok))
+$(error GNU Make $(need)+ required, but this is $(MAKE_VERSION))
+endif
+```
+
+`$(sort ...)` orders the running version against the one you need, `$(firstword ...)` takes the lower of the two, and `$(filter ...)` is non‑empty only when the running version is at least `need`.
+
+---
+
+## Prerequisites and rebuild semantics
+
+Make decides whether to rebuild a target by comparing modification times (mtimes): if any **normal** prerequisite is newer than the target — or the target is missing — the recipe runs.
+
+### Order‑only prerequisites
+
+Sometimes a target needs another to *exist* but should not rebuild just because that other thing changed — the classic case is an output directory. List such prerequisites after a pipe `|`; their timestamps are ignored:
+
+```makefile
+# build/output.txt depends on input.txt (normal) and the build/ dir (order-only).
+# A newer build/ timestamp will NOT trigger a rebuild of output.txt.
+build/output.txt: input.txt | build
+	cp $< $@
+
+build:
+	mkdir -p $@
+```
+
+> Beware **symlink** targets: Make checks the mtime of the file the link *resolves to*, not the link itself — which has surprising consequences. See [Gotchas](#gotchas).
+
+---
+
+## Special targets and directives
+
+### .PHONY
+
+By default a target is a *file* target. A **phony** target is one that doesn't correspond to a file — `all`, `clean`, `install`, `test`, and friends. Declaring it phony does two things: it stops Make being confused by a real file of the same name (e.g. a file literally called `clean`), and it makes the target *always* run:
+
+```makefile
+.PHONY: clean
+clean:
+	rm -rf *.o
+```
+
+A phony target is, in effect, always out of date, so `make clean` runs regardless of the filesystem. You can also use a phony name as a short alias for a long real target (see [Worked examples](#worked-examples)).
+
+### .DELETE_ON_ERROR
+
+If a recipe exits non‑zero partway through, the half‑written target file is left behind and looks up to date. `.DELETE_ON_ERROR:` tells Make to delete a target whose recipe fails:
+
+```makefile
+.DELETE_ON_ERROR:
+
+output1.txt:
+	touch $@
+
+# Write a partial result, then fail.
+output2.txt: output1.txt
+	touch $@ && false
+```
+
+When the recipe exits non‑zero, the half‑written `output2.txt` is removed instead of being left behind looking up to date:
+
+```console
+$ make
+touch output1.txt
+touch output2.txt && false
+make: *** [Makefile:8: output2.txt] Error 1
+make: *** Deleting file 'output2.txt'
+```
+
+Make *also* deletes a target if you interrupt a running recipe with Ctrl‑C, but that cleanup happens regardless of `.DELETE_ON_ERROR` — this special target is specifically about non‑zero *exit status*.
+
+Related special targets worth knowing: `.SECONDARY` and `.PRECIOUS` (keep intermediate files), `.INTERMEDIATE`, and `.NOTPARALLEL` (force serial builds).
+
+### SHELL
+
+Set the shell used for recipes (recipes default to `/bin/sh`). Use this when you rely on bash features:
+
+```makefile
+SHELL := /bin/bash
+```
+
+### include
+
+`include` suspends reading the current Makefile to read another first — useful for pulling configuration out into its own file:
+
+```makefile
+include config.mk
+```
+
+This is also how you pin tool versions: keep them in a small included file (e.g. `tool_versions` with `samtools_version=1.17`) and reference `$(samtools_version)` in your rules. The [dragmap example](examples/dragmap/) uses `include config.mk` to assemble compiler flags conditionally.
+
+---
+
+## Running make
+
+`make` accepts many flags; the full list is in `man make` or `make --help`. The most useful:
+
+| Flag | Long form | What it does | When it's useful |
+| --- | --- | --- | --- |
+| `-j [N]` | `--jobs[=N]` | Run up to `N` recipes in parallel (no `N` = as many as possible). | Anything CPU/IO‑bound with independent targets — the single biggest speed‑up. Prerequisites must be declared correctly or parallel builds race. |
+| `-O[type]` | `--output-sync[=type]` | Group each recipe's output so parallel jobs don't interleave. `type` ∈ `none`, `line`, `target` (default), `recurse`. | Whenever you use `-j`. Without it, parallel logs are unreadable. |
+| `-k` | `--keep-going` | Keep building unrelated targets after a failure instead of stopping. | Long batch runs where you want to see *all* failures in one pass. |
+| `-n` | `--dry-run` | Print the commands Make *would* run without executing them. | Sanity‑checking a Makefile, or generating a command list (e.g. for `make2graph`). |
+| `-B` | `--always-make` | Treat every target as out of date and rebuild unconditionally. | Forcing a clean rebuild, or when you changed something Make can't detect. |
+| `-d` | `--debug` | Verbose info on which rules fire, which prerequisites are considered, and why targets are (or aren't) rebuilt. | Figuring out *why* Make is rebuilding something — or refusing to. Pair with `-n`. |
+| `-C dir` | `--directory=dir` | `cd` into `dir` before reading the Makefile. | Running a sub‑project's Makefile from elsewhere. |
+| `-f file` | `--file=file` | Use `file` instead of the default (`Makefile`/`makefile`/`GNUmakefile`). | Keeping multiple Makefiles in one directory. |
+| `-s` | `--silent` | Suppress command echoing (as if every line were prefixed with `@`). | Cleaner output when you only care about program messages. |
+| `-i` | `--ignore-errors` | Ignore non‑zero exit codes from recipes. | Rarely a good idea; occasionally useful for cleanup targets. |
+| `-p` | `--print-data-base` | Print Make's internal database (variables, rules, implicit rules) after parsing. | Discovering implicit rules and variables in scope; pair with `-n`. |
+
+A useful combination for real workloads:
+
+```bash
+make -j4 -O -k all 2>&1 | tee results/run.log
+```
+
+This runs up to four recipes in parallel, keeps the interleaved output readable, doesn't stop on the first failure, and captures stdout+stderr to a log.
+
+Notes on `-j` and `-O`:
+
+- `-O target` (the default) prints each recipe's output as one block when it finishes — the most readable mode.
+- `-O line` synchronises at line granularity, so you see progress in real time without garbled lines.
+- `-O none` is the legacy interleaved behaviour — almost never what you want with `-j`.
+- `-k` with `-j` skips failed targets and their dependents but keeps other branches going; Make still exits non‑zero so CI catches the failure.
+- `-n` suppresses *recipe* execution only — parse‑time `$(shell ...)` functions still run.
+
+### Passing variables on the command line
+
+Variables given on the command line override the Makefile (unless `override` is used). This is the standard way to toggle behaviour: `make CC=clang`, `make DEBUG=1`, `make VERBOSE=1`.
+
+### A verbosity toggle
+
+A tidy idiom for switchable command echoing — quiet by default, full commands when asked:
+
+```makefile
+VERBOSE ?= 0
+ifeq ($(VERBOSE),0)
+  Q := @
+else
+  Q :=
+endif
+
+all:
+	$(Q)printf "Hello, World!\n"
+```
+
+`make` is quiet; `make VERBOSE=1` echoes the command. The same `?=`/conditional pattern drives a debug toggle — e.g. `DEBUG ?= 0` and, when set, `CFLAGS += -g` plus a `$(warning Debugging enabled)`.
+
+---
+
+## Gotchas
+
+**A target that never creates its file forces endless rebuilds.** Here `main.o` has no effective recipe (the condition is false, so the body is empty) and no file is ever produced, so Make treats it as perpetually out of date — and `hello`, which depends on it, relinks *every* run. In a large Makefile this is silent and maddening:
+
+```makefile
+hello: main.o
+	touch $@
+
+main.o:
+ifeq (false,true)
+	echo $@      # never runs -> main.o is never created -> hello always rebuilds
+endif
+```
+
+**Symlink targets are judged by the linked file's mtime.** When a target is a symlink, Make uses the mtime of the file it *resolves to*, not the link itself. So recreating or touching the link without changing the underlying file won't trigger dependents, and a prerequisite that is newer than the underlying file keeps the step re‑running until that file is regenerated.
+
+**`$` needs escaping in recipes.** Make consumes a single `$` for its own expansion. Use `$$` for a literal `$` (shell variables, `awk` programs, etc.). See [Recipes](#recipes).
+
+**Don't depend on a list of unknown targets.** It's tempting to generate files whose names you don't know ahead of time and have Make skip them once they exist. This is fragile: once `$(FILES)` exists, Make won't rebuild those files even when their inputs change, and you can't tell whether you got the 5 files you expected or only 2. Prefer knowing your targets up front.
+
+**Parallel builds expose under‑declared prerequisites.** Under `-j`, two recipes that secretly share a file (without declaring it) can race. If a parallel build is flaky but a serial one isn't, look for a missing prerequisite.
+
+---
+
+## Visualising the dependency graph
+
+[`make2graph`](https://github.com/lindenb/makefile2graph) turns Make's dry‑run output into a Graphviz diagram — a quick way to see how targets connect.
+
+```console
+# Build make2graph (one-off)
+git clone https://github.com/lindenb/makefile2graph.git
+cd makefile2graph && make
+
+# Install graphviz for `dot`
+sudo apt update && sudo apt install -y graphviz
+
+# Render the graph: -B force all targets, -n dry-run, -d debug output
+make -Bnd | ./make2graph | dot -Tpng -o out.png
+```
+
+A runnable demo and a sample `out.png` are in [`examples/visual/`](examples/visual/). To explore Make's *internal* knowledge (implicit rules, variables) instead of just your own targets, use `make -p`.
+
+> `-n` only suppresses *recipe* execution — parse‑time `$(shell ...)` calls still run, so `make -Bnd` is not always fully side‑effect‑free when generating the graph.
+
+---
+
+## Worked examples
+
+Short patterns are inlined here; the longer, runnable ones live under [`examples/`](examples/).
+
+### Aliasing long targets
+
+Give long real filenames short, memorable phony aliases. The trick: targets and prerequisites depend on the *real* files (via variables); the aliases just point at them.
+
+```makefile
+.PHONY: all first
+one := file_one_one_one_one_one.txt
+
+all: $(one)
+
+first: $(one)     # `make first` is the convenient alias...
+$(one):           # ...but the real work hangs off the file target
+	touch $@
+```
+
+### Versioned symlink backups
+
+Keep one stable symlink that always points at the latest version, while retaining a timestamped backup of every version:
+
+```makefile
+my_symlink: dep.txt
+	DS=$$(date +%Y%m%d_%H%M%S) && \
+		cat $< > $$DS && \
+		ln -fs $$DS $@
+```
+
+Editing `dep.txt` makes the prerequisite newer than the target, so the rule re‑runs — producing a new timestamped file and repointing the link. (The symlink‑mtime caveat in [Gotchas](#gotchas) applies if you instead try to trigger rebuilds via the link itself.)
+
+### Data‑driven targets
+
+Build a target list partly from a file, mixing static and discovered names:
+
+```makefile
+FILES      := 1.txt 2.txt 3.txt
+MORE_FILES := $(shell cut -f1 -d, files_to_create.csv)
+
+all: $(FILES) $(MORE_FILES) final.txt
+
+%.txt:
+	touch $@
+
+final.txt: $(FILES) $(MORE_FILES)
+	touch $@
+```
+
+(See the unknown‑targets caveat in [Gotchas](#gotchas) before relying on this.)
+
+### Debugging a build's environment — [`examples/dragmap/`](examples/dragmap/)
+
+A real case study: building [DRAGMAP](https://github.com/Illumina/DRAGMAP) against an alternate Boost install. It uses `include`, `$(info ...)` to dump variables, and `ifneq` emptiness tests to assemble `CPPFLAGS`/`LDFLAGS` from `BOOST_ROOT` / `BOOST_INCLUDEDIR` / `BOOST_LIBRARYDIR`. The `run.sh`/`test*.sh` scripts toggle the environment variables to show which combination fixes the link errors.
+
+### Orchestrating SGE cluster jobs — [`examples/sge/`](examples/sge/)
+
+Using Make as a dependency‑aware front end for a job scheduler: each target submits a job with `qsub` and chains them with `-hold_jid` so a job waits for its predecessor, while independent targets run in parallel. `submit.sh` runs Make itself as a parallel job (`make -j $NSLOTS`). SGE is largely legacy now; the same pattern applies to Slurm (`sbatch --dependency=afterok:<id>`).