Thread: Confused about gram.y referencs in Makefile?
Hi, hackers I find src/backend/utils/mb/Unicode/Makefile has the following comments: > # Note that while each script call produces two output files, to be > # parallel-make safe we need to split this into two rules. (See for > # example gram.y for more explanation.) > # I could not find the explanation in gram.y easily. Would someone point it out for me? Thanks in advance! -- Regrads, Japin Li
Japin Li <japinli@hotmail.com> writes:
> I find src/backend/utils/mb/Unicode/Makefile has the following comments:
>> # Note that while each script call produces two output files, to be
>> # parallel-make safe we need to split this into two rules. (See for
>> # example gram.y for more explanation.)
> I could not find the explanation in gram.y easily. Would someone point
> it out for me? Thanks in advance!
It's referring to this bit in src/backend/parser/Makefile:
-----
# There is no correct way to write a rule that generates two files.
# Rules with two targets don't have that meaning, they are merely
# shorthand for two otherwise separate rules. If we have an action
# that in fact generates two or more files, we must choose one of them
# as primary and show it as the action's output, then make all of the
# other output files dependent on the primary, like this. Furthermore,
# the "touch" action is essential, because it ensures that gram.h is
# marked as newer than (or at least no older than) gram.c. Without that,
# make is likely to try to rebuild gram.h in subsequent runs, which causes
# failures in VPATH builds from tarballs.
gram.h: gram.c
touch $@
gram.c: BISONFLAGS += -d
gram.c: BISON_CHECK_CMD = $(PERL) $(srcdir)/check_keywords.pl $< $(top_srcdir)/src/include/parser/kwlist.h
-----
This is indeed kind of confusing, because there's no explicit
reference to gram.y here --- the last two lines just tweak
the behavior of the default .y to .c rule.
Maybe we should adjust the comment in Unicode/Makefile, but
I'm not sure what would be a better reference.
regards, tom lane
On Mon, 25 Sep 2023 at 11:17, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Japin Li <japinli@hotmail.com> writes: >> I find src/backend/utils/mb/Unicode/Makefile has the following comments: > >>> # Note that while each script call produces two output files, to be >>> # parallel-make safe we need to split this into two rules. (See for >>> # example gram.y for more explanation.) > >> I could not find the explanation in gram.y easily. Would someone point >> it out for me? Thanks in advance! > > It's referring to this bit in src/backend/parser/Makefile: > > ----- > # There is no correct way to write a rule that generates two files. > # Rules with two targets don't have that meaning, they are merely > # shorthand for two otherwise separate rules. If we have an action > # that in fact generates two or more files, we must choose one of them > # as primary and show it as the action's output, then make all of the > # other output files dependent on the primary, like this. Furthermore, > # the "touch" action is essential, because it ensures that gram.h is > # marked as newer than (or at least no older than) gram.c. Without that, > # make is likely to try to rebuild gram.h in subsequent runs, which causes > # failures in VPATH builds from tarballs. > > gram.h: gram.c > touch $@ > > gram.c: BISONFLAGS += -d > gram.c: BISON_CHECK_CMD = $(PERL) $(srcdir)/check_keywords.pl $< $(top_srcdir)/src/include/parser/kwlist.h > ----- > > This is indeed kind of confusing, because there's no explicit > reference to gram.y here --- the last two lines just tweak > the behavior of the default .y to .c rule. > > Maybe we should adjust the comment in Unicode/Makefile, but > I'm not sure what would be a better reference. > > regards, tom lane Thank you! Maybe be reference src/backend/parser/Makefile is better than current. How about "See gram.h target's comment in src/backend/parser/Makefile" or just "See src/backend/parser/Makefile"? -- Regrads, Japin Li
> On 25 Sep 2023, at 05:34, Japin Li <japinli@hotmail.com> wrote: > Maybe be reference src/backend/parser/Makefile is better than current. > > How about "See gram.h target's comment in src/backend/parser/Makefile" > or just "See src/backend/parser/Makefile"? The latter seems more stable, if the Makefile is ever restructured it's almost guaranteed that this comment will be missed with the location info becoming stale. -- Daniel Gustafsson
Daniel Gustafsson <daniel@yesql.se> writes:
> On 25 Sep 2023, at 05:34, Japin Li <japinli@hotmail.com> wrote:
>> How about "See gram.h target's comment in src/backend/parser/Makefile"
>> or just "See src/backend/parser/Makefile"?
> The latter seems more stable, if the Makefile is ever restructured it's almost
> guaranteed that this comment will be missed with the location info becoming
> stale.
I did it like this:
# Note that while each script call produces two output files, to be
-# parallel-make safe we need to split this into two rules. (See for
-# example gram.y for more explanation.)
+# parallel-make safe we need to split this into two rules. (See notes
+# in src/backend/parser/Makefile about rules with multiple outputs.)
#
There are a whole lot of other cross-references to that same comment,
and they all look like
# See notes in src/backend/parser/Makefile about the following two rules
I considered modifying all of those as well, but decided it wasn't
really worth the trouble. The Makefiles' days are numbered I think.
regards, tom lane