--- rock-old/scripts/Build-All	Wed Oct 10 11:27:58 2001
+++ rock-new/scripts/Build-All	Sun Oct 14 12:09:16 2001
@@ -1,4 +1,20 @@
 #!/bin/sh
+#
+#   Run this command from the ROCK directory as ./scripts/Build-All [ options ]
+#
+#   It compiles/builds all the packages and stores them tar balls suitable
+#   for distribution. There are options for the used storage (NFS-Mount, 
+#   COPY, LINK)
+#   
+#   This script is the ROCK work-horse. It builds in a chroot environment
+#   (stage 2..E) and goes through (a maximum of) 6 build stages:
+#
+#   Stage 1: Create build environment (compilers etc.)
+#   Stage 2: Build user interaction (bash, raid etc. - rescue distro)
+#   Stage 3: Build support tools
+#   Stage 4: Build extra's (documentation)
+#   Stage 5: Complete rebuild (optional)
+#   Stage E: Build stable extensions (optional)
 
 . ./scripts/parse-config
 
@@ -27,6 +43,7 @@
 start="`date '+%D %T'`"
 
 finish() {
+    # Wrap up and warn user
 	umount -v $base/dist/dev $base/dist/proc $base/dist/rock-orig
 	date "+%n ** Finished ($start - %D %T) **%n"
 	stat=${1/0/0 (Ok)} ; stat=${stat/1/1 (Error)}
@@ -37,17 +54,20 @@
 }
 
 warnbeep() {
+    # Give irritating beeps to wake up user
 	echo -en \\007 ; sleep 1 ; echo -en \\007 ; sleep 1
 	echo -en \\007 ; sleep 1 ; echo -en \\007 ; sleep 5
 }
 
 {
+    # Trap all child errors (catch exeption, see end of script)
 	trap 'exit 1' INT
 	exec < /dev/null
 
 	echo -e "\n ** Testing **\n"
 	
 	if [ $1 != COPY -a $1 != LINK ] ; then
+	    # Test mount nfs tree
 		echo -n "NFS-Mount: " ; set -e
 		mkdir -p src/$$.mnt ; mount -t nfs $1 src/$$.mnt ; echo -n "mount-ok "
 		cmp base-archive/INDEX src/$$.mnt/base-archive/INDEX ; echo -n "data-ok "
@@ -55,6 +75,7 @@
 	fi
 	
 	echo -n "Free Disk Space: "
+	# Check for free disk space and warn if there is not enough
 	x=`df . | tail -1 | tr -s ' ' | cut -f4 -d' '` ; x=`expr $x / 1024`
 	if [ $x -gt 2560 ] ; then echo "$x MB -> ok." ; else
 	echo "$x MB -> WARNING: may be not enough (<2560)" ; warnbeep ; fi
@@ -63,7 +84,8 @@
 	./scripts/Cleanup
 
 	if [ -f rock-$arch-$rockver/base-pkgs/00-dirtree.tar.bz2 ] ; then
-
+        # Tests if binary packages already exists (won´t overwrite).
+		# Remove above package for a full rebuild
 		echo -e "\n **  WARNING  **\n"
 		echo -e "Found packages in rock-$arch-$rockver/ -> skipping" \
 		     "building of packages!\n"
@@ -77,7 +99,7 @@
 	    if [ $crossnative = native ] ; then
 		
 		echo -e "\n ** Stages 2-5 and E in the chroot tree **\n"
-		#
+		# Set up chroot environment
 		mkdir -p dist/rock-linux dist/rock-orig
 		cp -v Config dist/rock-linux/Config
 		[ -f /etc/localtime ] &&
@@ -85,8 +107,10 @@
 		mount -vt devfs none $base/dist/dev
 		mount -vt proc  none $base/dist/proc
 		if [ $1 != COPY -a $1 != LINK ] ; then
+		    # Mount storage
 			mount -vt nfs -o ro $1 $base/dist/rock-orig
 		else
+		    # Copy or link all files so they are visible
 			echo 'Copy data to dist/rock-orig/ ...'
 			for x in Documentation base-archive arch-conf \
 			         misc opt-archive base-config scripts     \
@@ -100,7 +124,8 @@
 			    fi
 			done
 		fi
-		#
+		# Create script that runs in chroot and goes through 
+		# each build stage
 		cd $base/dist ; cat > make_chroot.sh <<- EOS
 			. /etc/profile
 			set -e
@@ -119,17 +144,21 @@
 			fi
 			./scripts/Build-Pkg rock-debug
 		EOS
+		# Go into chroot
 		chroot $base/dist /bin/sh make_chroot.sh || finish 1
+		# Clean up and unmount nfs
 		rm -f make_chroot.sh ; cd $base ; echo
 		umount -v dist/dev dist/proc
 		[ $1 != COPY -a $1 != LINK ] && umount -v dist/rock-orig
 	    fi
 
+        # At this point all binary tar balls have been built
 	    echo -e "\n ** Move package files **\n"
 
+        # Create directory with distribution name
 	    mkdir -p rock-$arch-$rockver/base-pkgs
 
-	    # Move base packages
+	    # Move binary base packages into new tree
 	    #
 	    grep '^[xo]' scripts/packages | tr ' ' '\t' |
 	    tr -s '\t'| cut -f4 | while read pkg ; do
@@ -155,7 +184,7 @@
 		fi
 	    done
 
-	    # Move ext packages
+	    # Move ext binary packages
 	    #
 	    grep -v '^#' ext-config/INDEX | grep . | \
 	    while read dir pkg url ; do
@@ -187,6 +216,9 @@
 	    cp dist/usr/lib/install-disk/bin/install_bin.static \
 	       rock-$arch-$rockver/Install.bin
 
+        # Done! The full binary distribution lives in 
+		# rock-$arch-$rockver! It becomes a bootable CD
+		# image when burnt onto a CDROM
 	    echo -e "\n ** Clean up **\n"
 	    ./scripts/Cleanup
 
@@ -208,6 +240,7 @@
 
 	finish 0
 } 2>&1 | {
+    # A child has thrown an error, cleanup:
 	trap '' INT
 	tee -a build.out
 }
--- rock-old/scripts/Build-Stage	Mon Jan 15 10:14:27 2001
+++ rock-new/scripts/Build-Stage	Sun Oct 14 11:48:16 2001
@@ -1,5 +1,9 @@
 #!/bin/sh
+#
+#   Script gets called by ./scripts/Build-All and manages one build
+#   stage.
 
+# Set environment
 . ./scripts/parse-config
 
 if [ "$arch" = any ] ; then
@@ -25,15 +29,18 @@
 	# Build the extension packages. Never abort if an extension
 	# fails to build.
 	#
+	# Read the INDEX file
 	grep -v '^#' ext-config/INDEX | grep . | \
 	while read dir ext url ; do
 	    if [ -d ext-archive/$ext -a -f ext-config/$ext.ext ] ; then
+		# Get priority level 'pri'
 		pri="`egrep '^# \[(P|PRI|PRIORITY)\] ' ext-config/$ext.ext |
 		      head -1 | sed 's,^[^]]*] *,,'`"
 		[ "$pri" ] && echo "$ext:$pri"
 	    fi
 	done | sort -t: -k2 | cut -f1 -d: |
 	while read ext ; do
+	    # Build ext package if it is stable (only)
 	    if egrep -iq '^# \[(S|STATUS)\] Stable' ext-config/$ext.ext
 	    then
 		./scripts/Build-Pkg -5 -norebuild -maketar $ext
@@ -45,11 +52,21 @@
 
 	# Build the base packages
 	#
+	# Parse the ./scripts/packages file which defines all 
+	# packages. The packages starting with 'o' are considered
+	# optional and can be turned on using 'buildoptpkgs' by 
+	# Config (incidentally the 'x' packages are preselected
+	# by the binary distribution Install.bin program)
+	#
+	# The packages file also defines which packages get built
+	# in which stage.
+	#
 	grep '^[xo]' scripts/packages | \
 	tr ' ' '\t' | tr -s '\t' | cut -f 1,2,4 | \
 	while read isopt stages pkg ; do
 	    if [ $buildoptpkgs = 1 -o $isopt = x ] &&
 	       expr "$stages" : ".*$1.*" > /dev/null ; then
+		    # See if package fits in build stage
 		    if [ $makerebuild != 0 ] ; then
 			last=`echo $stages | tr -d '-' | sed 's,.*\(.\),\1,'`
 		    else
@@ -57,6 +74,7 @@
 		    fi
 		    if [ $last = $1 -o $crossnative = cross ]
 		    then maketar="-maketar" ; else maketar="" ; fi
+			# Build package
 		    ./scripts/Build-Pkg -$1 -norebuild $maketar $pkg
 		    if [ $? -ne 0 -a $abortonerror = 1 ] ; then
 			touch src/temp.stage-abort ; break
--- rock-old/scripts/Build-Subdist	Tue Apr 10 13:20:58 2001
+++ rock-new/scripts/Build-Subdist	Sun Oct 14 12:13:00 2001
@@ -1,5 +1,15 @@
 #!/bin/sh
+#
+#   This script gets called by Build-All in the final stage to 
+#   create each (standard) subdistribution
+#
+#   Each subdistribution gets built by a shell script named
+#   subdists/$1/build-subdist.sh. This subdistribution script 
+#   has to unpack the designated binary tar balls in a tree 
+#   and finally tars it all up again. For an example see the
+#   version for the rescue subdistribution.
 
+# Set environment
 . ./scripts/parse-config
 
 if [ "$arch" = any ] ; then
@@ -24,6 +34,7 @@
 	echo "File not found: subdists/$1/build-subdist.sh" ; exit 1
 fi
 
+# Some environment variables for build-subdist.sh
 sd_name=$1
 sd_srcdir=$base/subdists/$sd_name
 sd_instdir=$base/rock-$arch-$rockver/subdists
@@ -39,11 +50,14 @@
 umount src/*/{dev,proc} src/*/*/{dev,proc} 2> /dev/null
 rm -rf src/ ; mkdir -p src
 
+# Build in the ./src directory
 {
+    # Catch errors
 	trap 'exit 1' INT  ;  set -e
 	. $sd_srcdir/build-subdist.sh
 	touch $sd_infodir/logs/s-$sd_name.log
 } 2>&1 | {
+    # Recover from error and create logs
 	trap '' INT
 	mkdir -p $sd_infodir/logs
 	rm -f $sd_infodir/logs/s-$sd_name.{out,log,err}
@@ -57,12 +71,14 @@
 umount src/*/{dev,proc} src/*/*/{dev,proc} 2> /dev/null
 
 if [ -f $sd_infodir/logs/s-$sd_name.log ] ; then
+    # Build succeeded
 	rm -rf src/ ; mkdir -p src
 	echo "rock-$arch-$rockver/info/logs/s-$sd_name.out -> s-$sd_name.log"
 	mv $sd_infodir/logs/s-$sd_name.out $sd_infodir/logs/s-$sd_name.log
 	date "+== %D %T =[S]=> Finished building subdistribution $sd_name."
 	exit 0
 else
+    # Build failed
 	if [ $dontprintlogs = 1 ] ; then
 		echo "`tail < $sd_infodir/logs/s-$sd_name.out`" | \
 			sed 's,^,> ,; s/^\(.\{70\}\).\{3,\}/\1 ../'
--- rock-old/scripts/Internal	Wed Oct 10 11:24:00 2001
+++ rock-new/scripts/Internal	Sun Oct 14 11:10:54 2001
@@ -1,5 +1,8 @@
 #!/bin/sh
-
+# 
+# Internal contains functionality for maintaining ROCK Linux sources
+# and development.
+# 
 NO_AUTO_BACKUP=x
 . `dirname $0`/parse-config
 
@@ -140,6 +143,15 @@
 	foreach (sort keys %x) { print "$_$x{$_}\n" if $x{$_}=~/.\t/; }'
 elif [ "$1" = "diff" -a "$#" = "3" ] ||
      [ "$1" = "diff" -a "$2" = "-base" -a "$#" = "4" ] ; then
+	#
+	# 'diff' parameters: [ -base ] <old-dir> <new-dir> 
+	#
+	#  Runs a unified diff against two ROCK source trees. The output
+	#  of this diff you can send to Clifford if you want your changes
+	#  included in the next development tree. 
+	#
+	#  The -base option excludes all packages in ext-config
+	#
 	if ! perl -e 'exit 0' ; then
 		perl() { cat ; }
 	fi
@@ -272,7 +284,7 @@
 	echo
 	echo "This is an Internal Script. It is only needed by the core developers."
 	echo
-	echo "Usage: ./scripts/Internal  checkver | diff <old-dir> <new-dir>"
+	echo "Usage: ./scripts/Internal  checkver | diff [ -base ] <old-dir> <new-dir>"
 	x="                          "
 	echo "$x" "{ snapshot | devel-update } [ <my-inet-ip> ] | getip"
 	echo "$x" "make-cksum-cache | ext-checkdup | refetch-ext"
--- rock-old/scripts/parse-config	Mon Sep  3 14:20:23 2001
+++ rock-new/scripts/parse-config	Sun Oct 14 11:36:59 2001
@@ -1,4 +1,7 @@
-
+#
+# This script sets environment settings and parses the standard
+# ./Config file
+#
 # [BEGIN] of config section
 
 rockver=1.5.12  # Release Version