0000523: Add support for special target .PHONY in make

ID	Project	Category	View Status	Date Submitted	Last Update

0000523	1003.1(2008)/Issue 7	Shell and Utilities	public	2011-12-01 23:31	2024-06-11 08:53

Reporter	dwheeler	Assigned To	ajosey
Priority	normal	Severity	Objection	Type	Enhancement Request
Status	Closed	Resolution	Accepted As Marked

Name	David A. Wheeler
Organization
User Reference
Section	make
Page Number	2913
Line Number	95740
Interp Status	---
Final Accepted Text	See 0000523:0001081


Summary	0000523: Add support for special target .PHONY in make
Description	It is often useful to define "make" targets that are not simply the name of a file generated when running make, but are instead the name of a "recipe" to do some task by that name. In these cases, it is useful to be able to declare that these targets are "PHONY" using the .PHONY special target. Such targets are considered to not exist for the purposes of make's execution. One use case is names for items that will never create a file. "make all", "make test", and "make clean" are some common cases. It's common to see: .PHONY: all all: prog1 prog2 So that "make all" will always make "prog1" and "prog2". Otherwise, if a file "all" was ever created in the directory, "make all" probably fail to work as intended. Instead, make will check to see that all came after prog1 and prog2, and if it is, is will not rebuild prog1 and prog2 as needed. There are also performance advantages; on systems with rule chaining, implicit rule searching can be short-circuited (since the system knows the file will not exist, for make's purposes). Another use case is when you want to name subdirectories, so that "make DIR" will execute the default makefile for some subdirectory DIR. In this case, the subdirectory DIR will already exist, making it more convoluted to execute the make. By declaring DIR as .PHONY, make will ignore the fact that the directory already exists, and act as if it did not. Many implementations of "make" include support for the special target .PHONY, including: * GNU make * NetBSD make (implemented as "bmake" on Fedora Linux) * FreeBSD’s make http://www.freebsd.org/cgi/man.cgi?query=make&sektion=1 * OpenBSD’s make http://www.openbsd.org/cgi-bin/man.cgi?query=make&apropos=0&sektion=0&manpath=OpenBSD+Current&arch=i386&format=html * fastmake http://www.fastmake.org/doc.html For example, here is FreeBSD's documentation on .PHONY: .PHONY Apply the .PHONY attribute to any specified sources. Targets with this attribute are always considered to be out of date." This is so useful that even some very basic introductions to "make" include it, e.g.: http://linuxdevcenter.com/pub/a/linux/2002/01/31/make_intro.html?page=2 Phony targets can have prerequisites, but I don't think that needs to be specified here; the existing make specification handles that quite well without any additional material. I didn't find much documentation on what should happen with a blank target list for phony, that is: .PHONY: but both GNU make and NetBSD make ignore such statements, which seems reasonable enough. Erasing the list, as with .SUFFIXES, seems like a bad idea. I did add to the definition some material that's only implied in typical documentation. Once you "build" a phony target, it's not rebuilt again during that execution of 'make'. For example, "make all" will print "Hello there" only once, not twice, given this makefile: all: def ghi def: abc ghi: abc abc: @echo "Hello there" .PHONY: abc You can sort-of get the effect of .PHONY in the first case by selecting a file you're "sure" won't happen, e.g., "FORCE": clean: FORCE rm $(objects) FORCE: However, using .PHONY is more specific and efficient (especially if a make implements rule chaining or complex VPATHs). And if someone creates a file named FORCE, very weird things happen in this case. (If the filesystem folds case, which happens on some systems, even creating files like "force" can cause real problems.) And this approach completely fails to handle the case where you'd like to allow "make DIR", where DIR is the name of a subdirectory to be built. As a result, many "make" implementations include .PHONY.
Desired Action	On page 2913, before line 95740, insert the following definition for the special target .PHONY (note that this text is intentionally similar to the text of .SILENT): .PHONY Prerequisites of this special target are targets themselves; these targets shall be considered always out-of-date when the make utility begins executing. If a phony target's commands are executed, that phony target shall then be considered up-to-date until the execution of make completes. Subsequent occurrences of .PHONY shall also apply these rules to the additional targets. A .PHONY special target with no prerequisites shall be ignored. If the "-t" option is specified, targets declared as phony shall not be touched.
Tags	issue8

dwheeler 2011-12-01 23:56 reporter bugnote:0001072	P.S.: You can say in a POSIX makefile DIR: FORCE (commands) FORCE: As long as FORCE doesn't exist, you can do "Make DIR" even if the subdirectory doesn't exist. But this is not as clear, nor as efficient, as building .PHONY into make itself. The fact that so many make implementations include .PHONY demonstrates its utility. As an exception that proves the rule, perl Makefile::Parser by Agent Zhang includes the program "plmake". It does not have many features, in fact, it says "there are quite a lot of limitations" in the underlying parser. Yet its documentation only 4 issues as key limitations, and ".PHONY is not supported" is one of them. I wouldn't consider its non-support a blocker, as it's basically experimental (plmake's documentation says "Please don't use it in production."). Yet if even an experimental incomplete implementation has a big concern because it fails to implement .PHONY, then clearly .PHONY is a useful facility.

eblake 2011-12-15 17:05 manager bugnote:0001081 Last edited: 2011-12-15 17:15	At line 95610 [ASYNCHRONOUS EVENTS], change "or the target is a prerequisite of the special target .PRECIOUS" to "or the target is a prerequisite of the special targets .PHONY or .PRECIOUS" in describing when targets are not removed on receipt of signals. Prior to line 95740 [EXTENDED DESCRIPTION Target Rules], add .PHONY Prerequisites of this special target are targets themselves; these targets (known as /phony targets/) shall be considered always out-of-date when the make utility begins executing. If a phony target's commands are executed, that phony target shall then be considered up-to-date until the execution of make completes. Subsequent occurrences of .PHONY shall also apply these rules to the additional targets. A .PHONY special target with no prerequisites shall be ignored. If the "-t" option is specified, phony targets shall not be touched. Phony targets shall not be removed if make receives one of the asynchronous events explicitly described in the ASYNCHRONOUS EVENTS section. At line 95774, add ".PHONY," prior to ".POSIX" in the list of special targets that shall be specified without commands. After line 96368 [RATIONALE], add a new paragraph: Traditionally, constructs such as DIR: FORCE (commands) FORCE: were used to allow 'make DIR' to always run (commands); however, this depended on the user never creating a file named 'FORCE'. The addition of the .PHONY special target provides a more efficient manner of providing a target whose commands are always run, and where the user cannot create a file that influences behavior in an unexpected manner.

Date Modified	Username	Field	Change
2011-12-01 23:31	dwheeler	New Issue
2011-12-01 23:31	dwheeler	Status	New => Under Review
2011-12-01 23:31	dwheeler	Assigned To	=> ajosey
2011-12-01 23:31	dwheeler	Name	=> David A. Wheeler
2011-12-01 23:31	dwheeler	Section	=> make
2011-12-01 23:31	dwheeler	Page Number	=> 2913
2011-12-01 23:31	dwheeler	Line Number	=> 95740
2011-12-01 23:56	dwheeler	Note Added: 0001072
2011-12-15 17:05	eblake	Note Added: 0001081
2011-12-15 17:15	eblake	Note Edited: 0001081
2011-12-15 17:19	nick	Interp Status	=> ---
2011-12-15 17:19	nick	Final Accepted Text	=> See bugnote: 1081
2011-12-15 17:19	nick	Status	Under Review => Resolved
2011-12-15 17:19	nick	Resolution	Open => Accepted As Marked
2011-12-15 17:19	nick	Tag Attached: issue8
2011-12-15 17:19	nick	Final Accepted Text	See bugnote: 1081 => See 0000523:0001081
2014-08-07 16:18	eblake	Relationship added	related to 0000857
2020-03-18 15:32	geoffclare	Status	Resolved => Applied
2024-06-11 08:53	agadmin	Status	Applied => Closed

View Issue Details

Relationships

Activities

Issue History