Skip to content

Improve README.md documentation #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AntonioCS merged 1 commit into from
Jan 5, 2026
Merged

Improve README.md documentation #46

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -336,6 +336,18 @@ Rules:
- Bump minor version (e.g., 2.1.0 → 2.2.0) for new features/modules
- Bump patch version (e.g., 2.1.0 → 2.1.1) for bug fixes

### README Files
**IMPORTANT**: Keep README files up to date when making changes:

| File | Update When |
|------|-------------|
| `README.md` | Adding commands, changing installation, new user-facing features |
| `modules/README.md` | Changes to module structure, new module conventions |
| `core/README.md` | New core functions, changes to loading order, new utilities |
| `tests/README.md` | Changes to test framework, new assertions, test conventions |

When adding a new module, ensure the "Available Modules" table in `README.md` is updated.

### Trello Board
**Board ID: `vBmmD6it`** - Must be set at the start of each session using `mcp__trello__set_active_board`.

Expand Down
270 changes: 200 additions & 70 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,94 +2,89 @@

Streamline and manage your Makefile workflows with modular ease and project-specific customization.

*This README is a work in progress (WIP).*

## Table of Contents
- [Introduction](#introduction)
- [Support](#support)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Upgrading Make](#upgrading-Make)
- [On Linux (Debian)](#on-linux-debian)
- [On Mac](#on-mac)
- [Autocompletion on Mac](#autocompletion-on-mac)
- [Upgrading Make](#upgrading-make)
- [On Linux (Debian)](#on-linux-debian)
- [On Mac](#on-mac)
- [Common Commands](#common-commands)
- [Module System](#module-system)
- [What are Modules?](#what-are-modules)
- [Module Structure](#module-structure)
- [System vs Project Modules](#system-vs-project-modules)
- [Project Structure](#project-structure)
- [The bind-hub Folder](#the-bind-hub-folder)
- [Configuration Files](#configuration-files)
- [Debug Options](#debug-options)
- [Available Modules](#available-modules)

## Introduction
MakeBind is a Makefile project manager designed to simplify and customize your Makefile workflows. It allows you to manage projects and create modular Makefiles with ease.

MakeBind is a Makefile project manager designed to simplify and customize your Makefile workflows. It provides a plugin/module system for GNU Make, allowing you to compose reusable Makefile functionality and manage project-specific build configurations.

## Support
MakeBind is supported on the following operating systems:

MakeBind is supported on:
- Linux
- macOS
- Windows (not fully tested and still a work in progress)

If you encounter any issues on any of the platforms, please open an issue.
Windows users can use [WSL (Windows Subsystem for Linux)](https://learn.microsoft.com/en-us/windows/wsl/install).

If you encounter any issues, please [open an issue](https://github.com/AntonioCS/MakeBind/issues).

## Prerequisites

MakeBind requires the following tools to be installed on your system:
- `make` version 4.4 or higher

## Installation

To install MakeBind, run the appropriate command for your operating system in your terminal in the root folder of you project:
Run this command in your project's root folder:

### Linux and macOS:
```shell
curl -s -o ./Makefile https://raw.githubusercontent.com/AntonioCS/MakeBind/main/templates/Makefile.tpl.mk && make
```

### Windows:
```powershell
powershell -Command "Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/AntonioCS/MakeBind/main/templates/Makefile.tpl.mk' -OutFile './Makefile'; & make"
```
### What happens:
1. Downloads the Makefile template to your current directory
2. Runs `make`, which checks for MakeBind in the parent directory (`../MakeBind`)
3. If not found, downloads the latest release automatically
4. Creates a `bind-hub` folder with configuration files (`config.mk`, `project.mk`) and an `internal/` subfolder
5. Displays available targets - you're ready to use MakeBind!

### Custom installation path

### Explanation:
- This command downloads the Makefile template and creates a Makefile in your current directory.
- `make` will then automatically execute and check for the existence of the `MakeBind` folder in the path specified by `mb_mb_default_path` (default is `../MakeBind`, meaning it will search in the parent directory).
- If the `MakeBind` folder does not exist, the latest release will be downloaded.
- The folder `bind-hub` will be created in the current directory, which contains important configuration files, including `config.mk` and `project.mk`, plus an `internal/` subfolder for auto-generated files.
- You will then see a list of available targets, and you can start using MakeBind.
By default, MakeBind looks in the parent directory. For better control, you can:
- Manually clone the repo to your preferred location
- Set the `MB_MAKEBIND_GLOBAL_PATH_ENV` environment variable

NOTE: if you want better control of where MakeBind is installed, you can either manually clone the repo or download from Github.
But you can also specify `MB_MAKEBIND_GLOBAL_PATH_ENV` and set that to the path you want.
On Linux and macOS, you can do this by running:
To set the environment variable permanently on Linux/macOS:
```shell
cat <<'EOF' >> ~/.profile

# MakeBind: global path env used by MakeBind tooling
export MB_MAKEBIND_GLOBAL_PATH_ENV="full/path/to/MakeBind"
EOF
```
```
This will ensure that the environment variable is set for every session.

## Usage
MakeBind is designed to be simple to use and easy to configure. Here are some common commands you can use with MakeBind:
- `make`
The simplest way to run the default target which will just list all the available targets.
- `make <target>`
Run a specific target.

## Configuration
As mentioned, when you run MakeBind for the first time, it will create the `config.mk` and `project.mk` files in the folder `bind-hub`. These files are used to configure MakeBind for your project.
- In `config.mk`, you can set all configuration variables that are used by MakeBind modules or your own modules. You can create a local version named `config.local.mk` to override the default values (do not commit this file to your repository).
- In `project.mk`, you can add all targets that are specific to your project. You can create a local version named `project.local.mk` to override the default values (do not commit this file to your repository).
- In the `bind-hub` folder, you can add all your custom modules in `bind-hub/modules`.

## Upgrading Make

### On Linux (Debian)

Many Linux distributions come with `make` versions 4.2.1 or 4.3. We need to upgrade to the latest version.
The following script will install the latest version (specified in `SELECTED_MAKE_VERSION`):
Many Linux distributions ship with `make` 4.2.1 or 4.3. You'll need version 4.4+ for MakeBind.

> **Note:** This script requires admin privileges (sudo).

```shell
#!/bin/bash

export SELECTED_MAKE_VERSION="4.4.1"
sudo apt-get update
sudo apt-get install build-essential
sudo apt-get install build-essential
cd /tmp
wget "https://ftp.gnu.org/gnu/make/make-${SELECTED_MAKE_VERSION}.tar.gz"
tar -xvzf "make-${SELECTED_MAKE_VERSION}.tar.gz"
Expand All @@ -99,8 +94,7 @@ make
sudo make install
```

The above script will require admin privileges.
The script will:
This script will:
- Update your package list
- Install essential build packages for `make` compilation
- Navigate to the `/tmp` directory
Expand All @@ -112,44 +106,180 @@ To run this, copy and paste to a file (for example `update_make.sh`), then do:
chmod +x update_make.sh && ./update_make.sh
```

You can find all available `make` versions at [GNU's FTP site](https://ftp.gnu.org/gnu/make/).
If version `4.4.1` is no longer the latest, simply update the `SELECTED_MAKE_VERSION` variable in the script and re-run it.
Confirm that everything has been installed by doing `make --version` and checking that the version match the one specified in `SELECTED_MAKE_VERSION`.
You can find all available `make` versions at [GNU's FTP site](https://ftp.gnu.org/gnu/make/).
If version `4.4.1` is no longer the latest, update the `SELECTED_MAKE_VERSION` variable and re-run.

Verify the installation:
```shell
make --version
```

### On Mac

The default installed version of `make` on Mac is 3.81, which is outdated.
To upgrade your `make` version, we will use `homebrew`.
If you do not have `homebrew`, you can find the installation instructions [here](https://docs.brew.sh/Installation).
This is the package page: https://formulae.brew.sh/formula/make
If you are not using `Z shell`, replace `~/.zshrc` with the path to the appropriate configuration file for your shell.
macOS ships with `make` 3.81, which is too old. Use Homebrew to install a newer version.

To upgrade run the following script:
```bash
#!/bin/sh
> **Prerequisites:** [Homebrew](https://docs.brew.sh/Installation) must be installed.
> If you're not using zsh, replace `~/.zshrc` with your shell's config file.

```bash
brew install make
echo 'export PATH="$HOMEBREW_PREFIX/opt/make/libexec/gnubin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

To run this, copy and paste to a file (for example `update_make.sh`), then do:
This will:
- Install `make` via Homebrew (installed as `gmake`)
- Add the GNU make binary to your PATH so `make` uses the new version
- Reload your shell configuration

Verify the installation:
```shell
chmod +x update_make.sh && ./update_make.sh
make --version
```

This script will:
- Install `make` using Homebrew.
- Add the `gnubin` path to your shell configuration file:
- This command adds the new path to the top of your `~/.zshrc` file.
- Note: `$HOMEBREW_PREFIX` is an environment variable set during the installation of Homebrew. You can verify it using `echo $HOMEBREW_PREFIX`.
- This is needed to ensure that `make` is available as `brew` installs `make` as `gmake`.
- Reload your shell configuration:

This process should upgrade `make` to a more recent version.
Run `make --version` and confirm that the version is the latest one.

#### Autocompletion on Mac

If you want to enable autocompletion, you can use the extension [zsh-autosuggestions](https://github.com/zsh-users/zsh-autosuggestions).

## Common Commands

Here are the most commonly used commands in MakeBind:

| Command | Description |
|---------|-------------|
| `make` | List all available targets (default) |
| `make <target>` | Run a specific target |
| `make mb/modules/list` | List all available modules |
| `make mb/modules/add/<name>` | Add a module to your project |
| `make mb/modules/add/<name1>/<name2>` | Add multiple modules at once |
| `make mb/modules/remove/<name>` | Remove a module from your project |
| `make mb/help` | Get help on MakeBind |

## Module System

### What are Modules?

Modules are reusable packages of Makefile functionality. Instead of writing repetitive Makefile code for common tasks like Docker management, PHP tooling, or AWS operations, you can simply add the appropriate module and get access to pre-built targets.

For example, adding the `docker_compose` module gives you targets like:
- `dc/up` - Start containers
- `dc/down` - Stop containers
- `dc/logs` - View container logs

### Module Structure

Each module contains:
- `mod_info.mk` - Module metadata (name, version, dependencies)
- `<module>.mk` - Implementation with targets
- `mod_config.mk` - (Optional) Default configuration

For details on creating your own modules, see [modules/README.md](modules/README.md).

### System vs Project Modules

| Type | Location | Use Case |
|------|----------|----------|
| **System** | `modules/` (in MakeBind) | Reusable across all projects |
| **Project** | `bind-hub/modules/` | Specific to one project |

## Project Structure

### The bind-hub Folder

When you initialize MakeBind, it creates a `bind-hub` folder in your project with the following structure:

```
bind-hub/
├── config.mk # Project configuration (commit this)
├── config.local.mk # Local overrides (do NOT commit)
├── project.mk # Project-specific targets (commit this)
├── project.local.mk # Local target overrides (do NOT commit)
├── internal/ # Auto-generated files (do NOT edit)
│ └── modules.mk # List of enabled modules
├── configs/ # Module configuration overrides
│ └── <module>_config.mk
└── modules/ # Project-specific custom modules
└── <your_module>/
```

### Configuration Files

**config.mk** - Set configuration variables used by MakeBind and modules:
```makefile
mb_project_name := my-project
mb_project_path := $(abspath $(dir $(lastword $(MAKEFILE_LIST)))/..)
```

**config.local.mk** - Override settings for your local environment (gitignored):
```makefile
# Local overrides - do not commit
mb_debug := 1
```

**project.mk** - Add targets specific to your project:
```makefile
deploy: ## Deploy the application
./scripts/deploy.sh

test: ## Run tests
./scripts/test.sh
```

**project.local.mk** - Local target overrides (gitignored).

**configs/<module>_config.mk** - Override default module configuration:
```makefile
# Example: bind-hub/configs/docker_compose_config.mk
dc_file := docker/docker-compose.yml
dc_project_name := my-app
```

## Debug Options

When troubleshooting issues, you can enable various debug flags:

| Flag | Description |
|------|-------------|
| `mb_debug=1` | Enable general debugging output |
| `mb_debug_modules=1` | Debug module loading and discovery |
| `mb_debug_targets=1` | Debug target listing |
| `mb_debug_show_all_commands=1` | Show all shell commands being executed |

Usage:
```shell
make mb_debug=1
make mb_debug_modules=1 mb/modules/list
```

You can also set these in your `config.local.mk` for persistent debugging:
```makefile
mb_debug := 1
mb_debug_show_all_commands := 1
```

## Available Modules

MakeBind comes with modules organized by category:

| Category | Modules | Description |
|----------|---------|-------------|
| **Containers** | `docker`, `docker_compose` | Docker and Docker Compose management |
| **PHP** | `php`, `composer`, `phpunit`, `phpcs`, `phpstan`, `psalm` | PHP ecosystem tools |
| **PHP Frameworks** | `symfony`, `laravel` | Framework-specific targets |
| **Web Servers** | `nginx` | Web server management |
| **AWS** | `s3`, `sqs`, `sns`, `localstack` | AWS service integrations |
| **Infrastructure** | `terraform` | Infrastructure as Code |
| **Databases** | `postgresql` | Database management |
| **Project** | `project_builder` | Project scaffolding |

To see all available modules with descriptions:
```shell
make mb/modules/list
```

To add a module:
```shell
make mb/modules/add/docker_compose
```

Module dependencies are automatically resolved - if a module requires another module, it will be added automatically.
Loading