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 000000000..6a613d1f9 Binary files /dev/null and b/src/minimal_overlay/bundles/hello_mll/hello differ 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 + +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 ' to search for + packages and 'static-get -i ' 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'! :)