Added 'hello_mll' overlay bundle. Enhanced the internal docs.

src/.config

@@ -137,6 +137,7 @@ OVERLAY_TYPE=folder
 # fio            - I/O load generator.
 # golang         - Google's Go programming language.
 # graalvm        - VM for Java, JavaScript, Python, Ruby, R, LLVM.
+# hello_mll      - simple educational overlay bundle. Type 'hello' to run it.
 # java           - Oracle JRE or JDK. Manual preparations are required.
 # kbd            - keyboard utilities.
 # kernel_modules - default MLL kernel modules and 'mdev' hotplug manager.
@@ -172,9 +173,13 @@ OVERLAY_TYPE=folder
 #
 # OVERLAY_BUNDLES=dhcp,felix,links,openjdk
 #
-# The default overlay bundles are 'dhcp', 'mll_logo' and 'mll_source'.
+# The default overlay bundles are:
+# * dhcp
+# * hello_mll
+# * mll_logo
+# * mll_source
 #
-OVERLAY_BUNDLES=dhcp,mll_logo,mll_source
+OVERLAY_BUNDLES=dhcp,hello_mll,mll_logo,mll_source
 
 # The location where the overlay bundle software will be stored.
 #

src/README

@@ -71,6 +71,9 @@ Currently available overlay bundles:
                    Java, Scala, Clojure, Kotlin, and LLVM-based languages such
                    as C and C++.
 
+  Hello MLL      - Simple educational overlay bundle with detailed comments
+                   for each build step.
+
   JRE / JDK      - Oracle JRE/JDK. This overlay bundle requires some manual
                    preparation steps. Refer to the 'JAVA_ARCHIVE' property in
                    the '.config' file for more information. This overlay bundle

src/minimal_overlay/bundles/hello_mll/bundle.sh

@@ -0,0 +1,90 @@
+#!/bin/sh
+
+# Break the process if there are any errors
+set -e
+
+# Import common variables and functions
+. ../../common.sh
+
+
+# By convention the overlay bundles have "source" folder, where the source
+# code is downloaded. If the source is downloaded from internet, this allows
+# the download to proceed if the process has been interrupted. In our simple
+# use case we will copy the file "hello.c" and in this way we will simulate
+# (kind of) that it has been downloaded.
+#
+# The main overlay source folder is "minimal/src/source/overlay" and the bundle
+# source artifact will be "minimal/src/source/overlay/hello.c".
+cp $SRC_DIR/hello.c \
+  $OVERLAY_SOURCE_DIR
+
+# The next step is to prepare the source code that we have downloaded in the
+# previous step. Usually this means to extract it. By convention each overlay
+# bundle has its own root folder where all the build magic happens. In our 
+# simple use case we will "extract" the source code by copying it from the
+# source folder to the main bundle folder.
+#
+# The main overlay folder is "minimal/src/work/overlay" and the bundle overlay
+# folder will be "minimal/src/work/overlay/hello_mll".
+mkdir $OVERLAY_WORK_DIR/$BUNDLE_NAME
+cp $OVERLAY_SOURCE_DIR/hello.c \
+  $OVERLAY_WORK_DIR/$BUNDLE_NAME
+
+# Each overlay bundle also has a special directory where all build artifacts
+# are put in a structure which represents the final OS folder structure. This
+# folder is "minimal/src/work/overlay/hello_mll/hello_mll_installed".
+
+# First we create the "destination" folder.
+mkdir $DEST_DIR
+
+# We want our "hello" executable to reside in the "/bin" folder, so we create
+# subfolder "bin" in "$DEST_DIR".
+mkdir $DEST_DIR/bin
+
+# Now we can compile "$OVERLAY_WORK_DIR/$BUNDLE_NAME/hello.c" and place it in
+# "$DEST_DIR/bin" as executable binary "hello".
+gcc -o $DEST_DIR/bin/hello $OVERLAY_WORK_DIR/$BUNDLE_NAME/hello.c
+
+# Optionally, we can reduce the size of the generated overlay bundle artifacts.
+# We use the special function "reduce_size" and we pass as argument the file or
+# folder where our generated artifacts are located.
+reduce_size $DEST_DIR/bin/hello
+
+# No matter what you do with your bundles, no matter how you compile and/or
+# prepare them, in the end all your bundle artifacts must end up in the folder
+# "$OVERLAY_ROOTFS". This special folder represents the final OS structure
+# where all overlay bundles place their final artifacts. In our simple use case
+# we have already prepared appropriate OS folder structure in "$DEST_DIR", so
+# we will simply copy it in "$OVERLAY_ROOTFS".
+#
+# The overlay root filesystem folder is "minimal/src/work/overlay_rootfs".
+
+# We use the special function "install_to_overlay" which works in three modes:
+#
+# Mode 1 - install everything from "$DEST_DIR" in "OVERLAY_ROOTFS":
+#
+#  install_to_overlay (no arguments provided)
+#
+# Mode 2 - install specific file/folder from "$DEST_DIR", e.g. "$DEST_DIR/bin"
+# directly in "$OVERLAY_ROOTFS":
+#
+#  install_to_overlay bin
+#
+# Mode 3 - install specific file/folder from "$DEST_DIR", e.g. "$DEST_DIR/bin"
+# as specific file/folder in "$OVERLAY_ROOTFS", e.g. "$OVERLAY_ROOTFS/bin"
+#
+#  install_to_overlay bin bin
+#
+# All of the above examples have the same final. In our simple use case we use
+# the first mode (i.e. we provide no arguments).
+install_to_overlay
+
+# In the end we print message that our bundle has been installed and we return
+# to the overlay source folder.
+echo "Bundle '$BUNDLE_NAME' has been installed."
+
+cd $SRC_DIR
+
+# That's it. Add the overlay bundle in the main ".config" file, rebuild MLL
+# (i.e. run "repackage.sh") and when the OS starts, type "hello".
+

src/minimal_overlay/bundles/hello_mll/hello.c

@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+void main() {
+  printf("Hello MLL! :)\n");
+}
+

src/minimal_overlay/rootfs/README

@@ -1,14 +1,24 @@
 
-This file can be found in the folder 'minimal_overlay/rootfs'.
+   This file can be found in the folder 'minimal/src/minimal_overlay/rootfs'
 
-You can use this folder to put your own content (files and folders) which will
+ You can use the above folder to put your own content (files and folders) which
-be visible in the root folder of your 'Minimal Linux Live' system, just like
+ will be visible in the root folder of your 'Minimal Linux Live' system, just
-this file is visible. The files/folders will override the content in the root
+ like this file is visible. The files/folders will override the content in the
-folder, so be careful what you put there because you may end up with broken
+ root folder, so be careful what you put there because you may break your OS.
-system. If the boot media is writeable, then all changes on the root file system
+ If the boot media is writable, then all changes on the root file system are
-are persisted automatically, so be very careful what you do when you use the
+ persisted automatically, so be very careful what you do when you use the
-overlay support.
+ overlay system.
 
-Check the '.config' file in the source folder for more details on the overlay
+ Another way to add software in 'Minimal Linux Live' is by using the overlay
-options and how to use them.
+ bundles which add the software while the OS is being built. Check the
+ 'hello_mll' overlay bundle in folder 'minimal/src/minimal_overlay/bundles'.
+
+ You can also add software in 'Minimal Linux Live' while the OS is running with
+ the 'static_get' overlay bundle. Use 'static-get -s <package>' to search for
+ packages and 'static-get -i <package>' to install the package.
+
+ Check the '.config' file in the source folder for more details regarding the\
+ overlay system and how to use it.
+
+   Have fun with 'Minimal Linux Live'! :)