Makefile: Заменяем документацию командами

Когда-то много лет назад, я задолбался писать длинные и составные команды, которые были нужны в разных проектах. Особенно актуальной эта проблема стала с появлением Docker и Docker Compose. Некоторые связки для запуска, апдейта и изменений, требовали прямо таки серьезных многострочников. Типа такого:

 docker run -it --rm \
  -v $(CURDIR):/runner/project \
  quay.io/ansible/ansible-runner ansible-vault edit

Выходов из этой ситуации было несколько, например, скидывать их куда-то в доку типа README.md и копировать оттуда. Частично мы так и делали, но оно все время устаревает и просто задалбывает.

Часть команд можно запихнуть во встроенный инструментарий языков, к ним относятся rake tasks, npm scripts и так далее. И это даже хорошо работает, но только до тех пор пока команды простые и скорее относятся к инструментам на этом же языке. Если ваша задача запустить подряд пяток команд Docker Compose, то большинство этих инструментов будут неудобными. Да это пытаются решить тем что создают универсальные запускалки, но ни одна из них не стала по настоящему популярной сквозь разные экосистемы. Почти все эти инструменты носят локальный характер для какого-то языка или конкретного стека.

Можно пойти по хардкору и начать самому писать консольные скрипты, я знаю людей которые так делают. Но мы тут резко скатываемся в необходимость программирования. Нам захочется иметь не просто команды для запуска, а например строить между ними зависимости, чтобы не дублировать один и тот же код постоянно. А это придется писать ручками в таком случае.

Другой подход это алиасы в bash/zsh/fish. Но мне эта идея никогда не нравилась, потому что алиасы глобальны, а большая часть команд локальна для какого-то проекта. Несмотря на это алиасы все же заняли свое место в этой системе, но не рукопашные, а те что идут в коробке из ohmyzsh. Далеко не все знают, но это по сути ключевая фича этого инструмента. Вы только посмотрите, что он позволяет делать с гитом https://github.com/ohmyzsh/ohmyzsh/tree/master/plugins/git (а там есть комбо для всех популярных консольных утилит).

Ну и наконец, самый, как оказалось удобный подход. У нас есть старый добрый Make, который либо стоит уже сразу, либо крайне просто ставится в систему. У него есть команды, зависимости и возможность писать консольные команды напрямую (для большинства ситуаций). Еще году в 2015 я полностью перевел все свои проекты на Makefile, которые не просто решили проблему написания и запуска команд, но и создали некий универсальный язык, заменяющий доку. В любом моем проекте открыв Makefile можно понять все, что нужно для работы с проектом: make setup, make test, make lint, make run все эти команды универсальны независимо от стека.

include make-app.mk
include make-compose-app.mk
include make-compose.mk
include k8s/Makefile

project-setup: ansible-generate-env compose-setup

ansible-generate-env:
 docker run --rm -e RUNNER_PLAYBOOK=ansible/development.yml \
  -v $(CURDIR)/ansible/development:/runner/inventory \
  -v $(CURDIR):/runner/project \
  quay.io/ansible/ansible-runner

Прикольно то, что со временем это стали видеть многие и даже популярные проекты стали внедрять Makefile. Я помню был пост Андрея Ситника, где он рассказывал, как перевел команды для своей либы с npm scripts на Makefile и был удивлен как все упростилось.

В общем рекомендую. Мое видео на тему: https://www.youtube.com/watch?v=pK9mF5aK05Q

Ссылки: Телеграм | Youtube | VK