Initialize: including *.conf files from the preparation phase

Until now, when some configuration files were generated in the preparation
phase, only the auto-generated (in the preparation phase) Makefiles (with
the suffix '*.mk') were always included in 'initialize.mk'. As a
consequence, if there were any configuration files (with suffix '*.conf'),
they would not be automatically added, and it was necessary to manually
include them.

Since auto-generated configuration files are also one common output of the
preparation phase of a project, it is better to include them automatically.

With this commit, the '*.conf' configuration files generated in the
preparation phase are added by 'initialize.mk' automatically (if
necessary).

In the process, the comments in the final target of
'reproduce/analysis/make/prepare.mk' were updated to be more clear.

2 files changed, 31 insertions, 17 deletions

diff --git a/reproduce/analysis/make/initialize.mk b/reproduce/analysis/make/initialize.mk
index 753c70a..eb5f2ff 100644
--- a/reproduce/analysis/make/initialize.mk
+++ b/reproduce/analysis/make/initialize.mk
@@ -62,13 +62,17 @@ pconfdir    = reproduce/analysis/config
 # should be created, and in the 'make' phase, its contents should be
 # loaded.
 #
-# If you don't need any preparation, please simply comment these lines.
+# If your project doesn't need any preparation, you can ignore this.
 ifeq (x$(project-phase),xprepare)
 $(prepdir):; mkdir $@
 else
 include $(bsdir)/preparation-done.mk
 ifeq (x$(include-prepare-results),xyes)
-include $(prepdir)/*.mk
+# The '-' behind the include is The '-' is used for adding the files only
+# if it is possible (they exist). This is necessary because sometimes the
+# user will have only '*.conf' or '*.mk' files. So, if the '-' is not used,
+# Make will complain about not finding these files.
+-include $(prepdir)/*.mk $(prepdir)/*.conf
 endif
 endif
 
diff --git a/reproduce/analysis/make/prepare.mk b/reproduce/analysis/make/prepare.mk
index 92b57b6..ebc2b4d 100644
--- a/reproduce/analysis/make/prepare.mk
+++ b/reproduce/analysis/make/prepare.mk
@@ -28,24 +28,34 @@ prepare-dep = $(filter-out prepare, $(makesrc))
 $(bsdir)/preparation-done.mk: \
                 $(foreach s, $(prepare-dep), $(mtexdir)/$(s).tex)
 
-#	If you need to add preparations define targets above to do the
-#	preparations, then set the value below to 'yes'. Recall that just
-#	like './project make', before loading this file, './project
-#	prepare' loads loads 'initialize.mk' and 'download.mk', so you can
-#	safely assume everything that is defined there in the preparation
-#	phase also.
+#	If you need to add preparations (mainly automatically generated
+#	configuration files or Makefiles to simplify the './project make'
+#	phase) take the following step:
+#
+#	   1. Add prerequisites to this target ('preparation-done.mk'). Try
+#	      to avoid any kind of analysis in this (preparation) phase!
+#	      Preparation should ideally only involve automatic creation of
+#	      configuration files or Makefile that will be loaded into the
+#	      analysis phase (from 'top-make.mk').
+#
+#	   2. Set the value of 'include-prepare-results' (defined below) to
+#	      'yes'. If it is kept to the default 'no', then your
+#	      prepartion outputs will not be automatically
+#	      generated. Recall that just like 'top-make.mk',
+#	      'top-prepare.mk' also loads 'initialize.mk' before everything
+#	      else. So you can safely assume everything that is defined in
+#	      'initialize.mk' to be available in the preparation phase
+#	      also.
 #
 #	TIP: the targets can actually be automatically generated Makefiles
 #	that are used by './project make'. They can include variables, or
 #	automatically generated rules. Just make sure that those Makefiles
-#	aren't written in the source directory. Even though they are
-#	Makefiles, they are automatically built, so they don't belong in
-#	the source. '$(prepdir)' has been defined for this purpose (see
+#	aren't written in the source directory (only hand-written files
+#	should be in your source). Even though they are Makefiles, they are
+#	automatically built, so they don't belong in the
+#	source. '$(prepdir)' has been defined for this purpose (see
 #	'initialize.mk'), we recommend that you put all automatically
-#	generated Makefiles under this directory. In the 'make' phase,
-#	'initialize.mk' will automatically load all the '*.mk' files. If
-#	you need to load your generated configuration-makefiles before
-#	automatically generated Makefiles containing rules, you can use
-#	some naming convension like 'conf-*.mk' and 'rule-*.mk', or you can
-#	put them in subdirectories.
+#	generated configuration files or Makefiles under this directory. In
+#	the 'make' phase, 'initialize.mk' will automatically load all the
+#	'*.mk' files there.
 	@echo "include-prepare-results = no" > $@