告别Makefile混乱：如何使用fidry/makefile提升项目构建规范与协作效率

在软件开发的世界里，自动化是提升效率的关键。对于许多 PHP 项目而言，Makefile 常常扮演着这样的角色，它能将一系列复杂的命令封装成简单的指令，比如 make test、make deploy 等，让开发者能够一键执行任务。这无疑极大地提高了开发效率。

然而，随着项目的迭代和团队规模的扩大，makefile 也常常会成为一个“痛点”。你是否曾遇到过以下场景：

1. 文档缺失或过时： 新成员入职，面对项目根目录下的 Makefile，一脸懵逼，不知道有哪些可用的命令，或者 make help 的输出根本就是一堆乱码或过时的信息。
2. 规范不一： 不同的开发者编写 Makefile 的风格各异，有的命令有注释，有的没有；有的目标（target）声明是三行，有的只有一行，导致可读性极差。
3. 重复定义与冲突： 不小心定义了重复的命令，或者修改了一个命令，却忘记更新相关的帮助信息，导致团队协作效率低下，甚至引发难以察觉的构建错误。
4. 难以测试： Makefile 的内容通常被视为“脚本”，很少有人会为其编写测试，这意味着潜在的错误可能在最不合时宜的时候爆发。

这些问题让原本旨在提升效率的 Makefile 反而变成了团队协作的绊脚石。正当我一筹莫展之际，Composer 帮我找到了救星——fidry/makefile。

Composer在线学习地址：学习地址

fidry/makefile：Makefile 的“守护者”

fidry/makefile 是一个非常实用的 Composer 包，它旨在帮助你规范化、测试和维护 Makefile。它提供了一套工具，可以解析 Makefile 的内容，并允许你针对其结构和约定进行自动化测试。这意味着，你可以像测试 PHP 代码一样，确保你的 Makefile 始终保持整洁、一致和正确。

安装 fidry/makefile：

使用 Composer 安装非常简单：

<code class="bash">composer require --dev fidry/makefile</code>

注意，这个包通常只在开发环境中使用，所以我们使用 --dev 标志。

如何解决问题：以测试驱动 Makefile 规范

fidry/makefile 的核心理念之一，就是通过测试来强制执行 Makefile 的规范。它提供了一个 BaseMakefileTestCase 类，你可以继承它来编写自己的 Makefile 测试。

假设我们希望 Makefile 中的命令都遵循一个清晰的声明格式：

<code class="makefile">.PHONY: test
test:   ## Executes all the tests
test: composer_validate phpunit</code>

这种格式包括：

AI Web Designer

AI网页设计师，快速生成个性化的网站设计

下载

1. .PHONY 声明：确保该目标即使存在同名文件也会被执行。
2. ## 注释：用于生成 make help 的帮助信息。
3. 实际的规则定义。

使用 fidry/makefile，你可以这样测试你的 Makefile：

首先，创建一个 Makefile 文件（例如在项目根目录）：

<code class="makefile"># See https://tech.davis-hansson.com/p/make/
MAKEFLAGS += --warn-undefined-variables
MAKEFLAGS += --no-builtin-rules

.DEFAULT_GOAL := default


#
# Commands
#---------------------------------------------------------------------------

.PHONY: help
help:
    @printf "Usage:
  make TARGET

#
# Commands
#---------------------------------------------------------------------------
"
    @fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\$$//' | sed -e 's/##//' | awk 'BEGIN {FS = ":"}; {printf "%s:%s
", $$1, $$2}'

.PHONY: default
default:   ## Runs the default task
default: cs test

.PHONY: test
test:   ## Executes all the tests
test: composer_validate phpunit

.PHONY: composer_validate
composer_validate:  ## Validates the Composer package
composer_validate:
    composer validate --strict

.PHONY: phpunit
phpunit:   ## Runs PHPUnit
phpunit: $(PHPUNIT_BIN) vendor
    $(PHPUNIT)

#
# Rules
#---------------------------------------------------------------------------

vendor: composer.json
    $(COMPOSER) update --no-scripts
    touch -c $@
    touch -c $(PHPUNIT_BIN)

$(PHPUNIT_BIN): vendor
    touch -c $@</code>

然后，创建一个 PHPUnit 测试文件（例如 tests/MakefileTest.php）：

<code class="php"><?php declare(strict_types=1);

namespace Acme;

use FidryMakefileTestBaseMakefileTestCase;

/**
 * @coversNothing
 */
class MakefileTest extends BaseMakefileTestCase
{
    protected static function getMakefilePath(): string
    {
        // 指向你的 Makefile 文件路径
        return __DIR__.'/../Makefile';
    }

    protected function getExpectedHelpOutput(): string
    {
        // 这里是你期望 `make help` 命令的输出内容
        // 你可以手动运行 `make help`，然后复制其输出到这里
        return <<<'EOF'
            Usage:
              make TARGET

            #
            # Commands
            #---------------------------------------------------------------------------
            default: Runs the default task
            test:    Runs all the tests
            composer_validate:  Validates the Composer package
            phpunit:    Runs PHPUnit

            EOF;
    }
}</code>

这个测试做了什么？

当你运行 PHPUnit 时，BaseMakefileTestCase 会：

1. 解析 Makefile： 它会读取并解析你指定的 Makefile 文件。
2. 检查常见约定：
   • 确保所有带有 ## 注释的命令都遵循 .PHONY: target 和 target: ## comment 的三行声明模式。
   • 检查是否存在重复定义的命令。
3. 验证 help 输出： 它会实际执行 make help 命令，并将其输出与你在 getExpectedHelpOutput() 方法中定义的期望字符串进行比较。这意味着，如果你的 Makefile 帮助信息过时或格式不正确，测试会立即失败！

fidry/makefile 的优势与实际应用效果

通过引入 fidry/makefile，你的项目将获得以下显著优势：

1. 强制规范化： 团队成员必须遵循统一的 Makefile 编写规范，否则测试将失败，从源头杜绝混乱。
2. 提升可维护性： 清晰的结构和自动生成的帮助文档，让 Makefile 更容易理解和维护。
3. 降低新成员上手门槛： 稳定的 make help 输出，为新成员提供了可靠的命令参考，加速其融入项目。
4. 预防潜在错误： 自动检查重复定义、格式不一致等问题，在早期发现并修复潜在的构建错误。
5. 增强团队协作： 统一的规范减少了沟通成本和协作摩擦，让团队成员能够更高效地协同工作。
6. CI/CD 集成： 将 Makefile 测试集成到你的持续集成/持续部署（CI/CD）流程中，确保每次代码提交后 Makefile 的健康状态。

总结

Makefile 作为项目自动化构建的重要组成部分，其自身的质量和规范性同样不容忽视。fidry/makefile 这个 Composer 包为我们提供了一个优雅且强大的解决方案，它通过引入测试驱动的开发模式，将 Makefile 从一个可能令人头疼的配置脚本，变成了一个可靠、标准化且易于维护的构建利器。

如果你正在为 Makefile 的混乱而烦恼，或者希望提升团队的协作效率和项目的可维护性，那么 fidry/makefile 绝对值得你尝试。让你的 Makefile 不再是“野蛮生长”，而是成为一个真正高效、可靠的工具！