Austin Group Defect Tracker

Aardvark Mark IV

Main | My View | View Issues | Change Log | Docs
  

Viewing Issue Simple Details [ Jump to Notes ] [ Issue History ] [ Print ]
ID Category Severity Type Date Submitted Last Update
0000523 [1003.1(2008)/Issue 7] Shell and Utilities Objection Enhancement Request 2011-12-01 23:31 2020-03-18 15:32
Reporter dwheeler View Status public  
Assigned To ajosey
Priority normal Resolution Accepted As Marked  
Status Applied  
Name David A. Wheeler
Organization
User Reference
Section make
Page Number 2913
Line Number 95740
Interp Status ---
Final Accepted Text See Note: 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
Attached Files

- Relationships
related to 0000857Closed 1003.1(2013)/Issue7+TC1 Make rules which do not create the target file or do unexpected things with its timestamp 

-  Notes
(0001072)
dwheeler (reporter)
2011-12-01 23:56

 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.
(0001081)
eblake (manager)
2011-12-15 17:05
edited on: 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.

- Issue History
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 Note: 0001081
2014-08-07 16:18 eblake Relationship added related to 0000857
2015-04-23 23:13 emaste Issue Monitored: emaste
2020-03-18 15:32 geoffclare Status Resolved => Applied

Mantis 1.1.6[^]
Copyright © 2000 - 2008 Mantis Group
Powered by Mantis Bugtracker