[setup_target] started inline documentation...

1 files changed, 70 insertions, 4 deletions

diff --git a/remote/setup_target b/remote/setup_target
index 46c1d978..4ea1cbc2 100755
--- a/remote/setup_target
+++ b/remote/setup_target
@@ -1,5 +1,56 @@
 #!/bin/bash
-
+# -----------------------------------------------------------------------------
+# 
+# Copyright (c) 2011 - OpenSLX GmbH
+#
+# This program is free software distributed under the GPL version 2.
+# See http://openslx.org/COPYING
+#
+# If you have any feedback please consult http://openslx.org/feedback and
+# send your suggestions, praise, or complaints to feedback@openslx.org
+#
+# General information about OpenSLX can be found at http://openslx.org/
+# ----------------------------------------------------------------------------- 
+#
+#	This file contains the functions needed to setup a target.
+#	The main function is 'generate_target' which will go over all 
+#	activated modules (symlinks found under remote/targets/<target>)
+#	and run the module-specific 'fetch_source', 'build' and 'post_copy'
+#	functions of the modules.
+#
+#	The functions defined here are module-independent, meaning they
+#	can process any module, as long as following requirements are met:
+#
+#		- Modules need to have a build-script and a config file,
+#		  i.e. remote/module/kernel/kernel.build 
+#		  and  remote/module/kernel/kernel.conf
+#		  as these will be read by 'process_module'.
+#		
+#		- Modules need to generate a 'build'-directory in their
+#		  own sub-directory (i.e. remote/modules/sshd/build/
+#		  as 'copy_files_with_deps' will look for the files in
+#		  that directory ONLY.
+#
+#		- Several information have to be set in the config file of
+#		  a module:
+#		    * REQUIRED_BINARIES - list of binaries
+#		    * REQUIRED_FILES - list of regular files
+#		    * REQUIRED_DIRECTORIES - list of directories
+#		    * REQUIRED_SYSTEM_FILES - files to be copied directly from the system
+#		    * REQUIRED_INSTALLED_PACKAGES - list of packages needed at build-time
+#		    * REQUIRED_CONTENT_PACKAGES - list of packages where the contents are to be copied
+#		    * (optional variables needed by the module-build-script)
+#
+#		  NOTE: REQUIRED_BINARIES, REQUIRED_FILES, REQUIRED_FILES will be ONLY looked
+#		        for in the module's own build directory!
+#
+#	Optionally, a module can have a static data directory under
+#	remote/modules/<module>/data which will be copied as is to the target build directory.
+#
+#	Moreover modules do not need to specify the dynamic dependencies of given binaries
+#	as these will be determined automaticly by the helper function 'get_dynamic_dependencies' 
+# -----------------------------------------------------------------------------
+#
 MODE_DIR="${ROOT_DIR}/remote"
 MODULES_DIR="${MODE_DIR}/modules"
 
@@ -10,6 +61,9 @@ initial_checks () {
 	:
 }
 
+#
+# generic function to read the config file of the current $MODULE
+#
 read_config () {
 	# unset previous variables from other config files
 	for VARNAME in ${!REQUIRED_*}; do
@@ -18,8 +72,9 @@ read_config () {
 
 	local MODULE_CONFIG="${MODULE_DIR}/${MODULE}.conf"
 
-	# otherwise, use the generic one
+	# sanity checks
 	[ ! -e "${MODULE_CONFIG}" ] && perror "Config for '$MODULE' not found."
+	# source the config file
 	. "${MODULE_CONFIG}" || perror "Sourcing '${MODULE_CONFIG}' failed."
 	if [ -e "${MODULE_CONFIG}.${PACKET_MANAGER}" ]; then
 		# a specific tool.conf seems to exist, use it to override certain vars
@@ -27,6 +82,9 @@ read_config () {
 	fi
 }
 
+#
+# generic function to read the build script of the current $MODULE
+#
 read_build () {
 	local BUILD_SCRIPT="${MODULE_DIR}/${MODULE}.build"
 
@@ -35,7 +93,9 @@ read_build () {
 	. "${BUILD_SCRIPT}" || perror "Sourcing '${BUILD_SCRIPT}' failed."
 }
 
-
+#
+# main function which copies all files, directories, binaries and external libraries to TARGET_BUILD_DIR
+#
 copy_files_with_deps () {
 
 	[ ! -d "$MODULE_BUILD_DIR" ] && pinfo "No build directory found, skipping dependency copying" && return 0
@@ -123,10 +183,16 @@ copy_files_with_deps () {
 	
 }
 
+#
+#
+# main public function. Requires the TARGET to be given as argument.
+# this will simply go over all the modules as found in the remote/target/<TARGET>
+# and run following functions:
+# 
+#
 generate_target() {
 
 	initial_checks
-	#copy_kernel
 	
 	TARGET=$1 && shift
 	TARGET_DIR="${MODE_DIR}/targets/${TARGET}"