* lisp/Makefile.in (compile-one-process): Rename from "recompile".

lisp/ChangeLog

 2012-07-06  Glenn Morris  <rgm@gnu.org>
 
+	* Makefile.in (compile-one-process): Rename from "recompile".
+
 	* Makefile.in (bzr-update): "compile" is the same as "recompile
 	autoloads", but parallelizable, so use that instead.
 

lisp/Makefile.in

@@ -133,8 +133,6 @@ setwins_for_subdirs=subdirs=`find . -type d -print`; \
 	   esac; \
         done
 
-# `compile-main' tends to be slower than `recompile' but can be parallelized
-# with "make -j" and results in more deterministic compilation warnings.
 # cus-load and finder-inf are not explicitly requested by anything, so
 # we add them here to make sure they get built.
 all: compile-main $(lisp)/cus-load.el $(lisp)/finder-inf.el
@@ -317,19 +315,22 @@ backup-compiled-files:
 
 compile-after-backup: backup-compiled-files compile-always
 
-# Recompile all Lisp files which are newer than their .elc files and compile
-# new ones.
-# This has the same effect as compile-main.  recompile has some advantages:
-# i) It is faster (on a single processor), since it only has to start
-# Emacs once.  It was 33% faster on a test with a random 10% of the .el
-# files needing recompilation.
-# ii) The explicit cc-mode dependency.
-# recompile's disadvantages are:
-# i) Not parallelizable.
-# ii) Compiling multiple files in the same instance of Emacs is wrong,
-# since the environment of later files is affected by definitions in
-# earlier ones.
-recompile: doit $(LOADDEFS) compile-first $(lisp)/progmodes/cc-mode.elc
+# This does the same job as the "compile" rule, but in a different way.
+# Rather than spawning a separate Emacs instance to compile each file,
+# it uses the same Emacs instance to compile everything.
+# This is faster on a single core, since it avoids the overhead of
+# starting Emacs many times (it was 33% faster on a test with a
+# random 10% of the .el files needing recompilation).
+# Unlike compile, this is not parallelizable; so if you have more than
+# one core, compile will be (much) faster.
+# This rule also produces less accurate compilation warnings.
+# The environment of later files is affected by definitions in
+# earlier ones, so it does not produce some warnings that it should.
+# It can also produces spurious warnings about "invalid byte code" if
+# files that use byte-compile-dynamic are updated.
+# There is no reason to use this rule unless you only have a single
+# core and CPU time is an issue.
+compile-one-process: doit $(LOADDEFS) compile-first $(lisp)/progmodes/cc-mode.elc
 	$(emacs) $(BYTE_COMPILE_FLAGS) \
 	    --eval "(batch-byte-recompile-directory 0)" $(lisp)