Advancing on the documentation

And fixing a few directories names, in order to conform
with the documentation.

Signed-off-by: Myy Miouyouyou <myy@miouyouyou.fr>

DESIGN.md

@@ -3,63 +3,43 @@ Status: DRAFT
 
 # Main design
 
-## Adding a module
+## Adding a simple module directly on your system
 
 For each module you want to add :
 
-1. Create a directory inside `modules/`.
-2. Inside this directory add the following files :
-    1. **module.cli**  
-    The CLI version of the module that will be executed by default.  
-    This can be symlinked to system binaries, if you know what you're
-    doing.
-    2. **DESC**  
-    A description of the module.  
-    The first line should be brief, as it is shown in the list
-    provided by the main **configurator**, when listing all the modules.
-    3. **armbian/cli/DEPS**  
-    The list of additional Debian packages required to execute `module.cli`.  
-    Only put the dependencies that are not required by the **configurator**
-    itself.
+1. Create the following subdirectory :  
+`/usr/share/armbian/configurator/modules/${module_name}/cli` .
+2. Copy your module executable file to :  
+`/usr/share/armbian/configurator/modules/${module_name}/cli/module` .  
+The file can actually be an absolute symlink to a system executable
+file too.
+3. Write a short description of the module in  
+`/usr/share/armbian/configurator/modules/${module_name}/DESC` .
+
+That's about it.  
+
+For deveopment purposes, you might want to actually symlink
+`/usr/share/armbian/configurator/modules/${module_name}` to
+a development directory inside your home directory.  
+For example :
+`sudo ln -s /usr/share/armbian/configurator/modules/${module_name} /home/YourUserName/module_name`
 
 ## Adding a GUI (X11/Wayland) to a module
 
-Adding a GUI to a module, inside `modules/{module_name}`,
-you need to add :
+1. Create the directory :  
+`/usr/share/armbian/configurator/modules/${module_name}/gui`
 
-1. **module.gui**  
-The GUI version of the module.
-2. **armbian/gui/DEPS**  
-The list of additional Debian packages required to execute `module.gui`.  
-Only put the dependencies that are not required by the **configurator**
-itself.  
-Dependencies shared with the CLI version still need to be written.
+2. Add at least the executable file to :  
+`/usr/share/armbian/configurator/modules/${module_name}/gui/module`
 
-> **Symlinking to `module.cli`**
->
-> It is possible to have a single executable managing
-> both CLI and GUI, but remember that the CLI version
-> **MUST NOT** depend on GUI libraries.  
-> For example, you cannot ask for QT/GTK/OpenGL for CLI
-> softwares.
->
-> Which mean that single executables managing CLI and
-> GUI must load GUI libraries dynamically.  
-> For scripting languages, you can branch load the
-> libraries after a few sanity checks.  
-> For compiled languages, you'll need to deal with
-> dynamically loaded libraries.
->
-> So, think again before putting both in the same executable.
-> Having two executables sharing the same configuration
-> files and codebase might be far easier.
+Then copy all the files required by the GUI into its specific folder,  
+`/usr/share/armbian/configurator/modules/${module_name}/gui`.
 
-## Adding a translation
-
-> Support for this feature will be added very soon
+## Adding a translation to the short description
 
 To add a translation for a module description,
-inside `modules/{module_name}`, create a `DESC.{locale}` file.
+add a `DESC.{locale}` file to
+`/usr/share/armbian/configurator/modules/${module_name}/`
 
 Precise locales are sampled before global ones, however
 avoid using precise locales names when you can.
@@ -91,3 +71,6 @@ if you only add `DESC.fr_FR`, the system will use :
 * `DESC.fr_FR` for people using the `fr_FR` locale.  
 * `DESC` (default english version) for people using the `fr_CA` locale.
 
+## Prepare for packaging
+
+In order to prepare the module for packaging, see **PACKAGING.md**.

docs/PACKAGING.md

@@ -49,8 +49,8 @@ generate specific packages, depending of the presence of the
 
 Meaning that, if the following directories are present :
 
-* `armbian/any/cli`
-* `armbian/any/tui`
+* `armbian/all/cli`
+* `armbian/all/tui`
 * `armbian/arm64`
 * `armbian/arm64/cli`
 * `armbian/arm64.allwiner`
@@ -59,17 +59,17 @@ Meaning that, if the following directories are present :
 
 The package will build :
 
-* A CLI package for the architecture "any".
-* A TUI package for the architecture "any".
+* A CLI package for the architecture "all".
+* A TUI package for the architecture "all".
 * A CLI package for the architecture "arm64".
 * A CLI package for the architecture "arm64", targeting AllWinner boards.
 * A GUI package for the architecture "arm64", targeting AllWinner boards.
 
-Note that the files used by the "any" package WILL NOT BE SHARED
+Note that the files used by the "all" package WILL NOT BE SHARED
 with "arm64" or "arm64.allwinner" !  
 Same thing, the CLI files from "arm64" WILL NOT BE SHARED with
 the files in the "arm64.allwinner".  
-Meaning that, in this example, if the same CLI files are used in "any",
+Meaning that, in this example, if the same CLI files are used in "all",
 "arm64" and "arm64.allwinner", they need to be COPIED OVER AND OVER,
 in each "CLI" subdirectory of each architecture.
 
@@ -89,13 +89,19 @@ In the **armbian** directory, these are the files that can used by
 the packager :
 
 * `BUILD.sh`  
-   This script must be executed by the packaging script, at
-   the root folder of the current module, in order to build
-   the module.
+   If present, script is executed by the packager, from the root folder
+   of the current module, in order to buildthe module and populate the
+   `armbian` folder.  
+   Its content will be concatenated with all the other
+   specific `BUILD.sh` found.
 
 * `DEPS.build`  
    Set of dependencies required to execute `BUILD.sh` correctly.
 
+* `DEPS_${distribution}.build`
+   Distribution specific set of dependencies, required to
+   execute `BUILD.sh` correctly.
+
 * `DESC*`  
    The short description of the module and its translations.  
    This will be installed in `/usr/share/armbian/configurator/modules/${module_name}`.  
@@ -128,6 +134,35 @@ the packager :
 Then in each architecture subdirectory, the packager can also use the
 the following files :
 
+* `BUILD.sh`  
+   This script must be executed by the packaging script, at
+   the root folder of the current module, in order to build
+   the module.  
+   Its content will be concatenated with all the other
+   specific `BUILD.sh` found.  
+   See **Build phase**
+
+* `DEPS.build`  
+   Architecture specific set of dependencies required to
+   execute `BUILD.sh` correctly.  
+   See **Build phase**
+
+* `DEPS.remove.build`  
+   Architecture specific list of packages, to remove from the
+   list of packages to install in order to build the module.  
+   See **Build phase**
+
+* `DEPS_${distribution}.build`  
+   Architecture and distribution specific set of dependencies,
+   required to execute `BUILD.sh` correctly.  
+   See **Build phase**
+
+* `DEPS_${distribution}.remove.build`  
+   Architecture and distribution specific list of packages, to
+   remove from the list of packages to install in order to build
+   the module.  
+   See **Build phase**
+
 * `DEPS`  
    Architecture specific dependencies files, that will be concatenated
    with all the specifics dependencies files.  
@@ -159,6 +194,35 @@ the following files :
 Then, in each of the "cli", "tui", "gui" subdirectories, the following files
 might be used by the packager :
 
+* `BUILD.sh`  
+   This script must be executed by the packaging script, at
+   the root folder of the current module, in order to build
+   the module.  
+   Its content will be concatenated with all the other
+   specific `BUILD.sh` found.  
+   See **Build phase**
+
+* `DEPS.build`  
+   Mode and architecture specific set of dependencies required to
+   execute `BUILD.sh` correctly.  
+   See **Build phase**
+
+* `DEPS.remove.build`  
+   Mode and architecture specific list of packages, to remove from the
+   list of packages to install in order to build the module.  
+   See **Build phase**
+
+* `DEPS_${distribution}.build`  
+   Mode, architecture and distribution specific set of dependencies
+   required to execute `BUILD.sh` correctly.  
+   See **Build phase**
+
+* `DEPS_${distribution}.remove.build`  
+   Mode, architecture and distribution specific list of packages that
+   will be removed remove from the list of packages, defined in the
+   various `DEPS.build` files.  
+   See **Build phase**
+
 * `DEPS`  
    Mode specific dependencies files. 
    See **Dependencies management** afterward.
@@ -222,30 +286,29 @@ The concatenation should be performed as follow :
 
 #### List of concatenated files
 
-So, when building the 'CLI' package for 'Ubuntu 22.04', architecture 'any', the
+So, when building the 'CLI' package for 'Ubuntu 22.04', architecture 'all', the
 following `DEPS` files will be concatenated, if they're found :
 
 * `armbian/DEPS`
-* `armbian/DEPS.ubuntu`
-* `armbian/DEPS.ubuntu_2204`
-* `armbian/any/DEPS`
-* `armbian/any/DEPS.ubuntu`
-* `armbian/any/DEPS.ubuntu_2204`
-* `armbian/any/cli/DEPS`
-* `armbian/any/cli/DEPS.ubuntu`
-* `armbian/any/cli/DEPS.ubuntu_2204`
+* `armbian/DEPS_ubuntu`
+* `armbian/DEPS_ubuntu_2204`
+* `armbian/all/DEPS`
+* `armbian/all/DEPS_ubuntu`
+* `armbian/all/DEPS_ubuntu_2204`
+* `armbian/all/cli/DEPS`
+* `armbian/all/cli/DEPS_ubuntu`
+* `armbian/all/cli/DEPS_ubuntu_2204`
 
 Then the following `DEPS.remove` files will be concatenated if they're found :
 
-* `armbian/DEPS.remove`
-* `armbian/DEPS.ubuntu.remove`
-* `armbian/DEPS.ubuntu_2204.remove`
-* `armbian/any/DEPS.remove`
-* `armbian/any/DEPS.ubuntu.remove`
-* `armbian/any/DEPS.ubuntu_2204.remove`
-* `armbian/any/cli/DEPS.remove`
-* `armbian/any/cli/DEPS.ubuntu.remove`
-* `armbian/any/cli/DEPS.ubuntu_2204.remove`
+* `armbian/DEPS_ubuntu.remove`
+* `armbian/DEPS_ubuntu_2204.remove`
+* `armbian/all/DEPS.remove`
+* `armbian/all/DEPS_ubuntu.remove`
+* `armbian/all/DEPS_ubuntu_2204.remove`
+* `armbian/all/cli/DEPS.remove`
+* `armbian/all/cli/DEPS_ubuntu.remove`
+* `armbian/all/cli/DEPS_ubuntu_2204.remove`
 
 Then, all the packages obtained through `DEPS.remove` files will be removed
 from the list `DEPS` packages.
@@ -257,7 +320,7 @@ following list :
 
 `docker docker.io docker-compose python3 libpng14 libpng16-16`
 
-Then let's say that concatenating all the `DEPS.remoev` files lead to the
+Then let's say that concatenating all the `DEPS.remove` files lead to the
 following list :
 
 `docker libpng14`
@@ -395,3 +458,133 @@ locale to `fr_FR`, then the **configurator** will show the content of
 Following, if the user changes its locale to `en_US`, then the
 **configurator** will show the content of `DESC`.
 
+### Build phase
+
+The `BUILD.sh` is OPTIONAL.  
+If present, it will be run by the packager, in order to populate
+the `armbian` directory.  
+
+The current working directory when executing the script is the
+root of the module.  
+
+If the script is present, before executing the script, the packager
+will install the list of packages resulting from the concatenation
+of `DEPS.build` and `DEPS_${distribution}.build`, mine the list of
+packages resulting from the concatenation `DEPS.remove.build` and
+`DEPS_${distribution}.remove.build` files.
+
+Failing to install any of the packages, in the final list, will
+fail the entire packaging process.
+
+#### Concatenation of the dependencies
+
+> The concatenation process is identical to the one described in
+**Dependencies management**.
+
+The concatenation should be performed as follow :
+
+* Parse the content of each file.
+* In this content :
+  * Replace each spacing character (space, tabs, newlines, ...) by a space.
+  * Replace each occurence of multiple consecutive spaces by one space.
+  * Remove leading and trailing spaces.
+* Join all the contents, using one single space character as the delimiter.
+
+#### Example
+
+So, when building the 'TUI' package for 'Debian 11', architecture 'armv7', the
+following `DEPS.build` files will be concatenated, if they're found :
+
+* `armbian/DEPS.build`
+* `armbian/DEPS_debian.build`
+* `armbian/DEPS.debian_11.build`
+* `armbian/armv7/DEPS`
+* `armbian/armv7/DEPS_debian.build`
+* `armbian/armv7/DEPS_debian_11.build`
+* `armbian/armv7/tui/DEPS`
+* `armbian/armv7/tui/DEPS_debian.build`
+* `armbian/armv7/tui/DEPS_debian_11.build`
+
+Then the following `DEPS.remove.build` files will be concatenated
+if they're found :
+
+* `armbian/DEPS_debian.remove.build`
+* `armbian/DEPS_debian_11.remove.build`
+* `armbian/armv7/DEPS.remove.build`
+* `armbian/armv7/DEPS_debian.remove.build`
+* `armbian/armv7/DEPS_debian_11.remove.build`
+* `armbian/armv7/tui/DEPS.remove.build`
+* `armbian/armv7/tui/DEPS_debian.remove.build`
+* `armbian/armv7/tui/DEPS_debian_11.remove.build`
+
+If the concatenation of the `DEPS.build` files result in the
+following list :
+
+`gcc-9 gcc-10 make python3`
+
+And the concatenation of the `DEPS.remove.build` files result in
+the following list :
+
+`gcc-9 python3`
+
+Then the final list of packages installed, before running the
+`BUILD.sh` script will be :
+
+`gcc-10 make`
+
+### Concatenation of the BUILD.sh parts
+
+> The process is identical to the one used in
+**Post installation scripts**
+
+* If any `BUILD.sh` file is present :
+  * Parse the content of each `BUILD.sh` found
+  * Prepare the following string :  
+  `#!/bin/bash`
+  * Join this string with all the other contents, using a newline
+    character as the separator ('\n`).
+
+The order of concatenation of these scripts MUST be least-specific to
+most-specific.
+
+### Example
+
+For example, when building the 'TUI' package for 'Debian 12',
+architecture 'armv7', the following `BUILD.sh` needs to be
+concatenated, if they're found :
+
+* `armbian/BUILD.sh`
+* `armbian/arm64/BUILD.sh`
+* `armbian/arm64/gui/BUILD.sh`
+
+If any of these files are found, then the following `DEPS.build` files
+need to be concatenated :
+
+* `armbian/DEPS.build`
+* `armbian/DEPS_debian.build`
+* `armbian/DEPS.debian_12.build`
+* `armbian/armv7/DEPS`
+* `armbian/armv7/DEPS_debian.build`
+* `armbian/armv7/DEPS_debian_12.build`
+* `armbian/armv7/tui/DEPS`
+* `armbian/armv7/tui/DEPS_debian.build`
+* `armbian/armv7/tui/DEPS_debian_12.build`
+
+And then the following potentials `DEPS.remove.build` need to be
+concatenated too :
+
+* `armbian/DEPS_debian.remove.build`
+* `armbian/DEPS_debian_12.remove.build`
+* `armbian/armv7/DEPS.remove.build`
+* `armbian/armv7/DEPS_debian.remove.build`
+* `armbian/armv7/DEPS_debian_12.remove.build`
+* `armbian/armv7/tui/DEPS.remove.build`
+* `armbian/armv7/tui/DEPS_debian.remove.build`
+* `armbian/armv7/tui/DEPS_debian_12.remove.build`
+
+The packages listed in the `DEPS.remove.build` are then to be removed
+from the list of packages obtainted from the `DEPS.build` files.  
+The final packages list is then installed by the packager before
+running the script resulting from the concatenation of the `BUILD.sh`
+scripts.
+

modules/docker/armbian/BUILD.sh

@@ -1,3 +1 @@
-#!/bin/bash
-
 ./install.sh

modules/docker/install.sh

@@ -15,7 +15,7 @@ UI_FILES="ui"
 PACKAGING_FILES="build/DEPS.main build/POSTINST.sh"
 
 cp ${DESC_FILES} "armbian" &&
-mkdir -p "armbian/all-archs" &&
+mkdir -p "armbian/all" &&
 cp ${PACKAGING_FILES} "armbian"
 
 [[ $? -eq 0 ]] || abort "Could copy the basic armbian dependency files"
@@ -23,13 +23,13 @@ cp ${PACKAGING_FILES} "armbian"
 for mode in ${MODES}
 do
 	mkdir -p "armbian/all-archs/${mode}/module" &&
-	cp -r ${MAIN_FILES} "armbian/all-archs/${mode}/module" &&
-	cp "module.${mode}" "armbian/all-archs/${mode}/module/module" &&
-	cp "build/DEPS.${mode}" "armbian/all-archs/${mode}"
+	cp -r ${MAIN_FILES} "armbian/all/${mode}/module" &&
+	cp "module.${mode}" "armbian/all/${mode}/module/module" &&
+	cp "build/DEPS.${mode}" "armbian/all/${mode}"
 done
 
 [[ $? -eq 0 ]] || abort "Could not copy the modules content"
 
-cp -r ${UI_FILES} "armbian/all-archs/gui/module"
+cp -r ${UI_FILES} "armbian/all/gui/module"
 
 [[ $? -eq 0 ]] || abort "Could not copy the UI files"