From 5ce0720bcf0bec8a0a6c919f4155fb6ef8f56342 Mon Sep 17 00:00:00 2001
From: Juan Carrano <j.carrano@fu-berlin.de>
Date: Mon, 23 Jul 2018 17:03:07 +0200
Subject: [PATCH] Makefile.include: Explain usage of FORCE and PHONY.

---
 Makefile.include | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/Makefile.include b/Makefile.include
index a809d22910..0915216c83 100644
--- a/Makefile.include
+++ b/Makefile.include
@@ -349,9 +349,20 @@ include $(RIOTMAKE)/modules.inc.mk
 .PHONY: all link clean flash flash-only term doc debug debug-server reset objdump help info-modules
 .PHONY: print-size elffile binfile hexfile
 .PHONY: ..in-docker-container
-# Target can depend on FORCE to always rebuild but still let make use file
-# modification timestamp (contrary to .PHONY).
-# Use it for goals that may keep outputs unchanged when executed.
+
+# Targets that depend on FORCE will always be rebuilt. Contrary to a .PHONY
+# target, they are considered real files and the modification timestamp is taken
+# into account.
+#
+# FORCE is useful for goals that may keep outputs unchanged (for example, if it
+# depends on environment or configuration variables). If the goal were .PHONY, it
+# would trigger a rebuild of all its dependents regardless of file modification.
+#
+# As general rule, use .PHONY only for non-file targets.
+#
+# For more information, see:
+# https://www.gnu.org/software/make/manual/html_node/Phony-Targets.html
+# https://www.gnu.org/software/make/manual/html_node/Force-Targets.html
 .PHONY: FORCE
 
 ELFFILE ?= $(BINDIR)/$(APPLICATION).elf
-- 
GitLab