config: improve documentation

2 files changed, 36 insertions, 3 deletions

diff --git a/functions/init.sh b/functions/init.sh
index 1fc653224..4eb6e7299 100755
--- a/functions/init.sh
+++ b/functions/init.sh
@@ -30,6 +30,26 @@ Init_config_data ()
 	Set_config_defaults
 }
 
+# "Auto" script redirection.
+#
+# As a matter of convenience users can have a set of saved commandline options
+# which will be automatically included in every execution of live-build. How
+# this works is that the save file is itself a shell script saved in the config
+# directory (one per top-level live-build command in fact). When `lb config`,
+# `lb build` or `lb clean` is run, these scripts, if they see that an "auto"
+# file exists in the config, they run that file, passing along any user
+# arguments, and terminate once that ends. The "auto" script simply re-executes
+# the same command (e.g. `lb config`), only with a first param of "noauto",
+# used to stop an infinite loop of further redirection, then a fixed saved set
+# of command line options, as saved in the file by the user, then any
+# additional command line arguments passed into the script. This is simply a
+# means of injecting a saved set of command line options into the execution of
+# live-build.
+#
+# As for this function, it is a simple helper, used by the top-level commands
+# to perform the redirection if the relevant "auto" file exists. It should only
+# be called if the calling command script was not run with "noauto" as the
+# first argument (the purpose of which was just described).
 Maybe_auto_redirect ()
 {
 	local TYPE="${1}"; shift
diff --git a/scripts/build/config b/scripts/build/config
index b30223457..d2c747b2c 100755
--- a/scripts/build/config
+++ b/scripts/build/config
@@ -830,8 +830,12 @@ Local_arguments ()
 	done
 }
 
+# Processing args such that we have a value for --config if given
+# We can thus momentarily print an appropriate message that we are ignoring it under certain circumstances
 Local_arguments "${@}"
 
+# Ignoring --config if CWD is already a git repo
+# Only print warning from direct execution, not when run from auto script redirection, to avoid repetition
 if [ -e .git ] && [ -n "${_CONFIG}" ]
 then
 	if [ "${1}" != "noauto" ]
@@ -842,6 +846,8 @@ then
 	_CONFIG=""
 fi
 
+# Ignoring --config if CWD already has a config
+# Only print warning from direct execution, not when run from auto script redirection, to avoid repetition
 if [ -e .build/config ] && [ -n "${_CONFIG}" ]
 then
 	if [ "${1}" != "noauto" ]
@@ -852,6 +858,7 @@ then
 	_CONFIG=""
 fi
 
+# Otherwise, handling --config request, copying specified config
 if [ -n "${_CONFIG}" ]
 then
 	if [ -e "${_CONFIG}" ] || [ -e "/usr/share/live/images/${_CONFIG}" ]
@@ -887,14 +894,16 @@ then
 	fi
 fi
 
-# Redirecting to auto script if required
+# "Auto" script redirection.
+# Re-run via "auto" script to pick up saved command-line arguments, if not already redirected.
+# See the documentation of the Maybe_auto_redirect function for more details.
 if [ "${1}" = "noauto" ]; then
 	shift
 else
 	Maybe_auto_redirect config
 fi
 
-# Reading system configuration
+# Reading config defaults configured at system level
 if ls /etc/live/build.conf > /dev/null 2>&1 || ls /etc/live/build/* > /dev/null 2>&1
 then
 	if In_list "--ignore-system-defaults" "${@}"
@@ -907,11 +916,13 @@ then
 	fi
 fi
 
-# Reading existing configuration
+# Reading existing saved configuration
 Read_conffiles $(Common_config_files)
 
+# Processing arguments again to overwrite just-read previously saved settings as necessary
 Local_arguments "${@}"
 
+# Loading user specified saved config file if specified
 if [ -n "${_CONFFILE}" ]
 then
 	Read_conffiles "${_CONFFILE}"
@@ -921,6 +932,8 @@ fi
 Set_config_defaults
 Check_config_defaults
 
+# Creating or updating saved config
+
 if [ ! -e config ]
 then
 	Echo_message "Creating config tree for a ${LB_MODE}/${LB_DISTRIBUTION_BINARY}/${LB_ARCHITECTURES} system"