05 Mar 2020

Self documenting Makefile

One of the pain points of starting a new project or even hacking on existing project is to know where to start. One can start with documentation, test cases or even running it to see the logs and stacktraces (Stracktrace way is one of my favourite and you can tell a lot about code flow, organzation and you can even find un-handled bugs that way, which is a topic of its own for a blog post). Each language brings in its own set of tools that you need to know before you getting familiar with the code base. You might add `README` or some other documents to ease the pain but it might get stale overtime. One convention that I have been using, which has paid off with any project or teams that I have collaborated, are following simple conventions:

Above might sound a lot to ask but it is really trivial to do those with just following make file:

.PHONY: help
help: ## This is a cool project. It does great things to help humanity move forward.
	@echo 'usage: make [target] ...'
	@echo 'Targets Depends Description' | column -t -s ' '
	@echo '------- ------- -----------' | column -t -s ' '
	@egrep '^(.+)\:?.+\ ##\ (.+)' ${MAKEFILE_LIST} \
	| column -t -s ':#' | sed 's/Makefile  //'

setup: ## Sets up all that are needed start working on the project.
	@echo Setting up...
	# Put you logic here
	@echo Setting up done.

deps: setup ## Pulls in all required dependencies
	@echo Pulling all project dependencies

unit-test: deps ## Runs local tests
	@echo Running unit-tests...
	# Put your run unit-tests logic here
	@echo unit-tests done.

integration-test: deps ## Runs non local tests
	@echo Running integration-tests...
	# Put your run integration-tests logic here
	@echo integration-tests done.

The presence of above Makefile should not be underestimated. It will allow yourself and your fellow developers to dive into any project with just one liner like this:

git clone <project> && cd project && make deps

Would not that be wonderful if every project just follow simple conventions like this so you have less obstacle to start or dive into a project? It has benefited me and my team over the years and hope you see the benefit for yourself.

Tags: Makefile