Add explanation comments on the build system files

.gitlab-ci.yml

@@ -1,3 +1,4 @@
+# The GitLab Continuous Integration configuration
 image: "ubuntu:22.04"
 
 variables:

Makefile

@@ -1,7 +1,8 @@
-# Configuration and variables
+# This file contains the build system commands configuration
+# and environment variables
 include mk/config.mk
 
-# Dependencies
+# Build system dependencies
 include mk/depends.mk
 
 all: $(BUILD)/harddrive.img

bootstrap.sh

@@ -1,3 +1,7 @@
+# This script setup the Redox build system
+# It install Rustup, the recipe dependencies for cross-compilation
+# and download the build system configuration files
+
 #!/usr/bin/env bash
 
 set -e

build.sh

@@ -1,3 +1,5 @@
+# Alternative script for the build system Makefiles
+
 #!/usr/bin/env bash
 
 ###########################################################################

config/aarch64/acid.toml

@@ -1,3 +1,3 @@
-# Configuration for using acid
+# Configuration to run the "acid" tests
 
 include = ["../acid.toml"]

config/aarch64/ci.toml

@@ -1,4 +1,4 @@
-# This is the CI configuration file
+# The Redox build server configuration
 
 # General settings
 [general]

config/aarch64/demo.toml

@@ -1 +1,3 @@
+# Configuration for demonstration
+
 include = ["desktop.toml"]

config/aarch64/desktop-minimal.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Minimal desktop configuration
 
 include = ["../desktop-minimal.toml"]
 

config/aarch64/desktop.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Default build system configuration
 
 include = ["../minimal.toml"]
 

config/aarch64/jeremy.toml

@@ -1 +1,3 @@
+# Configuration for Jeremy Soller
+
 include = ["desktop.toml"]

config/aarch64/minimal-net.toml

@@ -1,4 +1,4 @@
-# Minimal configuration
+# Minimal network configuration
 
 include = ["../minimal-net.toml"]
 

config/aarch64/resist.toml

@@ -1,3 +1,3 @@
-# Configuration for using resist
+# Configuration to run the "resist" tests
 
 include = ["../resist.toml"]

config/aarch64/server.toml

@@ -1,4 +1,4 @@
-# Default server configuration
+# Server configuration
 
 include = ["../server.toml"]
 

config/acid.toml

@@ -1,4 +1,4 @@
-# Configuration for using acid
+# Configuration to run the "acid" tests
 
 include = ["base.toml"]
 

config/desktop-minimal.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Minimal desktop configuration
 
 include = ["minimal-net.toml"]
 

config/desktop.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Default build system configuration
 
 include = ["server.toml"]
 

config/dev.toml

@@ -1,4 +1,4 @@
-# Configuration for development, includes cargo and rustc
+# Configuration for development
 
 include = ["desktop.toml"]
 

config/i686/acid.toml

@@ -1,3 +1,3 @@
-# Configuration for using acid
+# Configuration to run the "acid" tests
 
 include = ["../acid.toml"]

config/i686/ci.toml

@@ -1,4 +1,4 @@
-# This is the CI configuration file
+# The Redox build server configuration
 
 # General settings
 [general]

config/i686/demo.toml

@@ -1,3 +1,4 @@
+# Configuration for demonstration
 ##############################################################################
 #                          Redox Demo Configuration                          #
 #                                                                            #

config/i686/desktop-minimal.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Minimal desktop configuration
 
 include = ["../desktop-minimal.toml"]
 

config/i686/desktop.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Default build system configuration
 
 include = ["../desktop.toml"]
 

config/i686/dev.toml

@@ -1,4 +1,4 @@
-# Configuration for development, includes cargo and rustc
+# Configuration for development
 
 include = ["../dev.toml"]
 

config/i686/jeremy.toml

@@ -1,4 +1,4 @@
-# Jeremy's configuration
+# Configuration for Jeremy Soller
 
 include = ["../desktop.toml"]
 

config/i686/minimal-net.toml

@@ -1,4 +1,4 @@
-# Minimal configuration
+# Minimal network configuration
 
 include = ["../minimal-net.toml"]
 

config/i686/resist.toml

@@ -1,3 +1,3 @@
-# Configuration for using resist
+# Configuration to use the "resist" tests
 
 include = ["../resist.toml"]

config/i686/server.toml

@@ -1,4 +1,4 @@
-# Default server configuration
+# Server configuration
 
 include = ["../server.toml"]
 

config/llvm.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# # Configuration to create "llvm-config" script
 
 include = ["base.toml"]
 

config/net.toml

@@ -1,4 +1,4 @@
-# Net configuration: includes the base configuration and adds files required
+# Network configuration: includes the base configuration and adds files required
 # for networking
 
 include = ["base.toml"]

config/redoxer-gui.toml

@@ -1,4 +1,4 @@
-# Configuration for redoxer GUI image
+# Configuration for the Redoxer GUI image
 
 include = ["redoxer.toml"]
 

config/redoxer.toml

@@ -1,4 +1,4 @@
-# Configuration for redoxer image
+# Configuration for the Redoxer image
 
 include = ["net.toml"]
 

config/resist.toml

@@ -1,4 +1,4 @@
-# Configuration for using resist
+# Configuration to run the "resist" tests
 
 include = ["net.toml"]
 

config/server.toml

@@ -1,4 +1,4 @@
-# Default server configuration
+# Server configuration
 
 include = ["net.toml"]
 

config/x86_64/acid.toml

@@ -1,3 +1,3 @@
-# Configuration for using acid
+# Configuration to use the "acid" tests
 
 include = ["../acid.toml"]

config/x86_64/ci.toml

@@ -1,4 +1,4 @@
-# This is the CI configuration file
+# The Redox build server configuration
 
 # General settings
 [general]

config/x86_64/demo.toml

@@ -1,3 +1,4 @@
+# Configuration for demonstration
 ##############################################################################
 #                          Redox Demo Configuration                          #
 #                                                                            #

config/x86_64/desktop-contain.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration using contain
+# Desktop configuration using the Contain sandbox
 
 include = ["../desktop.toml"]
 

config/x86_64/desktop-minimal.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Minimal desktop configuration
 
 include = ["../desktop-minimal.toml"]
 

config/x86_64/desktop.toml

@@ -1,4 +1,4 @@
-# Default desktop configuration
+# Default build system configuration
 
 include = ["../desktop.toml"]
 

config/x86_64/dev.toml

@@ -1,4 +1,4 @@
-# Configuration for development, includes cargo and rustc
+# Configuration for development
 
 include = ["../dev.toml"]
 

config/x86_64/jeremy.toml

@@ -1,4 +1,4 @@
-# Jeremy's configuration
+# Configuration for Jeremy Soller
 
 include = ["../desktop.toml"]
 

config/x86_64/llvm.toml

@@ -1,3 +1,3 @@
-# Config for creating llvm-config script
+# Configuration to create "llvm-config" script
 
 include = ["../llvm.toml"]

config/x86_64/minimal-net.toml

@@ -1,4 +1,4 @@
-# Minimal configuration
+# Minimal network configuration
 
 include = ["../minimal-net.toml"]
 

config/x86_64/resist.toml

@@ -1,3 +1,3 @@
-# Configuration for using resist
+# Configuration to run the "resist" tests
 
 include = ["../resist.toml"]

config/x86_64/server.toml

@@ -1,4 +1,4 @@
-# Default server configuration
+# Server configuration
 
 include = ["../server.toml"]
 

docker/Dockerfile

@@ -1,3 +1,5 @@
+# Configuration file to setup the Docker container of Redox
+
 FROM rustlang/rust:nightly
 
 ENV IMAGE_NAME=redox-os-docker

docker/docker.sh

@@ -1,3 +1,5 @@
+# This script run the Docker image of Redox
+
 docker run --privileged --cap-add MKNOD --cap-add SYS_ADMIN --device /dev/fuse \
     -e LOCAL_UID="$(id -u)" -e LOCAL_GID="$(id -g)" \
     -v redox-"$(id -u)-$(id -g)"-cargo:/usr/local/cargo \

mk/ci.mk

@@ -1,3 +1,5 @@
+# Configuration file of the build system commands for the build server
+
 IMG_TAG?=$(shell git describe --tags)
 IMG_SEPARATOR?=_
 IMG_DIR?=build/img/$(ARCH)

mk/config.mk

@@ -1,3 +1,5 @@
+# Configuration file of the build system environment variables
+
 -include .config
 
 HOST_ARCH?=$(shell uname -m)

mk/depends.mk

@@ -1,4 +1,4 @@
-# Dependencies
+# Configuration file for the build system dependencies
 
 # Don't check for Rust/Cargo if you will be using Podman
 ifneq ($(PODMAN_BUILD),1)

mk/disk.mk

@@ -1,3 +1,5 @@
+# Configuration file with the commands configuration of the Redox image
+
 $(BUILD)/harddrive.img: $(FSTOOLS_TAG) $(REPO_TAG)
 	mkdir -p $(BUILD)
 	rm -rf $@  $@.partial

mk/fstools.mk

@@ -1,3 +1,5 @@
+# Configuration file for redox-installer, Cookbook and RedoxFS FUSE
+
 fstools: $(FSTOOLS_TAG)
 
 $(FSTOOLS_TAG): cookbook installer redoxfs $(CONTAINER_TAG)

mk/podman.mk

@@ -1,6 +1,4 @@
-##############################################
-# podman.mk - Use Podman to build components #
-##############################################
+# Configuration file of the Podman commands
 
 # Configuration variables for running make in Podman
 ## Tag the podman image $IMAGE_TAG

mk/prefix.mk

@@ -1,3 +1,5 @@
+# Configuration file for the Rust/GCC cross-compilers and relibc
+
 PREFIX=prefix/$(TARGET)
 
 PREFIX_INSTALL=$(PREFIX)/relibc-install

mk/qemu.mk

@@ -1,3 +1,5 @@
+# Configuration file for QEMU
+
 QEMU=SDL_VIDEO_X11_DGAMOUSE=0 qemu-system-$(QEMU_ARCH)
 QEMUFLAGS=-d guest_errors -name "Redox OS $(ARCH)"
 

mk/repo.mk

@@ -1,3 +1,5 @@
+# Configuration file for recipe commands
+
 $(BUILD)/fetch.tag: prefix $(FSTOOLS_TAG) $(FILESYSTEM_CONFIG) $(CONTAINER_TAG)
 ifeq ($(PODMAN_BUILD),1)
 	$(PODMAN_RUN) $(MAKE) $@

mk/virtualbox.mk

@@ -1,3 +1,5 @@
+# Configuration file for VirtualBox, it creates a VirtualBox virtual machine
+
 virtualbox: $(BUILD)/harddrive.img
 	echo "Delete VM"
 	-$(VBM) unregistervm Redox --delete; \

podman/redox-base-containerfile

@@ -1,3 +1,5 @@
+# Configuration file to install the recipe dependencies inside the Podman container
+
 FROM debian:bookworm-20240513-slim
 
 # _UID_ must be replaced with the user's uid on host

podman/rustinstall.sh

@@ -1,6 +1,7 @@
-#/usr/bin/env bash
+# This script install the Rust toolchain and the build system dependencies
+# in Podman after the image has been built
 
-# Install Rust in Podman, after the image has been built
+#/usr/bin/env bash
 
 curl https://sh.rustup.rs -sSf | sh -s -- -y --default-toolchain stable
 cargo +stable install --force --version 0.1.1 cargo-config

podman_bootstrap.sh

@@ -1,3 +1,7 @@
+# This script setup the Redox build system with Podman
+# It install the Podman dependencies, Rustup, recipes dependencies for cross-compilation
+# and download the build system configuration files
+
 #!/usr/bin/env bash
 
 set -e

scripts/backtrace.sh

@@ -1,3 +1,6 @@
+# This script allow the user to copy a Rust backtrace from Redox
+# and retrieve the symbols
+
 #!/usr/bin/env bash
 
 usage()

scripts/category.sh

@@ -1,3 +1,5 @@
+# This script run the recipe command options on some Cookbook category
+
 #!/usr/bin/env bash
 
 if [ -z "$1" ] || [ -z "$2" ]

scripts/changelog.sh

@@ -1,3 +1,5 @@
+# This script show the changelog of all Redox components
+
 #!/usr/bin/env bash
 
 set -e

scripts/commit-hash.sh

@@ -1,3 +1,5 @@
+# This script show the current Git branch and commit of the recipe source
+
 #!/usr/bin/env bash
 
 if [ $# -ne 1 ]

scripts/dual-boot.sh

@@ -1,3 +1,6 @@
+# This script install Redox in the free space of your storage device
+# and add a boot entry (if you are using the systemd-boot boot loader)
+
 #!/usr/bin/env bash
 
 set -e

scripts/find-recipe.sh

@@ -1,3 +1,5 @@
+# This script show all files installed by a recipe
+
 #!/usr/bin/env bash
 
 # Ensure arch and config are set as desired, we use these to find the build dir

scripts/include-recipes.sh

@@ -1,3 +1,7 @@
+# This script create a list with:
+# "recipe-name = {} #TODO"
+# For quick testing of WIP recipes
+
 #!/usr/bin/env bash
 
 # Given a string, find recipe.toml files containing that string.

scripts/pkg-size.sh

@@ -1,3 +1,6 @@
+# This script show the package size of the recipes ("stage.pkgar" and "stage.tar.gz")
+# It must be used by package maintainers to enforce the library linking size policy
+
 #!/usr/bin/env bash
 
 if [ $# = 0 ]

scripts/show-package.sh

@@ -1,6 +1,6 @@
-#!/usr/bin/env bash
+# This script show the contents of the "stage" and "sysroot" folders in some recipe
 
-# Show the contents of the stage and sysroot folders in some recipe
+#!/usr/bin/env bash
 
 if [ -z "$*" ]
 then

scripts/ventoy.sh

@@ -1,3 +1,5 @@
+# This script create and copy the Redox bootable image to an Ventoy-formatted device
+
 #!/usr/bin/env bash
 
 set -e