Common project usage: Makefile API
Contents
It’s common for me to jump around between projects. For example, I may be working on a backend service and need to jump to a frontend SPA to help the team on some deadline or other specific goal.
But cloning a new project always gives me bad memories. Not being able to run the tests (or not having tests at all), not knowing how to start/run the project (it may have docs for it if I’m lucky). And the worst part: not knowing how to deploy/publish a new version.
To try to address this, I always try to sell the idea that all projects should
have a Makefile
with a common api for running tests, the app, etc.
Makefile API
The idea is to have a Makefile
with typical targets that are present on all
projects. For example, all projects should be able to run make test
.
This is always a bit hard to sell. Developers will argue that they already
have yarn test
or bundle exec rspec
or lein test
, etc.
But for something that is picking up the project, that may not be up to date on
it, it’s hard to find all the available commands and how to run them. So I
suggest that we should have a Makefile
with the following targets:
make bootstrap
- one time command that will install required services, like the databases, etc. This works well if everyone uses the same system (for example,brew
on macs). So we may need to have specific per-system targets.make install
- will install and/or update the current project’s dependencies. This usually runsyarn install
orbundle install
.make test
- will run the development test suite (yarn test
orlein test
).make run
- will start the application. It will also output it’s URL or maybe how to use it.make ci
- steps to run the build pipeline.make docker
- builds a docker image for the project.make deploy
- deploys the project. It may not be possible to run this locally without extra settings. But at least we’ll know what is being done.
Developers may continue to use their common commands, but this way we have an interface that anyone else can follow.
Example Makefile
With a bit of makefile magic we can have an output that shows the available targets and what they do.
.PHONY: help test
help: ## Shows the available commands.
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
test: ## Runs the development test suite.
lein test
Running make
or make help
would output:
$ make help
help Shows the available commands.
test Runs the development test suite.
Summary
Developers end up liking the idea and actually start using the Makefile
to add
specific project related commands (for example, to fetch/build translations).
This is not a replacement for proper documentation, but does help in having a
consistent API that facilitates the
onboarding of new contributors.