Make and just

target: prerequisite1 prerequisite2
	recipe line          # begins with a literal TAB, not spaces
	another line         # each line runs in its own shell

.PHONY: all build test clean
all: build test

build: bin/my-app                       # phony alias for a real file target

bin/my-app: $(wildcard *.go) go.sum      # rebuilt only when a source or go.sum changed
	go build -o $@ .

clean:
	rm -rf bin/                          # deletes build output

VERSION  ?= $(shell git describe --tags --always --dirty)   # ?= only if not already set (env or command line)
GOFLAGS  := -trimpath                  # := expands now, once
LDFLAGS   = -X main.version=$(VERSION) # = expands every time it is used (recursive)
CGO_ENABLED ::= 0                      # POSIX spelling of :=
BIN      := bin/my-app
CFLAGS   += -Wall                      # append
override CFLAGS += -O2                 # append even when CFLAGS came from the command line
export GOFLAGS                         # pass to recipe shells

test: GOFLAGS += -race                 # target-specific: applies to test and everything it triggers
test:
	go test $(GOFLAGS) ./...

print-%:                               # make print-VERSION shows the value
	@echo '$*=$($*)'

%.o: %.c %.h | build/                  # after | : order-only; created if missing, timestamp ignored
	$(CC) $(CFLAGS) -c $< -o $@

build/:
	mkdir -p $@

docs/%.html: docs/%.md
	pandoc $< -o $@

OBJS := $(patsubst %.c,%.o,$(wildcard src/*.c))
my-app: $(OBJS)
	$(CC) -o $@ $^

$(OBJS): %.o: %.c                      # only the files in OBJS, built from their .c
	$(CC) -c $< -o $@

MAKEFLAGS += --no-builtin-rules --no-builtin-variables
.SUFFIXES:

SRCS    := $(wildcard cmd/*/main.go)
CMDS    := $(patsubst cmd/%/main.go,bin/%,$(SRCS))        # cmd/api/main.go -> bin/api
NAMES   := $(notdir $(patsubst %/main.go,%,$(SRCS)))       # api worker
UPPER   := $(shell echo $(NAMES) | tr a-z A-Z)
HAS_GO  := $(if $(shell command -v go),yes,)
PLATS   := linux/amd64 linux/arm64
OSES    := $(foreach p,$(PLATS),$(firstword $(subst /, ,$(p))))
FILTERED := $(filter-out %_test.go,$(wildcard *.go))
SORTED  := $(sort $(NAMES))                                 # also deduplicates

ifeq ($(HAS_GO),)
  $(error go is not installed)
endif
ifneq ($(origin CI),undefined)                              # variable came from the environment
  GOFLAGS += -mod=readonly
endif

define build-cmd                                            # multi-line macro, used with call/eval
bin/$(1): cmd/$(1)/main.go
	go build -o $$@ ./cmd/$(1)
endef
$(foreach n,$(NAMES),$(eval $(call build-cmd,$(n))))

include config.mk                      # error if missing
-include local.mk                      # silently skipped if missing
include $(wildcard mk/*.mk)

config.mk: config.mk.in                # make remakes included files first, then restarts
	./configure

SUBDIRS := lib app
.PHONY: $(SUBDIRS)
app: lib                               # explicit ordering between subdirectory targets
$(SUBDIRS):
	$(MAKE) -C $@

.DEFAULT_GOAL := build                 # instead of "first rule wins"
.DELETE_ON_ERROR:                      # remove a target whose recipe failed; otherwise a half-written file looks up to date
.ONESHELL:                             # whole recipe in one shell; cd and variables persist between lines
.SHELLFLAGS := -eu -o pipefail -c      # with .ONESHELL, otherwise only the last line's status counts
SHELL := bash
.SILENT: clean                         # no echo for these targets; @ does it per line
.NOTPARALLEL:                          # serialise this whole Makefile (rarely right; fix the dependencies instead)
.SECONDARY:                            # keep intermediate files
.PRECIOUS: %.o                         # keep even when interrupted
.EXTRA_PREREQS := Makefile             # every target also depends on the Makefile (4.3+)

all: build .WAIT test                  # test does not start until build is done, even with -j

SHELL := bash
.SHELLFLAGS := -eu -o pipefail -c
.DEFAULT_GOAL := build
.DELETE_ON_ERROR:
MAKEFLAGS += --warn-undefined-variables --no-builtin-rules

MODULE   := $(shell go list -m)
NAME     := $(notdir $(MODULE))
VERSION  ?= $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
COMMIT   := $(shell git rev-parse --short HEAD 2>/dev/null || echo none)
DATE     := $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
LDFLAGS  := -s -w -X main.version=$(VERSION) -X main.commit=$(COMMIT) -X main.date=$(DATE)
GOFILES  := $(shell find . -name '*.go' -not -path './vendor/*')
BIN      := bin/$(NAME)
PLATFORMS := linux/amd64 linux/arm64 darwin/arm64
export CGO_ENABLED ?= 0

.PHONY: build
build: $(BIN)                                 ## Build for the host platform

$(BIN): $(GOFILES) go.mod go.sum | bin/
	go build -trimpath -ldflags '$(LDFLAGS)' -o $@ .

bin/ dist/:
	mkdir -p $@

.PHONY: release
release: $(foreach p,$(PLATFORMS),dist/$(NAME)-$(subst /,-,$(p)))   ## Cross-compile every platform

dist/$(NAME)-%: $(GOFILES) go.mod go.sum | dist/
	GOOS=$(word 1,$(subst -, ,$*)) GOARCH=$(word 2,$(subst -, ,$*)) \
	  go build -trimpath -ldflags '$(LDFLAGS)' -o $@ .

.PHONY: test lint vet fmt tidy cover
test:                                          ## Unit tests with the race detector
	go test -race -count=1 ./...
cover:                                         ## Coverage report in the browser
	go test -coverprofile=cover.out ./... && go tool cover -html=cover.out
vet:
	go vet ./...
lint: vet                                      ## golangci-lint (must be installed)
	golangci-lint run ./...
fmt:
	gofmt -l -w $(GOFILES)
tidy:
	go mod tidy
	git diff --exit-code go.mod go.sum       # fails in CI when tidy changed something

.PHONY: run
run: $(BIN)
	$(BIN) $(ARGS)

.PHONY: clean
clean:                                         ## Remove build output
	rm -rf bin/ dist/ cover.out

.PHONY: help
help:                                          ## Show this help
	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_-]+:.*##/ {printf "  %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

SHELL := bash
.SHELLFLAGS := -eu -o pipefail -c
.DEFAULT_GOAL := help
.DELETE_ON_ERROR:

ENGINE    ?= $(shell command -v podman || command -v docker)
REGISTRY  ?= registry.example.com/my-team
NAME      := my-app
VERSION   ?= $(shell git describe --tags --always --dirty)
IMAGE     := $(REGISTRY)/$(NAME)
PLATFORMS ?= linux/amd64,linux/arm64
CONTEXT   := .
SOURCES   := Containerfile $(shell git ls-files src/ 2>/dev/null)

.PHONY: build push run shell scan lint clean help

build: .build-$(VERSION)                       ## Build the image for the host platform
.build-$(VERSION): $(SOURCES)                  # stamp file: rebuild only when sources change
	$(ENGINE) build --pull -t $(IMAGE):$(VERSION) -t $(IMAGE):latest \
	  --label org.opencontainers.image.version=$(VERSION) \
	  --label org.opencontainers.image.revision=$(shell git rev-parse HEAD) \
	  -f Containerfile $(CONTEXT)
	rm -f .build-*
	touch $@

push: build                                    ## Push version and latest tags (writes to the registry)
	$(ENGINE) push $(IMAGE):$(VERSION)
	$(ENGINE) push $(IMAGE):latest

multiarch:                                     ## Multi-arch manifest with podman
	$(ENGINE) build --platform $(PLATFORMS) --manifest $(IMAGE):$(VERSION) -f Containerfile $(CONTEXT)
	$(ENGINE) manifest push --all $(IMAGE):$(VERSION)

run: build                                     ## Run locally on port 8080
	$(ENGINE) run --rm -it -p 8080:8080 -v ./config:/etc/my-app:Z,ro $(IMAGE):$(VERSION)

shell: build
	$(ENGINE) run --rm -it --entrypoint sh $(IMAGE):$(VERSION)

lint:                                          ## Lint the Containerfile
	hadolint Containerfile

scan: build                                    ## Vulnerability scan
	trivy image --exit-code 1 --severity HIGH,CRITICAL $(IMAGE):$(VERSION)

clean:                                         ## Remove local image and stamp files
	-$(ENGINE) rmi $(IMAGE):$(VERSION) $(IMAGE):latest
	rm -f .build-*

help:
	@awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_-]+:.*##/ {printf "  %-12s %s\n", $$1, $$2}' $(MAKEFILE_LIST)

just --list                                   # recipes with their doc comments, grouped
just --summary                                # names only, for completion scripts
just --show deploy                            # recipe source after expansion
just --evaluate                               # every variable's value
just --evaluate image
just --dry-run deploy production              # print the commands
just --set version 1.2.3 build                # override a variable
just version=1.2.3 build                      # same, shorter
just --justfile ../justfile --working-directory . test
just --fmt --unstable                         # rewrite the justfile in canonical format
just --fmt --check --unstable                 # CI: fail if not formatted
just --choose                                 # fzf picker
just --completions zsh > ~/.zfunc/_just

# Which make and version
make --version | head -1

# Why is this target rebuilding
make --debug=b bin/my-app 2>&1 | grep -E 'Must remake|newer than'

# Dry run showing the exact commands, including those hidden by @
make -n build

# Show every variable make knows and where it came from
make -p -n -f /dev/null 2>/dev/null | grep -E '^# (makefile|environment|command line)' -A1 | head -50

# Print a single variable without a print-% rule
make -f Makefile -f <(printf 'show:\n\t@echo $(VERSION)\n') show

# Targets in the Makefile that are not .PHONY and not files (candidates for .PHONY)
comm -23 <(make -pRrq : 2>/dev/null | awk -F: '/^[a-zA-Z0-9][^$#\/\t=]*:([^=]|$)/ {print $1}' | sort -u) <(ls | sort)

# Time each target in a parallel build
make -j8 -O --trace build 2>&1 | ts '%H:%M:%.S'

# Find lines indented with spaces where a tab is expected
grep -nP '^ +\S' Makefile

# Convert leading spaces to a tab in recipe lines (rewrites the file)
sed -i -E 's/^ {2,8}/\t/' Makefile

# Show the shell make will use and its flags
make -p -n -f /dev/null 2>/dev/null | grep -E '^(SHELL|\.SHELLFLAGS) '

# Run a target with a variable override and verbose shell
make build VERSION=1.2.3 SHELL='bash -x'

# Remake everything, ignoring timestamps
make -B -j"$(nproc)"

# Check a Makefile parses without running anything
make -n -f Makefile >/dev/null

# List recipes with descriptions, JSON, for scripting
just --dump --dump-format json | jq '.recipes | keys'

# Run a recipe from a subdirectory of the project
just --fallback test

# Does the justfile parse
just --list >/dev/null

# Check justfile formatting in CI
just --fmt --check --unstable

# Show the shell commands a recipe expands to
just --dry-run deploy production

# Run a recipe with an environment file other than .env
just --dotenv-filename .env.staging deploy

#!/usr/bin/env bash
set -euo pipefail
target=${1:-all}
make -s "$target" >/dev/null
second=$(make -n "$target" 2>&1 | grep -v -E '^make(\[[0-9]+\])?: (Nothing to be done|Entering|Leaving)' || true)
if [[ -n $second ]]; then
  printf 'these commands would run again after a clean build of %s:\n%s\n' "$target" "$second"
  exit 1
fi
printf '%s is stable: nothing to do on the second run\n' "$target"

#!/usr/bin/env bash
set -euo pipefail
{
  echo 'digraph make {'
  echo '  rankdir=LR; node [shape=box];'
  make -pRrq : 2>/dev/null |
    awk '/^# Not a target/ {skip=1; next}
         /^[a-zA-Z0-9_.\/-]+:( |$)/ && !skip { split($0, a, ":"); n=split(a[2], deps, " "); for (i=1; i<=n; i++) printf "  \"%s\" -> \"%s\";\n", a[1], deps[i] }
         {skip=0}'
  echo '}'
} > deps.dot
printf 'wrote deps.dot; render with: dot -Tsvg deps.dot -o deps.svg\n'

#!/usr/bin/env bash
set -euo pipefail
mapfile -t recipes < <(just --dump --dump-format json | jq -r '.recipes[] | select(.attributes[]? .group == "check") | .name')
[[ ${#recipes[@]} -gt 0 ]] || { echo 'no recipes in group "check"' >&2; exit 1; }
rc=0
for r in "${recipes[@]}"; do
  if just "$r" >"/tmp/just-$r.log" 2>&1; then printf 'ok    %s\n' "$r"
  else printf 'FAIL  %s (see /tmp/just-%s.log)\n' "$r" "$r"; rc=1; fi
done
exit "$rc"