; * lisp/Makefile.in: Comments about loaddefs.

lisp/Makefile.in

@@ -173,31 +173,46 @@ $(lisp)/finder-inf.el:
 	  --eval '(setq generated-finder-keywords-file (unmsys--file-name "$(srcdir)/finder-inf.el"))' \
 	  -f finder-compile-keywords-make-dist ${SUBDIRS_FINDER}
 
-# Use expand-file-name rather than $abs_scrdir so that Emacs does not
-# get confused when it compares file-names for equality.
+## Comments on loaddefs generation:
+
+# loaddefs depends on gen-lisp for two reasons:
+# 1) In ../src, the emacs target depends on loaddefs but not on eg leim-list.
+# So having leim as a dependency of loaddefs (via gen-lisp) ensures leim-list
+# gets created before the final emacs is dumped.  Having leim
+# dependencies in ../src as well would create a parallel race condition.
 #
-# Note that we set no-update-autoloads in _generated_ leim files.
-# If you want to allow autoloads in such files, remove that,
-# and make this depend on leim.
-# Actually this should depend on leim anyway, since no-update-autoloads
-# files are still recorded in loaddefs.  So we should ensure
-# that all input files are generated before we create loaddefs.
-# Otherwise making loaddefs again will change the output.
-#
-# In fact, now we rely on this target to create leim-list.
-# In src, emacs depends directly on loaddefs.el (not leim-list).
-#
-# Write to a temporary file in case we're doing a parallel build and a
-# CANNOT_DUMP-mode Emacs needs to read loaddefs at startup.
+# 2) Files that are marked no-update-autoloads still get recorded in loaddefs.
+# So those files should be generated before we make autoloads, if we
+# don't want a successive make autoloads to change the output file.
+# Said changes are trivial (only comments in the "files without autoloads"
+# section), but still can be annoying.  Of course, if generated lisp files
+# do contain autoloads, it is essential they be built before make autoloads.
+# (Also, if a generated file is not written atomically, it is possible that
+# in a parallel build, make autoloads could read a partial version of it.)
 #
+# We'd really like to add "make -C ../admin/unidata all" to gen-lisp
+# because of 2) above, but it causes a race condition in parallel
+# builds because ../src also runs that rule.  Given the limitations of
+# recursive make, the only way to fix that would be to remove unidata
+# from ../src rules, but that doesn't seem possible due to the various
+# non-trivial dependencies.
+
 # We make $(lisp)/loaddefs.el a dependency of .PHONY to cause Make to
 # ignore its time stamp.  That's because the real dependencies of
 # loaddefs.el aren't known to Make, they are implemented in
 # batch-update-autoloads, which only updates the autoloads whose
-# sources have changed.  We start by copying an existing loaddefs.el
-# to loaddefs.tmp to avoid regenerating the entire file anew, which is
-# slow; starting from an almost-correct content will enable the "only
-# update where necessary" feature of batch-update-autoloads.
+# sources have changed.
+
+# Write to a temporary file in case we're doing a parallel build and a
+# CANNOT_DUMP-mode Emacs needs to read loaddefs at startup.  We start
+# by copying an existing loaddefs.el to loaddefs.tmp to avoid regenerating
+# the entire file anew, which is slow; starting from an almost-correct
+# content will enable the "only update where necessary" feature of
+# batch-update-autoloads.
+
+# Use expand-file-name rather than $abs_scrdir so that Emacs does not
+# get confused when it compares file-names for equality.
+
 autoloads .PHONY: $(lisp)/loaddefs.el
 $(lisp)/loaddefs.el: gen-lisp $(LOADDEFS)
 	@echo Directories for loaddefs: ${SUBDIRS_ALMOST}
@@ -352,6 +367,8 @@ compile-clean:
 
 .PHONY: gen-lisp leim semantic
 
+## make -C ../admin/unidata all should be here, but that would race
+## with ../src.  See comments above for loaddefs.
 gen-lisp: leim semantic
 
 leim: