Makefile para Desenvolvedores — Automatize Tarefas Sem Espaguetis em Bash

Você sabe como é. Um projeto começa limpo. Depois alguém adiciona um run.sh. Depois build.sh. Depois um deploy.sh que referencia um .env e chama os dois primeiros em uma ordem específica, e de repente há seis arquivos de shell que ninguém quer tocar e um README que diz “veja a pasta de scripts.”

Faça correções nisso. Um Makefile no diretório raiz do projeto, make test, feito.

Isso não é sobre sistemas de compilação em C. O Make antecedeu o Linux e foi originalmente projetado para compilação baseada em dependências — mas seu mecanismo central (alvos nomeados que executam comandos em shell) o torna um gerenciador de tarefas totalmente adequado para qualquer stack. Node, Python, Go, Rust, Docker, ou o que você estiver construindo.

Como o Make realmente funciona

Um Makefile é uma lista de alvos. Cada alvo tem um nome, dependências opcionais e um bloco de comando em shell:

.PHONY: build test lint clean

build:
	npm run build

test:
	npm test

Duas coisas que confundem todos na primeira vez que os veem:

• A indentação deve ser um caractere de tab real, não espaços. Todo editor que converte automaticamente tabs silenciosamente quebrará seu Makefile até que você configure o contrário. Isso já era verdade em 1977 e o Make nunca perdoará se você usar espaços.
• Por padrão, o Make acredita que os nomes de alvo são nomes de arquivos. Se um arquivo chamado build existir no diretório raiz do seu projeto, make build não fará nada porque o Make acredita que o alvo já foi “construído”. A solução é .PHONY.

Declarar todos os alvos que não são nomes de arquivos reais como .PHONY. Na prática, Makefiles de gerenciadores de tarefas declaram todos os alvos porque nenhum deles produz arquivos. Seu .PHONY ficará assim como a primeira linha do modelo abaixo.

Variáveis e sobrescritas da linha de comando

O Make tem sua própria sintaxe de variáveis — parece shell, mas age de forma diferente:

DOCKER_IMAGE = myapp
TAG = latest

build:
	docker build -t $(DOCKER_IMAGE):$(TAG) .

Sobrescreva na linha de comando: make build TAG=v1.2.3. Sem necessidade de edição de arquivos para builds versados ou deploys específicos de ambiente. Variáveis de ambiente do shell também estão disponíveis automaticamente — $(HOME), $(PATH), o que estiver em seu ambiente quando você rodar make.

Um modelo de Makefile pronto para uso

Copie isso, exclua o que não se aplica, ajuste os comandos para sua stack:

.PHONY: install build test lint clean run docker-up docker-down help

# --- Config -------------------------------------------------------------------
DOCKER_COMPOSE = docker compose
APP_NAME = myapp

# --- Default target -----------------------------------------------------------
help:
	@echo "Available targets:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'

# --- Dev ----------------------------------------------------------------------
install: ## Install dependencies
	npm ci

run: ## Start the dev server
	npm run dev

build: ## Build for production
	npm run build

# --- Quality ------------------------------------------------------------------
lint: ## Run the linter
	npm run lint

test: ## Run the test suite
	npm test

test-watch: ## Run tests in watch mode
	npm run test:watch

# --- Docker -------------------------------------------------------------------
docker-up: ## Start services via docker compose
	$(DOCKER_COMPOSE) up -d

docker-down: ## Stop and remove containers
	$(DOCKER_COMPOSE) down

docker-logs: ## Tail container logs
	$(DOCKER_COMPOSE) logs -f

# --- Cleanup ------------------------------------------------------------------
clean: ## Remove build artifacts and caches
	rm -rf dist node_modules/.cache .next

O help alvo usa um padrão grep + awk para extrair comentários inline e transformá-los em documentação formatada. Execute ## e você obterá uma lista ordenada de todos os alvos com suas descrições — sem necessidade de manter documentos separados. Este é o trecho mais roubado na história de Makefiles, e por uma boa razão. make help e você recebe uma lista ordenada de todos os destinos com suas descrições — sem documentos separados para manter. Este é o trecho mais roubado na história dos Makefile, por uma boa razão.

Cadeia de alvos para CI

O Make trata dependências nativamente. Liste alvos como dependências para executá-los em ordem:

ci: lint test build ## Full CI check (lint -> test -> build)

make ci executa lint, depois testes, depois build. Se qualquer etapa sair com código não-zero, o Make para. Isso é o comportamento correto de CI — falhe com força, não oculte silenciosamente o passo quebrado.

Supressão de echo e comandos multilinhas

Por padrão, o Make imprime cada comando antes de executá-lo. Prefixe com @ para suprimir:

setup:
	@echo "Setting up project..."
	@cp .env.example .env
	@npm ci
	@echo "Done."

Para comandos que ocupam múltiplas linhas, conecte com && — ele para em caso de falha, diferente de pontos e vírgulas que continuam mesmo que haja falha:

migrate:
	npm run db:migrate && \
	npm run db:seed && \
	echo "Migration complete"

Quando o Make é a ferramenta errada

O Make vem com o macOS (via ferramentas de linha de comando do Xcode) e com todas as distribuições Linux. Sem etapa de instalação, sem conflitos de versão, zero atrito para a maioria das equipes de desenvolvimento.

Onde ele se mostra fraco:

• Windows — o WSL funciona bem, mas o Windows nativo não tem make sem Chocolatey, Scoop ou a versão GnuWin32. Se sua equipe for nativa do Windows, simplesmente é uma alternativa próxima, projetada especificamente para preencher essa lacuna.
• Lógica complexa — o Make não é uma linguagem de programação. Condições e laços existem, mas são verdadeiramente feios. Se sua lógica de build precisar de verdadeiro ramificação, escreva um script adequado.
• Comandos de shell cross-platform — rm -rf, cpe outros recursos Unix não existem no Windows nativo. Tarefa (baseada em Go) trata isso com suporte nativo a comandos cross-platform.

Para a maioria das equipes de backend e fullstack em Mac ou Linux, o Make é a escolha pragmática. É monótono da melhor forma — nada para instalar, nada para atualizar, nada que quebre em atualizações de dependência.

Manter seu Makefile limpo

Quando um Makefile cresce com múltiplos contribuidores e fusões, a indentação e o espaçamento se deslocam. Como o Make é sensível a espaços em branco, um espaço extra em vez de um tab quebra silenciosamente um alvo sem mensagem de erro útil. IO Tools’ formatação de Makefile normaliza a indentação e limpa o espaço em branco sem tocar na lógica — útil como verificação de saúde pré-commit.

Você também pode gostar