build: add a bunch of comments to makefile.py

... to (maybe?) make understandable what it's doing.

Signed-off-by: David Lamparter <equinox@opensourcerouting.org>

1 files changed, 16 insertions, 0 deletions

diff --git a/python/makefile.py b/python/makefile.py
index 64d02bbe5..dfc0ee549 100644
--- a/python/makefile.py
+++ b/python/makefile.py
@@ -63,6 +63,9 @@ if args.dev_build:
             )
             sys.exit(1)
 
+# this additional-dependency rule is stuck onto all compile targets that
+# compile a file which uses clippy-generated input, so it has a dependency to
+# make that first.
 clippydep = Template(
     """
 ${clippybase}.$$(OBJEXT): ${clippybase}_clippy.c
@@ -70,6 +73,8 @@ ${clippybase}.lo: ${clippybase}_clippy.c
 ${clippybase}_clippy.c: $$(CLIPPY_DEPS)"""
 )
 
+# this one is used when one .c file is built multiple times with different
+# CFLAGS
 clippyauxdep = Template(
     """# clippy{
 # auxiliary clippy target
@@ -88,6 +93,7 @@ while lines:
     if line.startswith(autoderp):
         line = line[len(autoderp) :]
 
+    # allow rerunning on already-clippified Makefile
     if line == "# clippy{":
         while lines:
             line = lines.pop(0)
@@ -115,36 +121,46 @@ while lines:
 
     filename = os.path.basename(target)
     if '-' in filename:
+        # dashes in output filename = building same .c with different CFLAGS
         am_name, _ = filename.split('-', 1)
         am_name = os.path.join(os.path.dirname(target), am_name)
         am_name = am_name.replace('/', '_')
         extraflags = " $(%s_CFLAGS)" % (am_name,)
     else:
+        # this path isn't really triggered because automake is using a generic
+        # .c => .o rule unless CFLAGS are customized for a target
         extraflags = ""
 
     if target.endswith(".lo") or target.endswith(".o"):
         if not dep.endswith(".h"):
+            # LLVM bitcode targets for analysis tools
             bcdeps.append("%s.bc: %s" % (target, target))
             bcdeps.append("\t$(AM_V_LLVM_BC)$(COMPILE)%s -emit-llvm -c -o $@ %s" % (extraflags, dep))
     if m.group(2) in clippy_scan:
+        # again - this is only hit for targets with custom CFLAGS, because
+        # automake uses a generic .c -> .o rule for standard CFLAGS
         out_lines.append(
             clippyauxdep.substitute(target=m.group(1), clippybase=m.group(2)[:-2])
         )
 
     out_lines.append(line)
 
+# now, cover all the .c files that don't have special build rules
 out_lines.append("# clippy{\n# main clippy targets")
 for clippy_file in clippy_scan:
     out_lines.append(clippydep.substitute(clippybase=clippy_file[:-2]))
 
+# combine daemon .xref files into frr.xref
 out_lines.append("")
 out_lines.append("xrefs = %s" % (" ".join(["%s.xref" % target for target in xref_targets])))
 out_lines.append("frr.xref: $(xrefs)")
 out_lines.append("")
 
+# analog but slower way to get the same frr.xref
 #frr.xref: $(bin_PROGRAMS) $(sbin_PROGRAMS) $(lib_LTLIBRARIES) $(module_LTLIBRARIES)
 #	$(AM_V_XRELFO) $(CLIPPY) $(top_srcdir)/python/xrelfo.py -o $@ $^
 
+# LLVM bitcode link targets creating a .bc file for whole daemon or lib
 out_lines.append("")
 out_lines.extend(bcdeps)
 out_lines.append("")