b0317f4468344e0d3e5cc43fc46cea1d1e0d9576 — Charles Daniels 6 months ago 3a17f58
fix section headers in make guide
1 files changed, 59 insertions(+), 34 deletions(-)

M src/2017-07-15-guide-to-make.md
M src/2017-07-15-guide-to-make.md => src/2017-07-15-guide-to-make.md +59 -34
@@ 1,26 1,6 @@
# A Practical Guide to Make

# Contents

<!-- vim-markdown-toc GFM -->

* [Introduction](#introduction)
* [Background - What is Make?](#background---what-is-make)
* [Make Syntax](#make-syntax)
* [A Simple C Program](#a-simple-c-program)
* [Using Variables](#using-variables)
	* [Standard Variables](#standard-variables)
	* [Special Variables](#special-variables)
* [Pattern Rules](#pattern-rules)
* [Best Practices](#best-practices)
* [Common Gotchas and Pitfalls](#common-gotchas-and-pitfalls)
* [The Future of Build Systems](#the-future-of-build-systems)
* [Further Reading](#further-reading)
* [Edit History](#edit-history)

<!-- vim-markdown-toc -->

# Introduction
*Published 2017-07-15*

In this article, you will learn how to use the Make build system to compile
software projects. This article is targeted at those who have experience

@@ 35,7 15,11 @@ peers and students who have often completed one or more semesters of a
computing degree, and are competent programmers, but have not had the benefit
of UNIX experience.

# Background - What is Make?
<h2 class=navhdr id="background">
	Background - What is Make?
	<a href=#background class=navhandle>¶ </a>

The true purpose and utility of Make are often neglected in courses and
articles which discuss it. Make is often regarded and used as simply a tool

@@ 61,7 45,11 @@ which to execute the tasks B-F without repeating or executing a task without
it's dependencies, is a quite difficult problem, the complexity of which grows
multiplicatively with the number of targets and dependencies.

# Make Syntax
<h2 class=navhdr id="syntax">
	Make Syntax
	<a href=#syntax class=navhandle>¶ </a>

Make uses a very simple syntax. Targets are strings which start in column zero
and are terminated by a `:`, and followed by a list of dependencies. The

@@ 139,7 127,12 @@ executing B
executing A

# A Simple C Program
<h2 class=navhdr id="simpleprog">
	A Simple C Program
	<a href=#simpleprog class=navhandle>¶ </a>

Consider the following files comprising a simple C program:

@@ 234,9 227,16 @@ the `-` character, if say `module.o` did **not** exist, but `main.o` **did**,
the command `rm module.o` would fail, causing `make clean` to exit without
removing `main.o`.

# Using Variables
<h2 class=navhdr id="variables">
	Using Variables
	<a href=#variables class=navhandle>¶ </a>

<h3 class=navhdr id="standard_variables">
	Standard Variables
	<a href=#standard_variables class=navhandle>¶ </a>

## Standard Variables

In GNU make, variables are assigned in one of four ways. The simplest is with
the `:=` operator, and take the form `VARNAME := value`. The other three

@@ 270,8 270,11 @@ the date is Sun May 28 18:18:00 EDT 2017
VARNAME is: a string

<h3 class=navhdr id="special_variables">
	Special Variables
	<a href=#special_variables class=navhandle>¶ </a>

## Special Variables

**NOTE** What I refer to as "special variables" are actually referre to as
**Automatic Variables** in the Make documentation.

@@ 335,7 338,11 @@ Notice that all three of the compilation-related rules are considerably shorter
and easier to type. This is especially handy when writing a target which has
many dependencies which later change - any changes can be made in one place.

# Pattern Rules
<h2 class=navhdr id="pattern">
	Pattern Rules
	<a href=#pattern class=navhandle>¶ </a>

One of the most powerful, but also most arcane features of Make is [pattern

@@ 406,8 413,11 @@ opaque and intractable to developers not deeply familiar with Make.
Nevertheless, implicit rules are a longstanding and mature feature of Make
which any C developer should be familiar with.

<h2 class=navhdr id="best_practice">
	Best Practices
	<a href=#best_practice class=navhandle>¶ </a>

# Best Practices

* Be careful about which commands should fail the build when they fail, and
  which you can safely ignore failures of using the `-` character.

@@ 434,8 444,11 @@ which any C developer should be familiar with.
  compiler and all it’s options - this will save you lots of times if you decide
  you want to add another compiler flag or anything of that sort.

<h2 class=navhdr id="gotchas">
	Common Gotchas and Pitfalls
	<a href=#gotchas class=navhandle>¶ </a>

# Common Gotchas and Pitfalls

* Make targets must be indented by the tab character - this is NOT the same
  thing as some number of spaces.

@@ 449,7 462,10 @@ which any C developer should be familiar with.
  separate files (unlike Mac and Windows) - creating both in the same directory
  will cause unexpected consequences.

# The Future of Build Systems
<h2 class=navhdr id="future">
	The Future of Build Systems
	<a href=#future class=navhandle>¶ </a>

In the modern age, much of software development is moving away from Make.  It
is becoming increasingly common for new languages to implement first-party

@@ 500,15 516,24 @@ features and benefits of Make, with a few key differences:
  dependency or target is out of date. This can make it more reliable on some

# Further Reading
<h2 class=navhdr id="reading">
	Further Reading
	<a href=#reading class=navhandle>¶ </a>

* [Notes for New Make Users - Alexander Gromnitsky](http://gromnitsky.users.sourceforge.net/articles/notes-for-new-make-users/)
* [Official GNU Make Manual](https://www.gnu.org/software/make/manual/)

# Edit History

<h2 class=navhdr id="history">
	# Edit History
	<a href=#history class=navhandle>¶ </a>

* 2018-02-22 - removed "Using Make with Java" section, it was just an anecdote
  and did not provide a useful example, nor useful information.
* 2018-03-02 - Added Pattern Rules section.
* 2018-03-02 - Added "The Future of Build Systems" section.
* 2018-03-06 - Added "Further Reading" Section
* 2018-03-06 - Added "Further Reading" Section.
* 2019-11-25 - Update section headers to new style.