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:** | Category | Information Needed | |----------|-------------------| | **Project** | Language (C/C++/Python/Go/Java), structure (single/multi-directory) | | **Build** | Source files, output artifacts, dependencies, build order | | **Install** | PREFIX location, directories (bin/lib/share), files to install | | **Targets** | all, install, clean, test, dist, help (which are needed?) | | **Config** | Compiler, flags, pkg-config dependencies, cross-compilation | **When to Use AskUserQuestion (MUST ask if any apply):** | Condition | Example Question | |-----------|------------------| | Language not specified | "What programming language is this project? (C/C++/Go/Python/Java)" | | Project structure unclear | "Is this a single-directory or multi-directory project?" | | Docker requested but registry unknown | "Which container registry should be used? (docker.io/ghcr.io/custom)" | | Multiple binaries possible | "Should this build a single binary or multiple executables?" | | Install targets needed but paths unclear | "Where should binaries be installed? (default: /usr/local/bin)" | | Cross-compilation mentioned | "What is the target platform/architecture?" | **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):** | Doc | Full Path | |-----|-----------| | Structure guide | `devops-skills-plugin/skills/makefile-generator/docs/makefile-structure.md` | | Variables guide | `devops-skills-plugin/skills/makefile-generator/docs/variables-guide.md` | | Targets guide | `devops-skills-plugin/skills/makefile-generator/docs/targets-guide.md` | | Patterns guide | `devops-skills-plugin/skills/makefile-generator/docs/patterns-guide.md` | | Optimization guide | `devops-skills-plugin/skills/makefile-generator/docs/optimization-guide.md` | | Security guide | `devops-skills-plugin/skills/makefile-generator/docs/security-guide.md` | | Requirement | Read This Doc | |-------------|---------------| | Docker/container targets | `.../docs/patterns-guide.md` (Pattern 8: Docker Integration) | | Multi-binary projects | `.../docs/patterns-guide.md` (Pattern 7: Multi-Binary Project) | | Go projects with version embedding | `.../docs/patterns-guide.md` (Pattern 5: Go Project) | | Parallel builds, caching, ccache | `.../docs/optimization-guide.md` | | Credentials, secrets, API keys | `.../docs/security-guide.md` | | Complex dependencies, pattern rules | `.../docs/patterns-guide.md` | | Order-only prerequisites | `.../docs/optimization-guide.md` or `.../docs/targets-guide.md` | | Variables, assignment operators | `.../docs/variables-guide.md` | **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. 2. **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. 3. **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):** ```bash # 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):** ```makefile .DELETE_ON_ERROR: .SUFFIXES: ``` **Modern (GNU Make 4.0+, recommended):** ```makefile SHELL := bash .ONESHELL: .SHELLFLAGS := -eu -o pipefail -c .DELETE_ON_ERROR: .SUFFIXES: MAKEFLAGS += --warn-undefined-variables MAKEFLAGS += --no-builtin-rules ``` #### Standard Variables ```makefile # 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++:** ```makefile $(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:** ```makefile $(TARGET): $(shell find . -name '*.go') go.mod go build -o $@ ./cmd/$(PROJECT) ``` **Python:** ```makefile .PHONY: build build: python -m build .PHONY: develop develop: pip install -e .[dev] ``` **Java:** ```makefile $(BUILDDIR)/%.class: $(SRCDIR)/%.java @mkdir -p $(@D) javac -d $(BUILDDIR) -sourcepath $(SRCDIR) $< ``` #### Standard Targets ```makefile .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> ``` 3. **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> ``` 2. **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:** | mbake Report | Action | |--------------|--------| | "Would reformat" with no specific issues | Auto-apply with `mbake format` | | Specific whitespace/indentation issues | Auto-apply with `mbake format` | | Issues in complex heredocs or multi-line strings | Skip formatting, explain in output | | Issues in `# bake-format off` sections | Skip (intentionally disabled) | | `mbake` command unavailable | Skip formatting, record tool-unavailable reason | **Validation Pass Criteria:** | Level | Requirement | Action |