I’ve been meaning to make a Makefile tutorial for the longest time. Makefiles have been a familiar face to most, recurring in unnoticeable corners in the likes of many GitHub repos. Yet they seldom invite us to open them up and dig into their complexities.
The first time I saw a Makefile was back in 2014 when I took my first college-level programming class in the C language. Ever since then, Makefiles have repeatedly popped up in various places in my studies, especially when I came across open-source projects. However, having never needed to create a decently large project, I’ve never taken the time to really understand all the nitty-gritty details of those Makefiles. Still, they haunted me.
Last Spring, I had finally gotten myself into a project so very non-trivially-sized that I decided to bite the bullet and dive into the depths of Makefiles and figure out what they’re all about. It was extremely frustrating. The documentation is not very helpful; it is strangely organized, with many forward references; functionalities are vaguely explained and too often left without illuminating examples; idiomatic code patterns are scattered all over the place; the worst offender is the poorly collated index and the lack of any search function whatsoever. Honestly, in my opinion, the official manual deserves much better treatment.
Most tutorials online only cover the most basic of usages, if not just outright wrong. Advanced techniques or knowledge are scattered around obscure blog posts and StackOverflow answers. Numerous idiomatic patterns are merely mentioned in a very hand-wavy style. You’d have to already be a veteran tool user to understand the actual ins and outs. Plus, mature Makefiles themselves are far from self-explanatory, so a green user would just be left clueless about what the hell is going on. It thus seeded in me the idea of writing up my own tutorials to go through everything I’ve learned.
In this series of blog posts, I intend to go from the most fundamental to the most intricate setups, using examples to illustrate how and why things work. I imagine it to be a continuous process, in which I will go back and forth between posts to polish and refine them, as the series evolves, from a crude draft to a fully developed publication. I hope that, in the end, it can hold a candle to all the well-written tutorials on the Internet that have helped me and that I’ve come to admire.