akin-ozer/cc-devops-skills/makefile-generator

Makefile Generator

Overview

Generate production-ready Makefiles with best practices for C/C++, Python, Go, Java, and generic projects. Features GNU Coding Standards compliance, standard targets, security hardening, and automatic validation via devops-skills:makefile-validator skill.

When to Use

• Creating new Makefiles from scratch
• Setting up build systems for projects (C/C++, Python, Go, Java)
• Implementing build automation and CI/CD integration
• Converting manual build processes to Makefiles
• The user asks to "create", "generate", or "write" a Makefile

Do NOT use for: Validating existing Makefiles (use devops-skills:makefile-validator), debugging (use make -d), or running builds.

Trigger Phrases

Use this skill when prompts look like:

• "Generate a Makefile for a Go service"
• "Create a production Makefile with install/test/help targets"
• "Write a Makefile for a C project with dependency tracking"
• "Add standard GNU targets to this existing Makefile"

Generation Workflow

Stage 1: Gather Requirements

Collect information for the following categories. Use AskUserQuestion when information is missing or ambiguous:

When to Use AskUserQuestion (MUST ask if any apply):

When to Skip AskUserQuestion (proceed with defaults):

• User explicitly provides all required information
• Standard project type with obvious defaults (e.g., "Go project with Docker" → use standard Go+Docker patterns)
• User says "use defaults" or "standard setup"

Default Assumptions (when not asking):

• Single-directory project structure
• PREFIX=/usr/local
• Standard targets: all, build, test, clean, install, help
• No cross-compilation

Stage 2: Documentation Lookup

When REQUIRED (MUST perform lookup):

• User requests integration with unfamiliar tools, frameworks, or build systems
• Complex build patterns not covered in Stage 3 examples (e.g., Bazel, Meson, custom toolchains)
• Docker/container integration (Dockerfile builds, multi-stage, registry push)
• CI/CD platform-specific integration (GitHub Actions, GitLab CI, Jenkins)
• Cross-compilation for unusual targets or embedded systems
• Package manager integration (Conan, vcpkg, Homebrew formulas)
• Multi-binary or multi-library projects
• Version embedding via ldflags or build-time variables

When OPTIONAL (may skip external lookup):

• Standard language patterns already covered in Stage 3 (C/C++, Go, Python, Java)
• Simple single-binary projects with no external dependencies
• User provides complete requirements with no ambiguity
• Internal docs already cover the required pattern comprehensively

Lookup Process (follow in order):

1. ALWAYS consult internal docs first using explicit file-open commands (primary source of truth):

Full doc path map (prefer full paths for deterministic access):

Deterministic open/read commands: ```bash # From repository root: sed -n '1,220p' devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md rg -n "Pattern 5|Pattern 8" devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md

# From skill directory: sed -n '1,220p' docs/security-guide.md ```

If shell commands are unavailable, use the environment's file-open/read capability on the same paths.

Required Workflow Example (Docker + Go with version embedding): ```bash # Step 1: Read Go pattern rg -n "Pattern 5" devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md

# Step 2: Read Docker pattern rg -n "Pattern 8" devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md

# Step 3: Read security guidance sed -n '1,220p' devops-skills-plugin/skills/makefile-generator/docs/security-guide.md ``` Then generate Makefile and list consulted docs in a header comment.

1. Try context7 for external tool documentation (when internal docs don't cover a specific tool):

``` # Only needed for tools/frameworks NOT covered in internal docs mcp__context7__resolve-library-id: "<tool-name>" mcp__context7__query-docs: query="<integration-topic>"

# Example queries: # - For Docker: query="dockerfile best practices" # - For Go: query="go build ldflags" # - For specific tools: query="<tool> makefile integration" ``` Fallback: If context7 is unavailable or returns nothing useful, record that and continue to Step 3.

1. Fallback to WebSearch (only if pattern not found in internal docs OR context7):

`` "<specific-feature>" makefile best practices 2025 Example: "docker makefile best practices 2025" Example: "go ldflags version makefile 2025" `` Trigger WebSearch when: Internal docs don't cover the specific integration AND context7 returns no relevant results.

Note: Document which internal docs you consulted in your response (add comment in generated Makefile header).

Stage 3: Generate Makefile

Optional helper-script fast path (for standard layouts):

# Generate template: TYPE NAME OUTPUT
bash scripts/generate_makefile_template.sh go myservice Makefile
 
# Add only selected standard targets
bash scripts/add_standard_targets.sh Makefile install clean help

Use manual authoring when requirements are complex (Docker release flow, multi-binary matrices, custom toolchains).

Header (choose one style)

Traditional (POSIX-compatible):

.DELETE_ON_ERROR:
.SUFFIXES:

Modern (GNU Make 4.0+, recommended):

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

Standard Variables

# User-overridable (use ?=)
CC ?= gcc
CFLAGS ?= -Wall -Wextra -O2
PREFIX ?= /usr/local
DESTDIR ?=
 
# GNU installation directories
BINDIR ?= $(PREFIX)/bin
LIBDIR ?= $(PREFIX)/lib
INCLUDEDIR ?= $(PREFIX)/include
 
# Project-specific (use :=)
PROJECT := myproject
VERSION := 1.0.0
SRCDIR := src
BUILDDIR := build
SOURCES := $(wildcard $(SRCDIR)/*.c)
OBJECTS := $(SOURCES:$(SRCDIR)/%.c=$(BUILDDIR)/%.o)

Language-Specific Build Rules

C/C++:

$(TARGET): $(OBJECTS)
	$(CC) $(LDFLAGS) $^ $(LDLIBS) -o $@
 
$(BUILDDIR)/%.o: $(SRCDIR)/%.c
	@mkdir -p $(@D)
	$(CC) $(CPPFLAGS) $(CFLAGS) -MMD -MP -c $< -o $@
 
-include $(OBJECTS:.o=.d)

Go:

$(TARGET): $(shell find . -name '*.go') go.mod
	go build -o $@ ./cmd/$(PROJECT)

Python:

.PHONY: build
build:
	python -m build
 
.PHONY: develop
develop:
	pip install -e .[dev]

Java:

$(BUILDDIR)/%.class: $(SRCDIR)/%.java
	@mkdir -p $(@D)
	javac -d $(BUILDDIR) -sourcepath $(SRCDIR) $<

Standard Targets

.PHONY: all clean install uninstall test help
 
## Build all targets
all: $(TARGET)
 
## Install to PREFIX
install: all
	install -d $(DESTDIR)$(BINDIR)
	install -m 755 $(TARGET) $(DESTDIR)$(BINDIR)/
 
## Remove built files
clean:
	$(RM) -r $(BUILDDIR) $(TARGET)
 
## Run tests
test:
	# Add test commands
 
## Show help
help:
	@echo "$(PROJECT) v$(VERSION)"
	@echo "Targets: all, install, clean, test, help"
	@echo "Override: make CC=clang PREFIX=/opt"

Stage 4: Validate and Format

Validation is required for every generated Makefile.

Validation Tool Preflight (default + fallback)

1. Preferred path: run devops-skills:makefile-validator.
2. If validator skill is unavailable: run local fallback checks:

```bash # Required fallback check (if make exists) make -f <Makefile> -n --dry-run

# Structural fallback checks rg -n '^ {1,}\S' <Makefile> # suspicious space-indented recipe lines rg -n '^\.PHONY:' <Makefile> ```

1. If `make` is unavailable: run structural checks only, report "partial validation due to missing make binary", and request user confirmation before claiming production readiness.

Required Validation Loop

1. Generate Makefile following stages above
2. Run validator skill (or fallback checks if unavailable)
3. Fix all errors (MUST have 0 errors before completion)
4. Apply formatting fixes (see "Formatting Step" below)
5. Fix warnings when feasible (SHOULD fix; explain if skipped)
6. Address info items for large/production projects
7. Re-run validation until checks pass
8. Output structured validation report (REQUIRED - see format below)

Formatting Step (REQUIRED)

When mbake reports formatting issues, you MUST either:

1. Auto-apply formatting (preferred for minor issues):

``bash mbake format <Makefile> ``

1. Explain why not applied (if formatting would break functionality):

``` Formatting not applied because:

• [specific reason, e.g., "heredoc syntax would be corrupted"]
• Manual review recommended for: [specific lines]

```

If mbake is not installed or not executable, skip formatter execution and record: Formatting skipped: mbake unavailable in current environment.

Formatting Decision Guide:

Validation Pass Criteria: