[src/trunk]: src/usr.bin/make make(1): document the enum GNodeMade

[rillig <rillig%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a9132e5fa6d3
branches:  trunk
changeset: 978545:a9132e5fa6d3
user:      rillig <rillig%NetBSD.org@localhost>
date:      Tue Nov 24 17:42:31 2020 +0000

description:
make(1): document the enum GNodeMade

Given only the state names and their individual documentation, it is
hard to see the full picture.  To make this easier, provide typical
examples of the ways that a GNode takes through these states.

diffstat:

 usr.bin/make/compat.c |  19 ++++++++++++-------
 usr.bin/make/make.h   |  49 +++++++++++++++++++++++++++++++++++++------------
 2 files changed, 49 insertions(+), 19 deletions(-)

diffs (130 lines):

diff -r 6c251cbce98e -r a9132e5fa6d3 usr.bin/make/compat.c
--- a/usr.bin/make/compat.c     Tue Nov 24 16:38:31 2020 +0000
+++ b/usr.bin/make/compat.c     Tue Nov 24 17:42:31 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: compat.c,v 1.189 2020/11/24 16:28:44 rillig Exp $      */
+/*     $NetBSD: compat.c,v 1.190 2020/11/24 17:42:31 rillig Exp $      */
 
 /*
  * Copyright (c) 1988, 1989, 1990 The Regents of the University of California.
@@ -96,7 +96,7 @@
 #include "pathnames.h"
 
 /*     "@(#)compat.c   8.2 (Berkeley) 3/19/94" */
-MAKE_RCSID("$NetBSD: compat.c,v 1.189 2020/11/24 16:28:44 rillig Exp $");
+MAKE_RCSID("$NetBSD: compat.c,v 1.190 2020/11/24 17:42:31 rillig Exp $");
 
 static GNode *curTarg = NULL;
 static pid_t compatChild;
@@ -470,6 +470,9 @@
 static Boolean
 MakeUnmade(GNode *const gn, GNode *const pgn)
 {
+
+       assert(gn->made == UNMADE);
+
        /*
         * First mark ourselves to be made, then apply whatever transformations
         * the suffix module thinks are necessary. Once that's done, we can
@@ -480,9 +483,12 @@
         */
        gn->flags |= REMAKE;
        gn->made = BEINGMADE;
+
        if (!(gn->type & OP_MADE))
                Suff_FindDeps(gn);
+
        MakeNodes(gn->children, gn);
+
        if (!(gn->flags & REMAKE)) {
                gn->made = ABORTED;
                pgn->flags &= ~(unsigned)REMAKE;
@@ -503,20 +509,19 @@
                gn->made = UPTODATE;
                DEBUG0(MAKE, "up-to-date.\n");
                return FALSE;
-       } else
-               DEBUG0(MAKE, "out-of-date.\n");
+       }
 
        /*
         * If the user is just seeing if something is out-of-date, exit now
         * to tell him/her "yes".
         */
+       DEBUG0(MAKE, "out-of-date.\n");
        if (opts.queryFlag)
                exit(1);
 
        /*
-        * We need to be re-made. We also have to make sure we've got a $?
-        * variable. To be nice, we also define the $> variable using
-        * Make_DoAllVar().
+        * We need to be re-made.
+        * Ensure that $? (.OODATE) and $> (.ALLSRC) are both set.
         */
        Make_DoAllVar(gn);
 
diff -r 6c251cbce98e -r a9132e5fa6d3 usr.bin/make/make.h
--- a/usr.bin/make/make.h       Tue Nov 24 16:38:31 2020 +0000
+++ b/usr.bin/make/make.h       Tue Nov 24 17:42:31 2020 +0000
@@ -1,4 +1,4 @@
-/*     $NetBSD: make.h,v 1.215 2020/11/23 20:41:20 rillig Exp $        */
+/*     $NetBSD: make.h,v 1.216 2020/11/24 17:42:31 rillig Exp $        */
 
 /*
  * Copyright (c) 1988, 1989, 1990, 1993
@@ -173,18 +173,43 @@
 #include "buf.h"
 #include "make_malloc.h"
 
+/*
+ * The typical flow of states is:
+ *
+ * The direct successful path:
+ * UNMADE -> BEINGMADE -> MADE.
+ *
+ * The direct error path:
+ * UNMADE -> BEINGMADE -> ERROR.
+ *
+ * The successful path when dependencies need to be made first:
+ * UNMADE -> DEFERRED -> REQUESTED -> BEINGMADE -> MADE.
+ *
+ * A node that has dependencies, and one of the dependencies cannot be made:
+ * UNMADE -> DEFERRED -> ABORTED.
+ *
+ * A node that turns out to be up-to-date:
+ * UNMADE -> BEINGMADE -> UPTODATE.
+ */
 typedef enum GNodeMade {
-    UNMADE,                    /* Not examined yet */
-    DEFERRED,                  /* Examined once (building child) */
-    REQUESTED,                 /* on toBeMade list */
-    BEINGMADE,                 /* Target is already being made.
-                                * Indicates a cycle in the graph. */
-    MADE,                      /* Was out-of-date and has been made */
-    UPTODATE,                  /* Was already up-to-date */
-    ERROR,                     /* An error occurred while it was being
-                                * made (used only in compat mode) */
-    ABORTED                    /* The target was aborted due to an error
-                                * making an inferior (compat). */
+    /* Not examined yet. */
+    UNMADE,
+    /* The node has been examined but is not yet ready since its
+     * dependencies have to be made first. */
+    DEFERRED,
+    /* The node is on the toBeMade list. */
+    REQUESTED,
+    /* The node is already being made.
+     * Trying to build a node in this state indicates a cycle in the graph. */
+    BEINGMADE,
+    /* Was out-of-date and has been made. */
+    MADE,
+    /* Was already up-to-date, does not need to be made. */
+    UPTODATE,
+    /* An error occurred while it was being made (used only in compat mode). */
+    ERROR,
+    /* The target was aborted due to an error making a dependency (compat). */
+    ABORTED
 } GNodeMade;
 
 /* The OP_ constants are used when parsing a dependency line as a way of