Jiby's toolbox

Jb Doyon’s personal website

Presentation: Makefiles for build automation and documentation

Posted on — Oct 23, 2022

Last Friday, I performed a presentation to my colleagues about Makefiles, and I want to share it to the public.

Of note, this presentation is setting aside what people usually know of Makefiles (autoconf-generated blobs, opaque to any inspection because machine-created), and instead I introduce the concept of file transformation as a graph, then teach Makefiles basics (using SQL commands as an example). We then move on to my plea for simple Makefiles, and their potential for both documentation (explain what your codebase commands are, to the juniors), and as lightweight automation (avoid typing long boring commands).

I start by describing how my job brings me to jump between many code repos, which can have confusing build/test/format commands. I feel those commands under-documented, and wish to have a single point of entry for all the important ones I should use around the codebase. I further believe this file can be a Makefile, and proceed to show how that could work.

Figure 1: Click to view the slides

Figure 1: Click to view the slides

For the adventurous, backup slides are available at the end, explaining extra complex behaviour, including my favourite: Polyglot Makefiles.

This presentation was long overdue, with my first notes for it going back to 2018. I’m glad I was finally able to make public my love of simple Makefiles, and hope everybody agree they’re pretty rad for this particular purpose.