This repository contains the default official module repository for BlueBuild. See ./modules/ for the module source code. See the website for module documentation. See How to make a custom module and Contributing for help with making custom modules and contributing.
These are general guidelines for writing official bash modules and their documentation to follow in order to keep a consistent style. Not all of these are to be mindlessly followed, especially the ones about grammar and writing style, but it's good to keep these in mind if you intend to contribute back upstream, so that your module doesn't feel out of place.
Module-maintainer: Maintainer of a BlueBuild bash module. The intended audience of this section of the documentation.
Image-maintainer: Maintainer of a custom image that uses BlueBuild.
Local-user: User of a custom image using the BlueBuild bash module. The image-maintainer is usually a local-user too.
Build-time modules: Modules that perform its functionality when image is building.
Boot-time modules: Modules that perform its functionality when system is booting or after system is booted.
snake_case
for functions and variables changed by the code.SCREAMING_SNAKE_CASE
for variables that are set once and stay unchanged."${variable_name}"
when you want to expose information from the variable & to ensure that variables are properly parsed as strings."${variable_name}"
, you should do that in this format: "prefix-${variable_name}-suffix"
set -euo pipefail
at the start of the script, to ensure that module will fail the image build if error is caught.
set -euxo pipefail
during debugging, where each executed command is printed. This should not be used in a published module. Every public module should have a module.yml
(reference) file for metadata and a README.md
file for an in-depth description.
For the documentation of the module in README.md
, the following guidelines apply:
/path/to/system/folder/
or config/folder-in-user-repo/
. When not talking about directories, do not postfix the file path with a slash, i.e. /path/to/system/file
.For the short module description (shortdesc:
), the following guidelines apply:
[!IMPORTANT]
Build-time modules are preferred over boot-time modules for better system reliability.
Only implement boot-time modules when build-time modules are impossible to implement for achieving desired functionality.
Boot-time modules: Modules that perform its functionality when system is booting or after system is booted.
Local module config is used to allow local-users to see & change the behavior of the boot-time module, in order to improve local-user experience.
Example of the boot-time module which satisfies the requirements & implements this functionality: default-flatpaks
Requirements for local module configs exist, as not all modules need this functionality.
Following conditions for approved local module config implementation are:
recipe.yml
.rpm-ostree
& akmods
modules, which are better utilized as build-time modules.default-flatpaks
module can remove a flatpak app, which local-user used daily.In order to keep config files easy to read & reliable to parse, standardized .yml
markup format is used.
yq
tool is used to process .yml
configs in order to reach the desired goal.
System config:
/usr/share/bluebuild/module-name/config.yml
System config is a module config which is derived from recipe.yml
module entry. It is placed in this read-only directory location in order to avoid local-users writing to it. So it is used to inform local-users about which modifications are done in recipe.yml
, so they can potentially proceed with modifications on their own.
Local-user config:
/usr/etc/bluebuild/module-name/config.yml
Local-user config is a module config which is derived from local-user config template. It is placed in /usr/etc
, which is then automatically copied to /etc
, which is writable to local-users. /usr/etc
local-user config can be used to reset module config that is done in /etc
.
System & local-user config is not there just for users, it is also directly utilized by the module, which reads the config.yml
file & further parses the data to allow the module to have local config functionality.
System config (/usr/share/bluebuild/default-flatpaks/config.yml
):
# Information about the config file
#
# vendor: BlueBuild
# module: default-flatpaks
# description: System config file for `default-flatpaks` BlueBuild module, which is used to install + remove flatpak apps or modify flatpak repos.
# instructions: Read this system config in order to know what is currently configured by the system & what to potentially modify in local-user config (/etc/bluebuild/default-flatpaks/config.yml).
# Configuration section
notify: true
system:
install:
- org.gnome.Boxes
- org.gnome.Calculator
- org.gnome.Calendar
- org.gnome.Snapshot
- org.gnome.Contacts
user:
install:
- org.gnome.World.Secrets
Local-user config (/etc/bluebuild/default-flatpaks/config.yml
):
# Information about the config file
#
# vendor: BlueBuild
# module: default-flatpaks
# description: Local-user config file for `default-flatpaks` BlueBuild module, which is used to install + remove flatpak apps or modify flatpak repos.
# instructions: Template of all supported options is in a example below. Modify the options you need & set "active" key to true.
# Configuration section
active: false
notify: true # possible options: true/false
system:
repo-url: https://dl.flathub.org/repo/flathub.flatpakrepo
repo-name: flathub-system
repo-title: "Flathub (System)" # Optional; this sets the remote's user-facing name in graphical frontends like GNOME Software
install:
- org.gnome.Boxes
- org.gnome.Calculator
- org.gnome.Calendar
- org.gnome.Snapshot
- org.gnome.Contacts
remove:
- org.gnome.TextEditor
user:
repo-url: https://dl.flathub.org/repo/flathub.flatpakrepo
repo-name: flathub-user
repo-title: "Flathub (User)" # Optional; this sets the remote's user-facing name in graphical frontends like GNOME Software
install:
- org.gnome.World.Secrets
remove:
- org.gnome.Contacts