yet another mostly cosmetic diff

- rename context into localvars, which is more meaningful and less generic
- instantiate the random rumbling at the start of gnode.h with actual
variable names
- explain and group gnode.h variables better
- make some comments terser/more meaningful

okay millert@

8 files changed, 65 insertions, 62 deletions

diff --git a/usr.bin/make/engine.c b/usr.bin/make/engine.c
index cb75f1e1e4f..d588e3c3e35 100644
--- a/usr.bin/make/engine.c
+++ b/usr.bin/make/engine.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: engine.c,v 1.58 2019/12/21 15:29:25 espie Exp $ */
+/*	$OpenBSD: engine.c,v 1.59 2019/12/21 15:31:54 espie Exp $ */
 /*
  * Copyright (c) 2012 Marc Espie.
  *
@@ -825,7 +825,7 @@ job_run_next(Job *job)
 		handle_all_signals();
 		job->location = &command->location;
 		Parse_SetLocation(job->location);
-		job->cmd = Var_Subst(command->string, &gn->context, false);
+		job->cmd = Var_Subst(command->string, &gn->localvars, false);
 		job->next_cmd = Lst_Adv(job->next_cmd);
 		if (fatal_errors)
 			Punt(NULL);
diff --git a/usr.bin/make/gnode.h b/usr.bin/make/gnode.h
index 242c2776120..6feea19d570 100644
--- a/usr.bin/make/gnode.h
+++ b/usr.bin/make/gnode.h
@@ -1,6 +1,6 @@
 #ifndef GNODE_H
 #define GNODE_H
-/*	$OpenBSD: gnode.h,v 1.32 2019/12/21 15:29:59 espie Exp $ */
+/*	$OpenBSD: gnode.h,v 1.33 2019/12/21 15:31:54 espie Exp $ */
 
 /*
  * Copyright (c) 2001 Marc Espie.
@@ -40,33 +40,32 @@
 #include <assert.h>
 
 /*-
- * The structure for an individual graph node. Each node has several
- * pieces of data associated with it.
- *	1) the name of the target it describes
- *	2) the location of the target file in the file system.
- *	3) the type of operator used to define its sources (cf parse.c)
- *	4) whether it is involved in this invocation of make
- *	5) whether the target has been rebuilt
- *	6) whether any of its children has been rebuilt
- *	7) the number of its children that are, as yet, not built
- *	8) its modification time
- *	9) the modification time of its youngest child (qv. make.c)
- *	10) a list of nodes for which this is a source
- *	11) a list of nodes on which this depends
- *	12) a list of nodes that depend on this, as gleaned from the
- *	    transformation rules.
- *	13) a list of nodes of the same name created by the :: operator
- *	14) a list of predecessors nodes, result of .ORDER:
+ * The structure for an individual graph node. Each node has a lot of
+ * of data associated with it.
+ *	1) the *name*of the target it describes (at end because ohash)
+ *	2) the *path* to the target file
+ *	3) the *type* of operator used to define its sources 
+ *		(cf parse.c, mostly : :: !  but...)
+ *	4) *must_make*: whether it is involved in this invocation of make
+ *	5) *built_status*: has the target been rebuilt/is up-to-date...
+ *	6) *child_rebuild*: at least one of its children has been rebuilt
+ *	7) *children_left*: number of children still to consider
+ *	8) *mtime*: node's modification time
+ *	9) *youngest*: youngest child (cf make.c)
+ *	10) *parents*: list of nodes for which this is a dependency
+ *	11) *children*: list of nodes on which this depends
+ *	12) *cohorts*: list of nodes of the same name created by the :: operator
+ *	13) *predecessors*: list of nodes, result of .ORDER:
  *	    if considered for building, they should be built before this node.
- *	15) a list of successors nodes, result of .ORDER:
+ *	14) *successors*: list of nodes, result of .ORDER:
  *	    if considered for building, they should be built after this node.
- *	16) a Lst of ``local'' variables that are specific to this target
- *	   and this target only (qv. var.c [$@ $< $?, etc.])
- *	17) a Lst of strings that are commands to be given to a shell
+ *	15) *localvars*: ``local'' variables specific to this target
+ *	   and this target only (cf var.c [$@ $< $?, etc.])
+ *	16) *commands*: the actual LIST of strings to pass to the shell
  *	   to create this target.
  */
 
-#define SPECIAL_NONE	0U
+#define SPECIAL_NONE		0U
 #define SPECIAL_PATH		21U
 #define SPECIAL_MASK		63U
 #define SPECIAL_TARGET		64U
@@ -99,8 +98,9 @@
 #define SPECIAL_EXPENSIVE	33U
 
 struct GNode_ {
-    unsigned int special_op;	/* special op to apply */
-    unsigned char special;	/* type of special node */
+    unsigned int type;		/* node type (see the OP flags, below) */
+    unsigned int special_op;	/* special op to apply (only used in parse.c) */
+    unsigned char special;	/* type of special node or SPECIAL_NONE */
     bool must_make;		/* true if this target needs building */
     bool child_rebuilt;		/* true if at least one child was rebuilt,
     			 	 * thus triggering timestamps changes */
@@ -116,36 +116,39 @@ struct GNode_ {
 				 * making an inferior */
 #define NOSUCHNODE	6	/* error from run_gnode */
 #define HELDBACK	7	/* Another target in the same group is
-				 * currently building, avoid race conditions */
+				 * currently building, avoid race conditions
+				 * Only used in the parallel engine make.c */
 
-    char *path;		/* The full pathname of the file */
-    unsigned int type;	/* Its type (see the OP flags, below) */
-    int order;		/* Its wait weight */
+    char *path;		/* full pathname of the file */
+    int order;		/* wait weight (see .ORDER/predecessors/successors) */
 
-    int children_left;	/* The number of children left to build */
-    int in_cycle;	/* cycle detection */
+    int children_left;	/* number of children left to build */
 
     struct timespec mtime;	/* Node's modification time */
     GNode *youngest;		/* Node's youngest child */
 
-    GNode *impliedsrc;
+    GNode *impliedsrc;	/* found by suff, to help with localvars */
     LIST cohorts;	/* Other nodes for the :: operator */
     LIST parents;	/* Nodes that depend on this one */
     LIST children;	/* Nodes on which this one depends */
     LIST predecessors;
     LIST successors; 	
 
-    SymTable context;	/* The local variables */
+    SymTable localvars;
     LIST commands;	/* Creation commands */
     Suff *suffix;	/* Suffix for the node (determined by
 			 * Suff_FindDeps and opaque to everyone
 			 * but the Suff module) */
-    GNode *sibling;	/* equivalent targets */
-    GNode *groupling;	/* target lists */
-    GNode *watched;	/* the node currently building */
-    /* stuff for target name equivalence */
+    GNode *groupling;	/* target lists, for HELDBACK: do not build two
+    			 * at the same time */
+    GNode *watched;	/* the node currently building for HELDBACK */
+
+			/* stuff for target name equivalence: */
+    GNode *sibling;	/* equivalent targets (not complete yet) */
     char *basename;	/* pointer to name stripped of path */
     GNode *next;
+
+    bool in_cycle;	/* cycle detection */
     char name[1];	/* The target's name */
 };
 
diff --git a/usr.bin/make/make.c b/usr.bin/make/make.c
index fa3de49e062..02e048ac056 100644
--- a/usr.bin/make/make.c
+++ b/usr.bin/make/make.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: make.c,v 1.75 2019/12/21 15:29:25 espie Exp $	*/
+/*	$OpenBSD: make.c,v 1.76 2019/12/21 15:31:54 espie Exp $	*/
 /*	$NetBSD: make.c,v 1.10 1996/11/06 17:59:15 christos Exp $	*/
 
 /*
@@ -50,7 +50,7 @@
  *	Make_Update		Update all parents of a given child. Performs
  *				various bookkeeping chores like finding the
  *				youngest child of the parent, filling
- *				the IMPSRC context variable, etc. It will
+ *				the IMPSRC local variable, etc. It will
  *				place the parent on the to_build queue if it
  *				should be.
  *
@@ -383,11 +383,10 @@ try_to_make_node(GNode *gn)
 		gn->built_status = UPTODATE;
 		if (gn->type & OP_JOIN) {
 			/*
-			 * Even for an up-to-date .JOIN node, we need it
-			 * to have its context variables so references
-			 * to it get the correct value for .TARGET when
-			 * building up the context variables of its
-			 * parent(s)...
+			 * Even for an up-to-date .JOIN node, we need its
+			 * local variables, so that we have the right
+			 * value for .TARGET when computing the
+			 * local variables of its parent(s)...
 			 */
 			Make_DoAllVar(gn);
 		}
diff --git a/usr.bin/make/suff.c b/usr.bin/make/suff.c
index cce46f2461a..7f8dfb69837 100644
--- a/usr.bin/make/suff.c
+++ b/usr.bin/make/suff.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: suff.c,v 1.97 2019/12/21 15:29:25 espie Exp $ */
+/*	$OpenBSD: suff.c,v 1.98 2019/12/21 15:31:54 espie Exp $ */
 /*	$NetBSD: suff.c,v 1.13 1996/11/06 17:59:25 christos Exp $	*/
 
 /*
@@ -936,7 +936,7 @@ SuffExpandVarChildren(LstNode after, GNode *cgn, GNode *pgn)
 	if (DEBUG(SUFF))
 		printf("Expanding \"%s\"...", cgn->name);
 
-	cp = Var_Subst(cgn->name, &pgn->context, true);
+	cp = Var_Subst(cgn->name, &pgn->localvars, true);
 	if (cp == NULL) {
 		printf("Problem substituting in %s", cgn->name);
 		printf("\n");
@@ -953,7 +953,7 @@ SuffExpandVarChildren(LstNode after, GNode *cgn, GNode *pgn)
 		 */
 		const char *sacrifice = (const char *)cp;
 
-		(void)Arch_ParseArchive(&sacrifice, &members, &pgn->context);
+		(void)Arch_ParseArchive(&sacrifice, &members, &pgn->localvars);
 	} else {
 		/* Break the result into a vector of strings whose nodes
 		 * we can find, then add those nodes to the members list.
@@ -980,7 +980,7 @@ SuffExpandVarChildren(LstNode after, GNode *cgn, GNode *pgn)
 				/* Start of a variable spec -- contact variable
 				 * module to find the end so we can skip over
 				 * it.  */
-				Var_ParseSkip(&cp2, &pgn->context);
+				Var_ParseSkip(&cp2, &pgn->localvars);
 			else if (*cp2 == '\\' && cp2[1] != '\0')
 				/* Escaped something -- skip over it.  */
 				cp2+=2;
diff --git a/usr.bin/make/symtable.h b/usr.bin/make/symtable.h
index d2e8105a6f4..cd34b450dbb 100644
--- a/usr.bin/make/symtable.h
+++ b/usr.bin/make/symtable.h
@@ -1,6 +1,6 @@
 #ifndef SYMTABLE_H
 #define SYMTABLE_H
-/*	$OpenBSD: symtable.h,v 1.4 2010/07/19 19:46:44 espie Exp $ */
+/*	$OpenBSD: symtable.h,v 1.5 2019/12/21 15:31:54 espie Exp $ */
 
 /*
  * Copyright (c) 2001 Marc Espie.
@@ -30,7 +30,7 @@
 #define LOCAL_SIZE	7
 
 /* SymTable is private to var.c, but is declared here to allow for
-   local declaration of context tables
+   local declaration of symbol tables
  */
 struct SymTable_ {
 	char *locals[LOCAL_SIZE];
diff --git a/usr.bin/make/targ.c b/usr.bin/make/targ.c
index 1cbeb86669d..f88440013d0 100644
--- a/usr.bin/make/targ.c
+++ b/usr.bin/make/targ.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: targ.c,v 1.80 2019/12/21 15:29:25 espie Exp $ */
+/*	$OpenBSD: targ.c,v 1.81 2019/12/21 15:31:54 espie Exp $ */
 /*	$NetBSD: targ.c,v 1.11 1997/02/20 16:51:50 christos Exp $	*/
 
 /*
@@ -165,7 +165,7 @@ Targ_NewGNi(const char *name, const char *ename)
 	Lst_Init(&gn->children);
 	Lst_Init(&gn->predecessors);
 	Lst_Init(&gn->successors);
-	SymTable_Init(&gn->context);
+	SymTable_Init(&gn->localvars);
 	gn->impliedsrc = NULL;
 	Lst_Init(&gn->commands);
 	gn->suffix = NULL;
diff --git a/usr.bin/make/var.c b/usr.bin/make/var.c
index 0ed3654bc36..ef1e295b7bc 100644
--- a/usr.bin/make/var.c
+++ b/usr.bin/make/var.c
@@ -1,4 +1,4 @@
-/*	$OpenBSD: var.c,v 1.101 2016/10/23 14:54:14 espie Exp $	*/
+/*	$OpenBSD: var.c,v 1.102 2019/12/21 15:31:54 espie Exp $	*/
 /*	$NetBSD: var.c,v 1.18 1997/03/18 19:24:46 christos Exp $	*/
 
 /*
@@ -574,7 +574,7 @@ Var_Mark(const char *name, const char *ename, unsigned int type)
 	}
 }
 
-/* Check if there's any reason not to use the variable in this context.
+/* Check if there's any reason not to use this variable.
  */
 static void
 poison_check(Var *v)
@@ -627,7 +627,7 @@ Var_Deletei(const char *name, const char *ename)
 	delete_var(v);
 }
 
-/* Set or add a global variable, in VAR_CMD or VAR_GLOBAL context.
+/* Set or add a global variable, either to VAR_CMD or VAR_GLOBAL.
  */
 static void
 var_set_append(const char *name, const char *ename, const char *val, int ctxt,
@@ -1029,7 +1029,7 @@ Var_Parse(const char *str,	/* The string to parse */
 	if (val == NULL) {
 		val = err ? var_Error : varNoError;
 		/* If it comes from a dynamic source, and it doesn't have
-		 * a context, copy the spec instead.
+		 * a local context, copy the spec instead.
 		 * Specifically, this make allows constructs like:
 		 * 	target.o: $*.c
 		 * Absence of a context means "parsing". But these can't
diff --git a/usr.bin/make/var.h b/usr.bin/make/var.h
index e7246a331fc..a831b581aec 100644
--- a/usr.bin/make/var.h
+++ b/usr.bin/make/var.h
@@ -1,6 +1,6 @@
 #ifndef VAR_H
 #define VAR_H
-/* $OpenBSD: var.h,v 1.19 2016/10/23 14:54:14 espie Exp $ */
+/* $OpenBSD: var.h,v 1.20 2019/12/21 15:31:54 espie Exp $ */
 /*
  * Copyright (c) 2001 Marc Espie.
  *
@@ -48,8 +48,9 @@ extern void Var_Seti_with_ctxt(const char *, const char *, const char *,
 #define Var_Set(n, v)	Var_Seti_with_ctxt(n, NULL, v, VAR_GLOBAL)
 #define Var_Seti(n, e, v) Var_Seti_with_ctxt(n, e, v, VAR_GLOBAL)
 /* Var_Appendi_with_ctxt(name, end, val, cxt);
- *	Appends value val to variable name/end in context ctxt, defining it
- *	if it does not already exist, and inserting one space otherwise. */
+ *	Appends value val to variable name/end in global context ctxt, 
+ *	defining it if it does not already exist, and inserting one 
+ *	space otherwise. */
 extern void Var_Appendi_with_ctxt(const char *, const char *,
 	const char *, int);
 #define Var_Append(n, v)	Var_Appendi_with_ctxt(n, NULL, v, VAR_GLOBAL)
@@ -68,7 +69,7 @@ extern void Var_Deletei(const char *, const char *);
 #define OODATE_INDEX	5
 #define ALLSRC_INDEX	6
 
-#define Var(idx, gn)	((gn)->context.locals[idx])
+#define Var(idx, gn)	((gn)->localvars.locals[idx])
 
 
 /* SymTable_Init(t);