Enhance the make fragments:

- comment the different parts
- re-order the code so that it is homogeneous amogst fragments
- eye-candy in some existing comments

 /trunk/tools/tools.mk     |   17    15     2     0 +++++++++++++++--
 /trunk/steps.mk           |   38    26    12     0 ++++++++++++++++++++++++++------------
 /trunk/samples/samples.mk |   41    28    13     0 ++++++++++++++++++++++++++++-------------
 /trunk/config/config.mk   |    2     1     1     0 +-
 4 files changed, 70 insertions(+), 28 deletions(-)

config/config.mk

@@ -3,7 +3,7 @@
 # These targets are used from top-level makefile
 
 #-----------------------------------------------------------
-# List all config files, source and generated
+# List all config files, wether sourced or generated
 
 # The top-level config file to be used be configurators
 KCONFIG_TOP = config/config.in

samples/samples.mk

@@ -1,11 +1,14 @@
 # Makefile to manage samples
 
+# ----------------------------------------------------------
 # Build the list of available samples
 CT_TOP_SAMPLES := $(patsubst $(CT_TOP_DIR)/samples/%/crosstool.config,%,$(wildcard $(CT_TOP_DIR)/samples/*/crosstool.config))
 CT_LIB_SAMPLES := $(filter-out $(CT_TOP_SAMPLES),$(patsubst $(CT_LIB_DIR)/samples/%/crosstool.config,%,$(wildcard $(CT_LIB_DIR)/samples/*/crosstool.config)))
-
 CT_SAMPLES := $(sort $(CT_TOP_SAMPLES) $(CT_LIB_SAMPLES))
 
+# ----------------------------------------------------------
+# This part deals with the samples help entries
+
 help-config::
 	@echo  '  saveconfig         - Save current config as a preconfigured target'
 
@@ -23,13 +26,35 @@ help-build::
 help-distrib::
 	@echo  '  wiki-samples       - Print a DokuWiki table of samples'
 
+# ----------------------------------------------------------
+# This part deals with printing samples information
+
+# Prints the details of a sample
+PHONY += $(patsubst %,show-%,$(CT_SAMPLES))
 $(patsubst %,show-%,$(CT_SAMPLES)):
 	@$(CT_LIB_DIR)/scripts/showSamples.sh -v $(patsubst show-%,%,$(@))
 
+# print the list of all available samples
 PHONY += list-samples
 list-samples: .FORCE
 	@echo $(CT_SAMPLES) |sed -r -e 's/ /\n/g;' |sort
 
+wiki-samples:
+	$(SILENT)$(CT_LIB_DIR)/scripts/showSamples.sh -w $(CT_SAMPLES)
+
+# ----------------------------------------------------------
+# This part deals with saving/restoring samples
+
+# Save a sample
+saveconfig:
+	$(SILENT)$(CT_LIB_DIR)/scripts/saveSample.sh
+
+# The 'sample_dir' function prints the directory in which the sample is,
+# searching first in local samples, then in global samples
+define sample_dir
+$$( [ -d $(CT_TOP_DIR)/samples/$(1) ] && echo "$(CT_TOP_DIR)/samples/$(1)" || echo "$(CT_LIB_DIR)/samples/$(1)")
+endef
+
 # How we do recall one sample
 PHONY += $(CT_SAMPLES)
 $(CT_SAMPLES):
@@ -61,13 +86,9 @@ $(CT_SAMPLES):
 	@echo
 	@echo  'Now configured for "$@"'
 
-# The 'sample_dir' function prints the directory in which the sample is,
+# ----------------------------------------------------------
-# searching first in local samples, then in global samples
-define sample_dir
-$$( [ -d $(CT_TOP_DIR)/samples/$(1) ] && echo "$(CT_TOP_DIR)/samples/$(1)" || echo "$(CT_LIB_DIR)/samples/$(1)")
-endef
-
 # And now for building all samples one after the other
+
 PHONY += regtest regtest_local regtest_global
 regtest: regtest-local regtest-global
 
@@ -107,9 +128,3 @@ $(patsubst %,regtest_%,$(CT_SAMPLES)):
 	 echo -e "\rCleaning sample \"$${samp}\""                                                       ;   \
 	 $(CT_NG) distclean                                                                             ;   \
 	 echo -e "\r"
-
-saveconfig:
-	$(SILENT)$(CT_LIB_DIR)/scripts/saveSample.sh
-
-wiki-samples:
-	$(SILENT)$(CT_LIB_DIR)/scripts/showSamples.sh -w $(CT_SAMPLES)

steps.mk

@@ -1,6 +1,17 @@
 # Makefile for each steps
 # Copyright 2006 Yann E. MORIN <yann.morin.1998@anciens.enib.fr>
 
+# ----------------------------------------------------------
+# This is the steps help entry
+
+help-build::
+	@echo  '  list-steps         - List all build steps'
+
+# ----------------------------------------------------------
+# The steps list
+
+# Please keep the last line with a '\' and keep the folowing empy line:
+# it helps when diffing and merging.
 CT_STEPS := libc_check_config   \
             kernel_headers      \
             gmp                 \
@@ -19,8 +30,23 @@ CT_STEPS := libc_check_config   \
             tools               \
             debug               \
 
+# Make the list available to sub-processes (scripts/crosstool.sh needs it)
 export CT_STEPS
 
+# Print the steps list
+PHONY += list-steps
+list-steps:
+	@echo  'Available build steps, in order:'
+	@for step in $(CT_STEPS); do    \
+	     echo "  - $${step}";       \
+	 done
+	@echo  'Use "<step>" as action to execute only that step.'
+	@echo  'Use "+<step>" as action to execute up to that step.'
+	@echo  'Use "<step>+" as action to execute from that step onward.'
+
+# ----------------------------------------------------------
+# This part deals with executing steps
+
 $(CT_STEPS):
 	$(SILENT)$(MAKE) -rf $(CT_NG) RESTART=$@ STOP=$@ build
 
@@ -29,15 +55,3 @@ $(patsubst %,+%,$(CT_STEPS)):
 
 $(patsubst %,%+,$(CT_STEPS)):
 	$(SILENT)$(MAKE) -rf $(CT_NG) RESTART=$(patsubst %+,%,$@) build
-
-help-build::
-	@echo  '  list-steps         - List all build steps'
-
-list-steps:
-	@echo  'Available build steps, in order:'
-	@for step in $(CT_STEPS); do    \
-	     echo "  - $${step}";       \
-	 done
-	@echo  'Use "<step>" as action to execute only that step.'
-	@echo  'Use "+<step>" as action to execute up to that step.'
-	@echo  'Use "<step>+" as action to execute from that step onward.'

tools/tools.mk

@@ -5,6 +5,16 @@
 # scripts for later inclusion mainline. If CT_LIB_DIR != CT_TOP_DIR, then those
 # scripts are downloaded only for use in CT_TOP_DIR.
 
+# ----------------------------------------------------------
+# The tools help entry
+
+help-distrib::
+	@echo  '  updatetools        - Update the config tools'
+
+# ----------------------------------------------------------
+# Where to get tools from, and where to store them into
+# The tools are: config.guess and config.sub
+
 CONFIG_SUB_SRC="http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.sub;hb=HEAD"
 CONFIG_SUB_DEST="$(CT_TOP_DIR)/tools/config.sub"
 CONFIG_GUESS_SRC="http://git.savannah.gnu.org/gitweb/?p=config.git;a=blob_plain;f=config.guess;hb=HEAD"
@@ -16,6 +26,9 @@ $(CT_TOP_DIR)/tools:
 PHONY += updatetools
 updatetools: $(CT_TOP_DIR)/tools $(CONFIG_SUB_DEST) $(CONFIG_GUESS_DEST)
 
+# ----------------------------------------------------------
+# How to retrieve the tools
+
 $(CONFIG_SUB_DEST):
 	$(SILENT)wget $(CONFIG_SUB_SRC) -O $@
 	$(SILENT)chmod u+rwx,go+rx-w $@
@@ -24,8 +37,8 @@ $(CONFIG_GUESS_DEST):
 	$(SILENT)wget $(CONFIG_GUESS_SRC) -O $@
 	$(SILENT)chmod u+rwx,go+rx-w $@
 
-help-distrib::
+# ----------------------------------------------------------
-	@echo  '  updatetools        - Update the config tools'
+# Clean up the mess
 
 distclean::
 	@$(ECHO) "  CLEAN tools"