Documentation improvements and cleanup. Added shutdown tasks (sync & umount).

.gitignore

@@ -5,6 +5,7 @@
 /src/source/**
 /src/work/**
 /src/*.iso
+/src/*.img
 
 /src/experimental/glibc-toybox/source/**
 /src/experimental/glibc-toybox/work/**

src/.config

@@ -29,26 +29,34 @@ SYSLINUX_SOURCE_URL=https://www.kernel.org/pub/linux/utils/boot/syslinux/syslinu
 ###   ###   ###
 
 # Use predefined '.config' file when building the kernel. This overrides the config generation
-# in '02_build_kernel.sh' and uses the config file provided in this parameter. You can comment,
+# in '02_build_kernel.sh' and the build process uses the config file provided in this parameter.
-# leave undefined or use nonexisting file in order to disable the property and rely on automatic
+# You can comment, leave undefined or use nonexisting file in order to disable the property and
-# config generation.
+# rely on automatic config generation. The file location is relative from the source folder.
 #
-# KERNEL_CONFIG_FILE=kernel.config
+# KERNEL_CONFIG_FILE=path/to/predefined/kernel.config
 
 # Use predefined '.config' file when building BusyBox. This overrides the config generation in
-# '07_build_busybox.sh' and uses the config file provided in this parameter. Leave undefined or
+# '07_build_busybox.sh' and the build process uses the config file provided in this parameter.
-# comment the property in order to disable it and rely on automatic config generation.
+# You can comment, leave undefined or use nonexisting file in order to disable the property and
+# rely on automatic config generation. The file location is relative from the source folder.
 #
-# BUSYBOX_CONFIG_FILE=busybox.config
+# BUSYBOX_CONFIG_FILE=path/to/predefined/busybox.config
 
 # Define the overlay type to use. Possible values are 'sparse' and 'folder'. You can use any other
-# value, no value, or comment the property in order to disable it.
+# value, no value, or comment the property in order to disable it. Put your overlay content in the
+# folder '11_generate_iso' and it will be automatically merged with the root file system on boot.
+# The build process creates either '/minimal.img/rootfs' or '/minimal/rootfs' (read below) and this
+# folder contains all overlay content in it. If the boot media is writeable, then all changes on
+# the root filesystem are automatically persisted.
 #
-# sparse - use sparse file with hardcoded maximal size of 1MB (see 11_generate_iso.sh). This option
+# sparse - use sparse file 'minimal.img' with hardcoded maximal size of 1MB (see 11_generate_iso.sh).
-#          requires root permissions. The generated ISO image is larger. 
+#          The generated ISO image is larger because the sparse file is treated as regular file. This
+#          option requires root permissions or otherwise sparse file generation is silently skipped.
+#          Sparse file is treated as separate disk image and works fine on 'vfat'. 
 #
-# folder - use normal folder structure. Currently this doesn't work if the file system is 'vfat'
+# folder - use normal folder structure (/minimal/). Note that this doesn't work if the file system is
-#          because FAT requires special handling, e.g. POSIX overlay (http://sf.net/p/posixovl).
+#          'vfat' because FAT requires special handling, e.g. POSIX overlay (http://sf.net/p/posixovl).
+#          This is the default option because it doesn't require root permissions.
 #
-OVERLAY_TYPE=sparse
+OVERLAY_TYPE=folder
 

src/02_build_kernel.sh

@@ -8,7 +8,7 @@ cd work/kernel
 cd $(ls -d *)
 
 # Cleans up the kernel sources, including configuration files.
-# make mrproper
+make mrproper
 
 # Read the 'KERNEL_CONFIG_FILE' property from '.config'
 KERNEL_CONFIG_FILE="$SRC_DIR/$(grep -i KERNEL_CONFIG_FILE $SRC_DIR/.config | cut -f2 -d'=')"
@@ -27,8 +27,6 @@ else
   sed -i "s/.*CONFIG_OVERLAY_FS.*/CONFIG_OVERLAY_FS=y/" .config
 fi
 
-exit 0
-
 # Compile the kernel with optimization for 'parallel jobs' = 'number of processors'.
 # Good explanation of the different kernels:
 # http://unix.stackexchange.com/questions/5518/what-is-the-difference-between-the-following-kernel-makefile-terms-vmlinux-vmlinux

src/07_build_busybox.sh

@@ -15,7 +15,7 @@ cd work/busybox
 cd $(ls -d *)
 
 # Remove previously generated artifacts.
-# make distclean
+make distclean
 
 # Read the 'BUSYBOX_CONFIG_FILE' property from '.config'
 BUSYBOX_CONFIG_FILE="$SRC_DIR/$(grep -iBUSYBOX_CONFIG_FILE $SRC_DIR/.config | cut -f2 -d'=')"
@@ -33,8 +33,6 @@ else
   sed -i "s/.*CONFIG_INETD.*/CONFIG_INETD=n/" .config
 fi
 
-exit 0
-
 # This variable holds the full path to the glibc installation area as quoted string.
 # All back slashes are escaped (/ => \/) in order to keep the 'sed' command stable.
 GLIBC_INSTALLED_ESCAPED=$(echo \"$GLIBC_INSTALLED\" | sed 's/\//\\\//g')

src/08_generate_rootfs.sh

@@ -20,7 +20,7 @@ cd $(ls -d *)
 # Copy all BusyBox generated stuff to the location of our 'initramfs' folder.
 cp -r _install ../../rootfs
 
-# Copy all rootfs stuff to the location of our 'initramfs' folder.
+# Copy all rootfs resources to the location of our 'initramfs' folder.
 cp -r ../../../08_generate_rootfs/* ../../rootfs
 
 cd ../../rootfs
@@ -35,6 +35,7 @@ cp ../../*.txt src
 cp -r ../../08_generate_rootfs src
 cp -r ../../11_generate_iso src
 
+# Make all files readable and all scripts executable.
 chmod -R +rx **/*.sh
 chmod -R +r **/.config
 chmod -R +r **/*.txt

src/08_generate_rootfs/etc/inittab

@@ -1,5 +1,9 @@
 ::sysinit:/etc/bootscript.sh
 ::restart:/sbin/init
+::shutdown:echo "Syncing file buffers..."
+::shutdown:/bin/sync
+::shutdown:echo "Unmounting all filesystems..."
+::shutdown:umount -a -r
 ::ctrlaltdel:/sbin/reboot
 ::once:cat /etc/welcome.txt
 ::respawn:/bin/cttyhack /bin/sh

src/08_generate_rootfs/etc/switch.sh

@@ -40,7 +40,7 @@ for DEVICE in /dev/* ; do
   WORK_DIR=""
 
   mount $DEVICE $DEVICE_MNT 2>/dev/null
-  if [ -d $DEVICE_MNT/minimal/rootfs ] && [ -d $DEVICE_MNT/minimal/work ] ; then
+  if [ -d $DEVICE_MNT/minimal/rootfs -a -d $DEVICE_MNT/minimal/work ] ; then
     # folder
     echo "  Found '/minimal' folder on device '$DEVICE'."
     touch $DEVICE_MNT/minimal/rootfs/minimal.pid 2>/dev/null
@@ -145,5 +145,7 @@ mount --move /tmp /mnt/tmp
 exec switch_root /mnt /sbin/init
 
 echo "You can never see this... unless there is a serious bug..."
-sleep 99999
+
+# Wait until any key has been pressed.
+read -n1 -s
 

src/11_generate_iso.sh

@@ -45,60 +45,59 @@ chmod +r src/*.txt
 
 # Read the 'OVERLAY_TYPE' property from '.config'
 OVERLAY_TYPE="$(grep -i OVERLAY_TYPE $SRC_DIR/.config | cut -f2 -d'=')"
+
 if [ "$OVERLAY_TYPE" = "sparse" -a "$(id -u)" = "0" ] ; then
-  # sparse
+  # Use sparse file as storage place. The above check guarantees that the whole
+  # script is executed with root permissions or otherwise this block is skipped.
+  # All files and folders located in the folder '11_generate_iso' will be merged
+  # with the root folder on boot.
   
   echo "Using sparse file for overlay."
   
-  # This is the BusyBox executable.
+  # This is the BusyBox executable that we have already generated.
   BUSYBOX=../rootfs/bin/busybox  
   
-  # Create sparse image file with 1MB size.
+  # Create sparse image file with 1MB size. Note that this increases the ISO image size.
   $BUSYBOX truncate -s 1M minimal.img
   
   # Find available loop device.
   LOOP_DEVICE=$($BUSYBOX losetup -f)
   
-  # Associate loop device with the sparse image file.
+  # Associate the available loop device with the sparse image file.
   $BUSYBOX losetup $LOOP_DEVICE minimal.img
   
   # Format the sparse image file with Ext2 file system. 
   $BUSYBOX mkfs.ext2 $LOOP_DEVICE
   
-  # Mount the sparse file in folder 'tmp_min".
+  # Mount the sparse file in folder 'sparse".
-  mkdir tmp_min
+  mkdir sparse
-  $BUSYBOX mount minimal.img tmp_min
+  $BUSYBOX mount minimal.img sparse
   
   # Create the overlay folders.
-  mkdir -p tmp_min/rootfs
+  mkdir -p sparse/rootfs
-  mkdir -p tmp_min/work
+  mkdir -p sparse/work  
   
   # Copy the overlay content.
-  cp -r $SRC_DIR/11_generate_iso/* tmp_min/rootfs/
+  cp -r $SRC_DIR/11_generate_iso/* sparse/rootfs/
   
   # Unmount the sparse file and thelete the temporary folder.
-  $BUSYBOX umount tmp_min
+  $BUSYBOX umount sparse
-  rm -rf tmp_min
+  rm -rf sparse
   
-  # Detach the loop device.
+  # Detach the loop device since we no longer need it.
   $BUSYBOX losetup -d $LOOP_DEVICE
 elif [ "$OVERLAY_TYPE" = "folder" ] ; then
-  # folder
+  # Use normal folder structure for overlay. All files and folders located in
+  # the folder '11_generate_iso' will be merged with the root folder on boot.
+  
   echo "Using folder structure for overlay."
+  
   mkdir -p minimal/rootfs
-  mkdir -p minimal/work
+  mkdir -p minimal/work  
   
   cp -r $SRC_DIR/11_generate_iso/* minimal/rootfs/
 fi
 
-# Create the overlay directory '/minimal/rootfs'. All files in this folder are
-# merged in the root folder and can be manipulated thanks to overlayfs.
-#mkdir -p minimal/rootfs
-#cd minimal/rootfs
-#echo 'Sample file 1 from CD.' > file_from_cd_1.txt
-#echo 'Sample file 2 from CD.' > file_from_cd_2.txt
-#cd ../..
-
 # Create ISOLINUX configuration file.
 echo 'default kernel.bz  initrd=rootfs.gz' > ./isolinux.cfg
 

src/11_generate_iso/README.txt

@@ -1,7 +1,12 @@
 
-This file is located in directory '11_generate_iso'. You can use this directory
+This file has been generated from directory '11_generate_iso'. You can use this
-to put your own content (files and folders) which will be visible in the root
+directory to put your own content (files and folders) which will be visible in
-directory of your 'Minimal Linux Live' system, just like this file is visible.
+the root directory of your 'Minimal Linux Live' system, just like this file is
-The files/folders will override the content in the root folder, so be careful
+visible. The files/folders will override the content in the root folder, so be
-what you put there because you may end up with broken system. :)
+careful what you put there because you may end up with broken system. If the
+boot media is writeable, then all changes on the root file system are persisted
+automatically, so be very careful what you do when you use the overlay support.
+
+
+Check the file '/src/.config' for more details on the overlay options.
 

src/qemu32.sh

@@ -1,5 +1,9 @@
 #!/bin/sh
 
 qemu-system-i386 -m 64M -cdrom minimal_linux_live.iso -boot d
-#qemu-system-i386 -m 64M -hda hdd.img -cdrom minimal_linux_live.iso -boot d
+
+# Use this when you want to play with hard disk content. You can manually create
+# sparse file (/minimal.img) and put overlay content (/minimal.img/rootfs) in it.
+#
+# qemu-system-i386 -m 64M -hda hdd.img -cdrom minimal_linux_live.iso -boot d
 

src/qemu64.sh

@@ -2,3 +2,7 @@
 
 qemu-system-x86_64 -m 64M -hda hdd.img -cdrom minimal_linux_live.iso -boot d
 
+# Use this when you want to play with hard disk content. You can manually create
+# sparse file (/minimal.img) and put overlay content (/minimal.img/rootfs) in it.
+#
+# qemu-system-x86_64 -m 64M -hda hdd.img -cdrom minimal_linux_live.iso -boot d