From 0d720bcdac2efe0b100f7f556e5e9f4faced3041 Mon Sep 17 00:00:00 2001
From: Ivan Davidov <davidov.i@gmail.com>
Date: Sun, 8 Sep 2019 21:56:06 +0300
Subject: [PATCH] Added 'hello_mll' overlay bundle. Enhanced the internal docs.

---
 src/.config                                   |   9 +-
 src/README                                    |   3 +
 .../bundles/hello_mll/bundle.sh               |  90 ++++++++++++++++++
 src/minimal_overlay/bundles/hello_mll/hello   | Bin 0 -> 8304 bytes
 src/minimal_overlay/bundles/hello_mll/hello.c |   6 ++
 src/minimal_overlay/rootfs/README             |  30 ++++--
 6 files changed, 126 insertions(+), 12 deletions(-)
 create mode 100755 src/minimal_overlay/bundles/hello_mll/bundle.sh
 create mode 100755 src/minimal_overlay/bundles/hello_mll/hello
 create mode 100644 src/minimal_overlay/bundles/hello_mll/hello.c

diff --git a/src/.config b/src/.config
index fa07f329b..39e96bd40 100644
--- a/src/.config
+++ b/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.
 #
diff --git a/src/README b/src/README
index dc81f227a..2b33df6c1 100644
--- a/src/README
+++ b/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
diff --git a/src/minimal_overlay/bundles/hello_mll/bundle.sh b/src/minimal_overlay/bundles/hello_mll/bundle.sh
new file mode 100755
index 000000000..bb87b634c
--- /dev/null
+++ b/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".
+
diff --git a/src/minimal_overlay/bundles/hello_mll/hello b/src/minimal_overlay/bundles/hello_mll/hello
new file mode 100755
index 0000000000000000000000000000000000000000..6a613d1f9a669f6188566a2b8966dd6c5fcdb603
GIT binary patch
literal 8304
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
M>0l0uf`0pd18aI05&!@I

literal 0
HcmV?d00001

diff --git a/src/minimal_overlay/bundles/hello_mll/hello.c b/src/minimal_overlay/bundles/hello_mll/hello.c
new file mode 100644
index 000000000..7e3bee5b5
--- /dev/null
+++ b/src/minimal_overlay/bundles/hello_mll/hello.c
@@ -0,0 +1,6 @@
+#include <stdio.h>
+
+void main() {
+  printf("Hello MLL! :)\n");
+}
+
diff --git a/src/minimal_overlay/rootfs/README b/src/minimal_overlay/rootfs/README
index 0d239e16f..bf4b011a1 100644
--- a/src/minimal_overlay/rootfs/README
+++ b/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
-be visible in the root folder of your 'Minimal Linux Live' system, just like
-this file is visible. The files/folders will override the content in the root
-folder, so be 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.
+ You can use the above folder to put your own content (files and folders) which
+ will be visible in the root folder of your 'Minimal Linux Live' system, just
+ like this file is visible. The files/folders will override the content in the
+ root folder, so be careful what you put there because you may break your OS.
+ If the boot media is writable, then all changes on the root file system are
+ persisted automatically, so be very careful what you do when you use the
+ overlay system.
 
-Check the '.config' file in the source folder for more details on the overlay
-options and how to use them.
+ Another way to add software in 'Minimal Linux Live' is by using the overlay
+ 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'! :)