---
title: "mbake Tool Reference"
description: "Comprehensive guide to using mbake (Makefile formatter and linter) for Makefile validation and formatting."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/bake-tool
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:08:12.346Z
license: CC-BY-4.0
attribution: "mbake Tool Reference — Claudary (https://claudary.paisolsolutions.com/skills/bake-tool)"
---

# mbake Tool Reference
Comprehensive guide to using mbake (Makefile formatter and linter) for Makefile validation and formatting.

## Overview

# mbake Tool Reference

Comprehensive guide to using mbake (Makefile formatter and linter) for Makefile validation and formatting.

## Overview

**mbake** is a modern Python-based tool designed to format and validate Makefiles with intelligent features. It's the first comprehensive Makefile formatter and linter, filling a 50-year gap in build tooling.

**Current Version**: See [PyPI](https://pypi.org/project/mbake/) for latest

### Known Limitations

While mbake is excellent for GNU Make formatting, be aware of these limitations:

- **POSIX Make**: mbake is designed for GNU Make; it may not recognize all POSIX make syntax
- **.SUFFIXES**: mbake doesn't understand `.SUFFIXES` special target
- **Format vs Check**: Some users report `mbake format --check` warns about different things than `mbake format` fixes

For additional linting coverage, consider using [checkmake](https://github.com/checkmake/checkmake) alongside mbake.

## Table of Contents

1. [Installation](#installation)
2. [Quick Start](#quick-start)
3. [Commands](#commands)
4. [Configuration](#configuration)
5. [Features](#features)
6. [CI/CD Integration](#cicd-integration)
7. [Editor Integration](#editor-integration)
8. [Advanced Usage](#advanced-usage)
9. [Troubleshooting](#troubleshooting)

## Installation

### PyPI Installation (Recommended)

```bash
# Install mbake
pip install mbake

# Upgrade to latest version
pip install --upgrade mbake

# Verify installation
mbake --version
```

### System Requirements

- **Python**: 3.9 or higher
- **GNU Make**: Required for validation (syntax checking)
- **pip**: For package management

### Virtual Environment (Isolated Installation)

```bash
# Create venv
python3 -m venv mbake-env

# Activate venv
source mbake-env/bin/activate  # Linux/macOS
# or
mbake-env\\Scripts\\activate  # Windows

# Install mbake
pip install mbake

# Use mbake
mbake format Makefile

# Deactivate when done
deactivate
```

**Note**: The makefile-validator skill automatically handles venv creation and cleanup.

### VS Code Extension

Install the "mbake Makefile Formatter" extension from the VS Code marketplace:

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "mbake Makefile Formatter"
4. Click Install

## Quick Start

### Basic Workflow

```bash
# 1. Check current formatting status
mbake format --check Makefile

# 2. Preview changes before applying
mbake format --diff Makefile

# 3. Apply formatting
mbake format Makefile

# 4. Validate syntax
mbake validate Makefile
```

### First-Time Usage

```bash
# Initialize configuration file
mbake init

# This creates ~/.bake.toml with default settings
# Edit the file to customize mbake behavior

# View current configuration
mbake config

# Format with current settings
mbake format Makefile
```

## Commands

### `mbake format`

Format and standardize Makefile structure.

```bash
# Basic formatting
mbake format Makefile

# Check formatting without modifying (CI/CD)
mbake format --check Makefile
# Exit code: 0 (properly formatted), 1 (needs formatting)

# Show diff of changes
mbake format --diff Makefile

# Backup before formatting
mbake format --backup Makefile
# Creates Makefile.bak

# Validate after formatting
mbake format --validate Makefile

# Specify custom config file
mbake format --config /path/to/.bake.toml Makefile

# Format multiple files
mbake format Makefile tests/*.mk build/*.mk
```

**Options:**
- `--check`: Check formatting without modifying (exit 0 if formatted, 1 if not)
- `--diff`: Display potential changes without applying
- `--backup`: Create .bak backup before modifying
- `--validate`: Run syntax validation after formatting
- `--config PATH`: Use custom configuration file

### `mbake validate`

Validate Makefile syntax using GNU Make.

```bash
# Validate syntax
mbake validate Makefile

# Validates with: make -f Makefile --dry-run
# Exit code: 0 (valid), 1 (invalid)

# Validate multiple files
mbake validate Makefile src/*.mk
```

**What it checks:**
- Syntax errors (missing colons, invalid characters)
- Target definition correctness
- Variable expansion syntax
- Recipe format
- Dependency chain validity

### `mbake init`

Create initial configuration file.

```bash
# Create ~/.bake.toml with defaults
mbake init

# The configuration file includes all formatting options
# Edit it to customize mbake behavior
```

### `mbake config`

Display current configuration settings.

```bash
# Show active configuration
mbake config

# Output includes:
# - Configuration file location
# - All active settings
# - Default values for unset options
```

### `mbake update`

Update mbake to the latest version.

```bash
# Update via pip
mbake update

# Equivalent to: pip install --upgrade mbake
```

## Configuration

### Configuration File: `~/.bake.toml`

Create and edit `~/.bake.toml` to customize mbake behavior:

```toml
# ~/.bake.toml - mbake configuration

# Add spaces around = in variable assignments
# Example: VAR = value  (instead of VAR=value)
space_around_assignment = true

# Add space after : in target definitions
# Example: target : prerequisites  (instead of target: prerequisites)
space_after_colon = true

# Normalize line continuation characters (backslashes)
# Removes trailing spaces before \\ and ensures proper continuation
normalize_line_continuations = true

# Remove trailing whitespace from all lines
remove_trailing_whitespace = true

# Fix missing tabs in recipes (convert spaces to tabs)
# This is critical - Makefiles MUST use tabs for recipes
fix_missing_recipe_tabs = true

# Automatically detect and insert .PHONY declarations
# Analyzes recipes to identify phony targets (clean, test, etc.)
auto_insert_phony_declarations = true

# Group multiple .PHONY declarations into single declaration
# .PHONY: clean test  (instead of two separate lines)
group_phony_declarations = true

# Place .PHONY declarations at the top of the file
# If false, keeps them near their target definitions
phony_at_top = false
```

### Per-Project Configuration

Create `.bake.toml` in your project root:

```toml
# Project-specific mbake settings
# These override ~/.bake.toml for this project

space_around_assignment = false  # Compact style for this project
auto_insert_phony_declarations = true
phony_at_top = true
```

**Priority:**
1. `.bake.toml` in current directory (highest)
2. `~/.bake.toml` in home directory
3. Built-in defaults (lowest)

### Configuration Options Reference

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `space_around_assignment` | bool | `true` | Add spaces around `=` |
| `space_after_colon` | bool | `true` | Add space after `:` |
| `normalize_line_continuations` | bool | `true` | Clean backslash continuations |
| `remove_trailing_whitespace` | bool | `true` | Remove end-of-line spaces |
| `fix_missing_recipe_tabs` | bool | `true` | Convert spaces to tabs in recipes |
| `auto_insert_phony_declarations` | bool | `true` | Auto-detect and add .PHONY |
| `group_phony_declarations` | bool | `true` | Combine .PHONY lines |
| `phony_at_top` | bool | `false` | Place .PHONY at file start |

## Features

### 1. Tab Indentation Enforcement

Automatically converts spaces to tabs in recipe sections.

```makefile
# Before (spaces - invalid!)
build:
    echo "Building..."
    go build -o app

# After (tabs - correct!)
build:
	echo "Building..."
	go build -o app
```

### 2. Variable Assignment Formatting

Consistent spacing around assignments.

```makefile
# Before (inconsistent)
VAR1=value
VAR2 =value
VAR3= value
VAR4  =  value

# After (consistent)
VAR1 = value
VAR2 = value
VAR3 = value
VAR4 = value
```

### 3. Target Colon Spacing

Standardizes spacing after target colons.

```makefile
# Before
target1:prerequisites
target2 :prerequisites
target3: prerequisites

# After
target1: prerequisites
target2: prerequisites
target3: prerequisites
```

### 4. Intelligent .PHONY Detection

Automatically identifies phony targets by analyzing recipes.

```makefile
# Before
clean:
	rm -rf build

test:
	go test ./...

install:
	cp app /usr/local/bin/

# After
.PHONY: clean test install

clean:
	rm -rf build

test:
	go test ./...

install:
	cp app /usr/local/bin/
```

**Detection Logic:**
- Targets with `rm`, `mkdir`, `echo` commands → Phony
- Targets with `npm`, `go test`, `docker` commands → Phony
- Targets with `curl`, `ssh`, `scp` commands → Phony
- Targets producing actual files (*.o, *.a, binaries) → Not phony

### 5. Line Continuation Normalization

Cleans up line continuation characters.

```makefile
# Before (trailing space after \\, inconsistent)
SOURCES = main.c \\
          utils.c\\
          config.c \\

# After (consistent, no trailing spaces)
SOURCES = main.c \\
          utils.c \\
          config.c
```

### 6. Trailing Whitespace Removal

Removes all trailing spaces and tabs.

```makefile
# Before (invisible trailing spaces marked with ·)
VAR = value···
build:···
	echo "test"··

# After (clean)
VAR = value
build:
	echo "test"
```

### 7. Syntax Validation

Validates Makefile syntax before and after formatting.

```bash
mbake format --validate Makefile
```

**Validation Process:**
1. Validates original file with `make --dry-run`
2. Applies formatting changes
3. Validates formatted file
4. Only saves if both validations pass

### 8. Format Disable Comments

Selectively disable formatting for specific sections.

```makefile
# Standard formatting applies here
VAR1=value
target1:prerequisites

# bake-format off
# Preserve legacy formatting in this section
VAR2   =    value
target2   :   prerequisites
	    echo   "custom spacing"
# bake-format on

# Standard formatting resumes
VAR3=value
target3:prerequisites
```

**Use cases:**
- Legacy Makefiles with specific formatting
- Auto-generated sections
- Intentional custom spacing
- Compatibility with other tools

## CI/CD Integration

### GitHub Actions

```yaml
name: Validate Makefiles

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install mbake
        run: pip install mbake

      - name: Check Makefile formatting
        run: mbake format --check Makefile

      - name: Validate Makefile syntax
        run: mbake validate Makefile

      - name: Check all .mk files
        run: |
          for file in $(find . -name "*.mk" -o -name "Makefile"); do
            echo "Checking $file..."
            mbake format --check "$file"
            mbake validate "$file"
          done
```

### GitLab CI

```yaml
# .gitlab-ci.yml
validate-makefiles:
  image: python:3.11
  stage: test

  before_script:
    - pip install mbake

  script:
    - find . -name "Makefile" -o -name "*.mk" | while read file; do
        echo "Validating $file";
        mbake format --check "$file";
        mbake validate "$file";
      done

  only:
    - merge_requests
    - main
```

### Pre-commit Hook

Install as a pre-commit hook:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: mbake-format
        name: mbake format
        entry: mbake format --check
        language: system
        files: (Makefile|.*\\.mk)$

      - id: mbake-validate
        name: mbake validate
        entry: mbake validate
        language: system
        files: (Makefile|.*\\.mk)$
```

Install and use:

```bash
# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files
```

### Make Target for Self-Validation

Add to your Makefile:

```makefile
# Self-validation targets
.PHONY: format-check format-fix validate-makefile

format-check:
	@echo "Checking Makefile formatting..."
	@mbake format --check $(MAKEFILE_LIST)

format-fix:
	@echo "Applying formatting to Makefile..."
	@mbake format $(MAKEFILE_LIST)

validate-makefile:
	@echo "Validating Makefile syntax..."
	@mbake validate $(MAKEFILE_LIST)

# Run all checks
.PHONY: check
check: format-check validate-makefile
	@echo "All checks passed!"
```

Usage:

```bash
# Check formatting and syntax
make check

# Auto-fix formatting
make format-fix

# Validate only
make validate-makefile
```

## Editor Integration

### VS Code

#### Extension

Install "mbake Makefile Formatter" from marketplace.

**Features:**
- Format on save
- Format on demand (Shift+Alt+F)
- Real-time validation
- Error highlighting

#### Manual Setup

Add to `.vscode/settings.json`:

```json
{
  "[makefile]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "mbake.mbake-formatter",
    "editor.insertSpaces": false,
    "editor.detectIndentation": false,
    "editor.tabSize": 8
  },
  "mbake.validateOnSave": true,
  "mbake.autoFixOnSave": false
}
```

#### Tasks

Add to `.vscode/tasks.json`:

```json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "mbake: Format Makefile",
      "type": "shell",
      "command": "mbake",
      "args": ["format", "${file}"],
      "problemMatcher": []
    },
    {
      "label": "mbake: Validate Makefile",
      "type": "shell",
      "command": "mbake",
      "args": ["validate", "${file}"],
      "problemMatcher": []
    },
    {
      "label": "mbake: Check Format",
      "type": "shell",
      "command": "mbake",
      "args": ["format", "--check", "${file}"],
      "problemMatcher": []
    }
  ]
}
```

### Vim/Neovim

Add to `.vimrc` or `init.vim`:

```vim
" Format Makefile with mbake
autocmd FileType make nnoremap <buffer> <leader>f :!mbake format %<CR>:e<CR>

" Validate Makefile
autocmd FileType make nnoremap <buffer> <leader>v :!mbake validate %<CR>

" Check format
autocmd FileType make nnoremap <buffer> <leader>c :!mbake format --check %<CR>

" Ensure tabs in Makefiles
autocmd FileType make setlocal noexpandtab tabstop=8 shiftwidth=8
```

### Emacs

Add to `.emacs` or `init.el`:

```elisp
;; mbake formatting for Makefiles
(defun mbake-format-buffer ()
  "Format current Makefile with mbake."
  (interactive)
  (shell-command (format "mbake format %s" (buffer-file-name)))
  (revert-buffer t t t))

(defun mbake-validate-buffer ()
  "Validate current Makefile with mbake."
  (interactive)
  (compile (format "mbake validate %s" (buffer-file-name))))

;; Key bindings
(add-hook 'makefile-mode-hook
  (lambda ()
    (local-set-key (kbd "C-c f") 'mbake-format-buffer)
    (local-set-key (kbd "C-c v") 'mbake-validate-buffer)))
```

## Advanced Usage

### Batch Processing

```bash
# Format all Makefiles in project
find . -name "Makefile" -o -name "*.mk" | xargs mbake format

# Check all files without modifying
find . -name "Makefile" -o -name "*.mk" | xargs mbake format --check

# Create backups of all files
find . -name "Makefile" -o -name "*.mk" | while read file; do
    mbake format --backup "$file"
done
```

### Selective Formatting

```bash
# Format only specific files
mbake format Makefile build.mk test.mk

# Format with pattern
mbake format **/*.mk

# Exclude certain files
find . -na

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/bake-tool) · https://claudary.paisolsolutions.com