Makefileの書き方｜自動変数一覧とタスクランナー用テンプレート

Makefileとは、「何を作るか（ターゲット）」「何に依存するか」「どう作るか（レシピ）」を書いておき、make コマンドで必要な処理だけを実行させるための設定ファイルです。 もともとはC言語のビルド用ですが、現在は make test や make up のように、プロジェクトのコマンドをまとめる「タスクランナー」 としても広く使われています。

この記事では、基本構文から自動変数・変数代入・関数・条件分岐までを実際に make を実行した出力つきで解説し、help を自動生成する Docker Compose / Python(uv) / Node.js 用テンプレートを載せます。

検証環境： GNU Make 4.3（make --version の出力は GNU Make 4.3 / Built for x86_64-pc-linux-gnu）、gcc、uv 0.8.17、Node.js 22。GNU Make の最新版は 4.4.1（2023年2月）です。

Makefileの書き方の早見表

基本の書き方：ターゲット・依存・レシピ

ターゲット: 依存ファイル1 依存ファイル2
    レシピ（実行するコマンド）※行頭はタブ

make は 「ターゲットが存在しない」か「依存ファイルの方が新しい」ときだけレシピを実行します。

C言語のビルドで動きを確認する

次の構成で試します。

src/main.c  src/util.c  src/util.h  Makefile

CC      := gcc
CFLAGS  := -Wall -O2
SRCS    := $(wildcard src/*.c)
OBJS    := $(patsubst src/%.c,build/%.o,$(SRCS))
TARGET  := build/app

.PHONY: all clean

all: $(TARGET)

$(TARGET): $(OBJS)
    $(CC) $(CFLAGS) -o $@ $^

build/%.o: src/%.c src/util.h
    @mkdir -p $(@D)
    $(CC) $(CFLAGS) -c -o $@ $<

clean:
    rm -rf build

実行結果：

$ make
gcc -Wall -O2 -c -o build/main.o src/main.c
gcc -Wall -O2 -c -o build/util.o src/util.c
gcc -Wall -O2 -o build/app build/main.o build/util.o

$ make
make: Nothing to be done for 'all'.

$ touch src/util.c && make
gcc -Wall -O2 -c -o build/util.o src/util.c
gcc -Wall -O2 -o build/app build/main.o build/util.o

$ ./build/app
total=5

2回目は何も実行されず、util.c を更新すると util.o とリンクだけがやり直されました。 これが依存関係を書く意味です。

タブではなくスペースで書くと「missing separator」

レシピの行頭をスペース4つにしたMakefileを実行すると、次のエラーになりました。

$ make -f Makefile.space
Makefile.space:2: *** missing separator.  Stop.

レシピの行頭は必ずタブ文字です。.editorconfig に [Makefile] と indent_style = tab を書いておくと防げます。cat -A Makefile ではタブが ^I と表示されます。

自動変数の一覧（$@ $< $^ $? $*）

自動変数は、ルールごとにmakeが自動で値を入れてくれる変数です。依存に a.txt を重複して書いた例で確認しました。

out/result.txt: a.txt b.txt a.txt
    @echo '$$@    = $@'
    @echo '$$<    = $<'
    @echo '$$^    = $^'
    @echo '$$+    = $+'
    @echo '$$?    = $?'
    @echo '$$(@D) = $(@D)'
    @echo '$$(@F) = $(@F)'
    @touch $@

out/%.log: %.txt
    @echo '$$*    = $*'

$ make
$@    = out/result.txt
$<    = a.txt
$^    = a.txt b.txt
$+    = a.txt b.txt a.txt
$?    = a.txt b.txt
$(@D) = out
$(@F) = result.txt

$ touch b.txt && make | grep '\$?'
$?    = b.txt

$ make out/a.log
$*    = a

レシピの中でシェルの $ を使いたいときは $$ と2つ重ねます（上の '$$@' はそのためです）。

変数の代入：= と := と ?= と += の違い

NAME = before
LAZY  = $(NAME)
NOW  := $(NAME)
NAME = after

ENV ?= dev
FLAGS := -Wall
FLAGS += -O2

TIME_LAZY  = $(shell date +%N)
TIME_NOW  := $(shell date +%N)

show:
    @echo 'LAZY  = $(LAZY)'
    @echo 'NOW   = $(NOW)'
    @echo 'ENV   = $(ENV)'
    @echo 'FLAGS = $(FLAGS)'
    @echo 'TIME_LAZY: $(TIME_LAZY) / $(TIME_LAZY)'
    @echo 'TIME_NOW : $(TIME_NOW) / $(TIME_NOW)'

$ make
LAZY  = after
NOW   = before
ENV   = dev
FLAGS = -Wall -O2
TIME_LAZY: 193890592 / 196437124
TIME_NOW : 190171156 / 190171156

$ ENV=prod make | grep ENV
ENV   = prod
$ make ENV=stg | grep ENV
ENV   = stg

迷ったら := を使うと、値がいつ決まるかが明確になり、$(shell ...) の実行回数も1回で済みます。

なお A = x の次に A = $(A) y と書くと、*** Recursive variable 'A' references itself (eventually). Stop. で止まりました。追記は A += y か A := $(A) y と書きます。

.PHONY：ファイルを作らないターゲット

clean という名前のファイルがある状態で、.PHONY なしの clean を実行した結果です。

$ touch clean && make clean
make: 'clean' is up to date.

clean を「既にあるファイル」とみなして何もしません。 .PHONY: clean を追加するとレシピが実行されました。test build docs などフォルダ名と重なりやすいターゲットは必ず .PHONY に書きます。

パターンルール %.o: %.c

最初のC言語の例の build/%.o: src/%.c src/util.h がパターンルールです。% は任意の文字列に一致し、左右で同じ文字列が使われます（build/main.o → src/main.c）。ヘッダー更新後に何が実行されるかを make -n（dry-run）で確認しました。

$ touch src/util.h && make -n
mkdir -p build
gcc -Wall -O2 -c -o build/main.o src/main.c
mkdir -p build
gcc -Wall -O2 -c -o build/util.o src/util.c
gcc -Wall -O2 -o build/app build/main.o build/util.o

-n は @ で隠したコマンドも表示し、実際には何も実行しません。

よく使う関数（wildcard・patsubst・shell・foreach ほか）

SRCS  := $(wildcard src/*.c)
OBJS  := $(patsubst src/%.c,build/%.o,$(SRCS))
NAMES := $(notdir $(basename $(SRCS)))
GIT   := $(shell git --version)
DIRS  := api web worker
EACH  := $(foreach d,$(DIRS),svc-$(d))

.PHONY: show
show:
    @echo 'SRCS   = $(SRCS)'
    @echo 'OBJS   = $(OBJS)'
    @echo 'NAMES  = $(NAMES)'
    @echo 'FILTER = $(filter %b.c,$(SRCS))'
    @echo 'GIT    = $(GIT)'
    @echo 'EACH   = $(EACH)'

src/a.c、src/b.c、src/sub/c.c がある状態での出力：

SRCS   = src/a.c src/b.c
OBJS   = build/a.o build/b.o
NAMES  = a b
FILTER = src/b.c
GIT    = git version 2.43.0
EACH   = svc-api svc-web svc-worker

条件分岐 ifeq・ifdef と include

OS := $(shell uname -s)

ifeq ($(OS),Linux)
  OPEN := xdg-open
else ifeq ($(OS),Darwin)
  OPEN := open
else
  OPEN := start
endif

ifdef DEBUG
  CFLAGS := -g -O0
else
  CFLAGS := -O2
endif

Linuxでの実行結果は OPEN = xdg-open、CFLAGS = -O2、make DEBUG=1 では CFLAGS = -g -O0 になりました。ifeq などの行はタブで始めない（タブで始めるとレシピとして扱われる）のがポイントです。

include で設定を分けると、個人ごとの上書きファイルも作れます。

# config.mk の中身は「APP_PORT ?= 8000」と「export DB_NAME := app」
include config.mk
-include local.mk

.PHONY: p
p:
    @echo port=$(APP_PORT) db=$$DB_NAME

$ make
port=8000 db=app
$ echo 'APP_PORT := 9000' > local.mk && make
port=9000 db=app

-include はファイルがなくても続行します。 - なしだと No rule to make target 'nothing.mk'. Stop. で止まりました。export した変数はシェルの環境変数になります（$$DB_NAME）。

並列実行 -j と .ONESHELL・デフォルトゴール

-j で並列実行

1秒かかる独立したターゲット3つを実行した時間です。

依存関係が正しければ -j だけで速くなります。 ログが混ざるなら --output-sync=target でターゲットごとにまとめます。-j でだけ失敗する場合は依存の書き漏れを見直します。

レシピは1行ずつ別のシェルで実行される（.ONESHELL）

normal:
    cd /tmp
    pwd
    X=1
    echo "X=$$X"

make normal の結果、pwd は /tmp ではなくMakefileのあるディレクトリを表示し、最後は X= と空になりました。各行は別のシェルなので、cd も変数も引き継がれません。 ファイル先頭に .ONESHELL: を書くと /tmp と X=1 が出力されました。使わない場合は cd /tmp && pwd と1行につなげます。

デフォルトゴールとエラー時の動き

タスクランナー用テンプレート（help自動生成つき）

ターゲットの行末に ## 説明 を書き、grep と awk で一覧を表示するのが定番の書き方です。

Python(uv)プロジェクト用

# ==== Python (uv) プロジェクト用 Makefile ====
SHELL := /bin/bash
.SHELLFLAGS := -eu -o pipefail -c
.DEFAULT_GOAL := help
MAKEFLAGS += --no-builtin-rules

.PHONY: help setup lint format test check clean

help: ## コマンド一覧を表示
    @grep -E '^[a-zA-Z0-9_-]+:.*?## ' $(MAKEFILE_LIST) \
      | awk 'BEGIN {FS = ":.*?## "}; {printf "  \033[36m%-10s\033[0m %s\n", $$1, $$2}'

setup: ## 依存関係をインストール（uv sync）
    uv sync
    uv add --dev ruff pytest

lint: ## ruff で静的チェック
    uv run ruff check .

format: ## ruff で整形
    uv run ruff format .

test: ## pytest を実行
    uv run pytest -q

check: lint test ## lint と test をまとめて実行

clean: ## キャッシュを削除
    rm -rf .pytest_cache .ruff_cache
    find . -name __pycache__ -type d -prune -exec rm -rf {} +

uv init --lib taskapp での実行結果（色コードは省略）：

$ make
  help       コマンド一覧を表示
  setup      依存関係をインストール（uv sync）
  lint       ruff で静的チェック
  format     ruff で整形
  test       pytest を実行
  check      lint と test をまとめて実行
  clean      キャッシュを削除

$ make check
uv run ruff check .
I001 [*] Import block is un-sorted or un-formatted
（中略）
make: *** [Makefile:18: lint] Error 1

check: lint test は lint が失敗した時点で止まり、test は実行されません。 uv run ruff check --fix . で直した後は次のとおり通りました（ruff 0.16.9 / pytest 9.1.1）。

$ make check
uv run ruff check .
All checks passed!
uv run pytest -q
.                                                                        [100%]
1 passed in 0.01s

.SHELLFLAGS := -eu -o pipefail -c はパイプ途中の失敗や未定義変数でも止める設定です。

Node.js プロジェクト用（npm install を必要なときだけ）

# ==== Node.js 用 Makefile ====
STAMP := node_modules/.installed
.DEFAULT_GOAL := help
.PHONY: help install test build

help: ## コマンド一覧
    @grep -E '^[a-zA-Z0-9_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-10s %s\n", $$1, $$2}'

# package.json か package-lock.json が変わったときだけ npm install
$(STAMP): package.json package-lock.json
    npm install
    @mkdir -p $(@D) && touch $@

install: $(STAMP) ## 依存関係をインストール

test: $(STAMP) ## テスト
    npm test --silent

build: $(STAMP) ## ビルド
    npm run build --silent

目印ファイル（スタンプ）を依存にしたことで、make build の1回目は npm install → ビルド、2回目は npm run build --silent だけが実行されました。 更新日時で判断するmakeならではの使い方です。

Docker Compose 用

# ==== Docker Compose 用 Makefile ====
COMPOSE ?= docker compose
SERVICE ?= app
.DEFAULT_GOAL := help
.PHONY: help up down restart logs sh

help: ## コマンド一覧
    @grep -E '^[a-zA-Z0-9_-]+:.*?## ' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-10s %s\n", $$1, $$2}'

up: ## バックグラウンドで起動
    $(COMPOSE) up -d

down: ## 停止してコンテナを削除
    $(COMPOSE) down

restart: down up ## 再起動

logs: ## ログを追いかける（SERVICE=名前 で絞り込み）
    $(COMPOSE) logs -f $(SERVICE)

sh: ## コンテナに入る
    $(COMPOSE) exec $(SERVICE) sh

make -n で展開結果を確認しました（docker compose 自体は未実行）。

$ make -n restart
docker compose down
docker compose up -d
$ make -n logs SERVICE=db
docker compose logs -f db

SERVICE ?= app にしておくと、make logs SERVICE=db のように引数で切り替えられます。

GNU make と BSD make の違い

この記事の構文はGNU make向けです。FreeBSD等の標準 make はBSD makeで、条件分岐は .if / .endif、変数は ${.TARGET} ${.ALLSRC}、関数の代わりに修飾子 ${VAR:M*.c} を使うため、gmake として GNU make を入れて使います（BSD make は未実行、マニュアルに基づく）。macOS標準は GNU Make 3.81 なので、.ONESHELL（3.82以降）を使うなら Homebrew の gmake を使います。

just・npm scripts・Taskfile との比較

よくある質問

Q. make: *** No rule to make target 'xxx' と出ます。 A. 依存に書いたファイルが存在せず、それを作るルールもないときのエラーです。ファイル名のつづり、パス、include したファイルの有無を確認します。

Q. Makefile と makefile のどちらがよいですか？ A. GNU make の公式マニュアルは Makefile を推奨しています（探す順は GNUmakefile → makefile → Makefile）。

Q. レシピでシェル変数が空になります。 A. 各行が別のシェルで動くためです。&& でつなぐか .ONESHELL: を使い、$$X と書きます。

まとめ

• Makefileは「ターゲット: 依存」＋タブで始まるレシピ。スペースだと missing separator
• 自動変数 $@ $< $^ $? $* $(@D) でファイル名を繰り返し書かずに済む
• 変数は基本 :=、上書き可能にしたい値は ?=、追記は +=
• ファイルを作らないターゲットは .PHONY に書く
• make -n で確認、make -j で並列化、.ONESHELL でレシピを1つのシェルに
• ## コメント と grep/awk の help で、タスクランナーとしてチームに共有しやすくなる

株式会社RJCでは、チームの誰もが同じコマンドで開発を始められるように、環境の整え方をプロジェクトの中で仲間と学び合っています。こうした知識を共有しながら、日々技術を磨いています。

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。