diff --git a/src/modules/netinstall/README.md b/src/modules/netinstall/README.md index cb6159d95..0a9db2f22 100644 --- a/src/modules/netinstall/README.md +++ b/src/modules/netinstall/README.md @@ -1,127 +1,6 @@ # Netinstall module -The netinstall module allows distribution maintainers to ship minimal ISOs with -only a basic set of preinstalled packages. At installation time, the user is -presented with the choice to install groups of packages from a predefined list. - -Calamares will then use the *packages* module to install the packages. - - -## Module Configuration - -The `netinstall.conf` file is self-describing, and at the very -least should contain a *groupsUrl* key: - -``` - ---- - groupsUrl: -``` - -The URL must point to a YAML file, the *groups* file. See below for -the format of that groups file. The URL may be a local file (e.g. -scheme `file:///`) or a regular HTTP(s) URL. The URL has one special -case: the literal string `local` is used to indicate that the groups -data is contained in the `netinstall.conf` file itself. - - -## Groups Configuration - -Here is a short example of how the YAML file should look. - -``` - - name: "Group name" - description: "Description of the group" - packages: - - lsb-release - - avahi - - grub - - name: "Second group name" - ... -``` - - -The file is composed of a list of entries, each describing one group. The -keys *name*, *description* and *packages* are required for each group. - -More keys (per group) are supported: - - - *hidden*: if true, do not show the group on the page. Defaults to false. - - *selected*: if true, display the group as selected. Defaults to false. - - *critical*: if true, make the installation process fail if installing - any of the packages in the group fails. Otherwise, just log a warning. - Defaults to false. If not set in a subgroup (see below), inherits from - the parent group. - - *immutable*: if true, the state of the group (and all its subgroups) - cannot be changed; it really only makes sense in combination - with *selected* set to true. This only affects the user-interface. - - *expanded*: if true, the group is shown in an expanded form (that is, - not-collapsed) in the treeview on start. This only affects the user- - interface. Only top-level groups are show expanded-initially. - - *immutable*: if true, the group cannot be changed (packages selected - or deselected) and no checkboxes are shown for the group. - - *subgroups*: if present this follows the same structure as the top level - of the YAML file, allowing there to be sub-groups of packages to an - arbitary depth - - *pre-install*: an optional command to run within the new system before - the group's packages are installed. It will run before each package in - the group is installed. - - *post-install*: an optional command to run within the new system after - the group's packages are installed. It will run after each package in - the group is installed. - -If you set both *hidden* and *selected* for a group, you are basically creating -a "default" group of packages which will always be installed in the user's -system. - -> The note below applies to Calamares up-to-and-including 3.2.13, but will -> change in a later release. - -The *pre-install* and *post-install* commands are **not** passed to -a shell; see the **packages** module configuration (i.e. `packages.conf`) -for details. To use a full shell pipeline, call the shell explicitly. - - - -## Overall Configuration - -Here is the set of instructions to have the module work in your Calamares. - -First, if the module is used, we need to require a working Internet connection, -otherwise the module will be unable to fetch the package groups and to perform -the installation. Requirements for the Calamares instance are configured in the -`welcome.conf` file (configuration for the **welcome** module). Make sure -*internet* is listed under the *required* checks. - -In the `settings.conf` file, decide where the **netinstall** page should be -displayed. I put it just after the **welcome** page, but any position between -that and just before **partition** should make no difference. - -If not present, add the **packages** job in the *exec* list. This is the job -that calls the package manager to install packages. Make sure it is configured -to use the correct package manager for your distribution; this is configured in -`packages.conf`. - -The *exec* list in `settings.conf` should contain the following items in -order (it's ok for other jobs to be listed inbetween them, though): - -``` - - unpackfs - - networkcfg - - packages -``` - -**unpackfs** creates the chroot where the installation is performed, and unpacks -the root image with the filesystem structure; **networkcfg** set ups a working -network in the chroot; and finally **packages** can install packages in the -chroot. - -## Common issues - -If launching the package manager command returns you negative exit statuses and -nothing is actually invoked, this is likely an error in the setup of the chroot; -check that the parameter **rootMountPoint** is set to the correct value in the -Calamares configuration. - -If the command is run, but exits with error, check that the network is -working in the chroot. Make sure `/etc/resolv.conf` exists and that -it's not empty. +All of the actual documentation of the netinstall module has moved +into the `netinstall.conf` file; since the configuration file **may** +contain the groups-and-packages list itself, that format is +also described there. diff --git a/src/modules/netinstall/netinstall.conf b/src/modules/netinstall/netinstall.conf index 5368a9edf..24f4f201d 100644 --- a/src/modules/netinstall/netinstall.conf +++ b/src/modules/netinstall/netinstall.conf @@ -1,15 +1,58 @@ +### Netinstall module +# +# The netinstall module allows distribution maintainers to ship minimal ISOs +# with only a basic set of preinstalled packages. At installation time, the +# user is presented with the choice to install groups of packages from a +# predefined list. +# +# Calamares will then use the *packages* module to install the packages. +# Without a *packages* module in the exec phase somewhere **after** +# this netinstall, nothing will actually get installed. The packages +# module must be correctly configured **and** the package manager must +# be runnable from within the installed system at the point where it +# is invoked, otherwise you'll get nothing. +# +# There are two basic deployment schemes: +# - static package lists; the packages do not change for this release. +# In this case, the package list file may be on the ISO-image itself +# as a separate file, **or** included in this configuration file. +# Either will do; separate file is easier to update independently +# of the Calamares configuration, while merged configurations use +# fewer files overall and are closer to self-documenting. +# - online package lists; the package list is fetched from a remote +# URL and handled otherwise like a static list. This can be useful +# if the package list needs updating during the lifetime of an ISO- +# image, e.g. packages are added or renamed. +# +# There is only one required key for this module, *groupsUrl*. +# +# This module supports multiple instances through the *label* key, +# which allows you to distinguish them in the UI. --- # This is the URL that is retrieved to get the netinstall groups-and-packages # data (which should be in the format described in netinstall.yaml), e.g.: -# groupsUrl: http://example.org/netinstall.php +# ``` +# groupsUrl: http://example.org/netinstall.php +# ``` # or it can be a locally installed file: -# groupsUrl: file:///usr/share/calamares/netinstall.yaml +# ``` +# groupsUrl: file:///usr/share/calamares/netinstall.yaml +# ``` +# or it can be the special-case literal string "local": +# ``` +# groupsUrl: local +# ``` # # Note that the contents of the groups file is the **important** # part of the configuration of this module. It specifies what -# the user may select and what commands are to be run. +# groups and packages the user may select (and so what commands are to +# be run to install them). # -# The format of the groups file is documented in `README.md`. +# The format of the groups file is the same as the format of the +# *groups* key described below, **except** that a stand-alone +# groups file does not have the top-level *groups* key. +# +# TODO: remove that ^^ restriction # # As a special case, setting *groupsUrl* to the literal string # `local` means that the data is obtained from **this** config @@ -24,27 +67,47 @@ groupsUrl: local # # This only has an effect if the netinstall data cannot be retrieved, # or is corrupt: having "required" set, means the install cannot proceed. +# For local or file: type *groupsUrl* settings, this setting is not +# really meaningful. required: false # To support multiple instances of this module, # some strings are configurable and translatable here. -# - *sidebar* This is the name of the module in the progress-tree / sidebar +# Sub-keys under *label* are used for the user interface. +# - *sidebar* This is the name of the module in the progress-tree / sidebar # in Calamares. -# - *title* This is displayed above the list of packages. +# - *title* This is displayed above the list of packages. # If no *sidebar* values are provided, defaults to "Package selection" # and existing translations. If no *title* values are provided, no string # is displayed. # +# Translations are handled through [cc] notation, much like in +# `.desktop` files. The string `key[cc]` is used for *key* when +# when the language *cc* (country-code, like *nl* or *en_GB*) is used. +# # The following strings are already known to Calamares and can be # listed here in *untranslated* form (e.g. as value of *sidebar*) # without bothering with the translations: they are picked up from # the regular translation framework: -# - "Package selection" -# - "Office software" -# - "Office package" -# - "Browser software" -# - "Browser package" -# - "Web browser" +# - "Package selection" +# - "Office software" +# - "Office package" +# - "Browser software" +# - "Browser package" +# - "Web browser" +# - "Kernel" +# - "Services" +# - "Login" +# - "Desktop" +# - "Applications" +# - "Communication" +# - "Development" +# - "Office" +# - "Multimedia" +# - "Internet" +# - "Theming" +# - "Gaming" +# - "Utilities" label: sidebar: "Package selection" # sidebar[nl]: "Pakketkeuze" @@ -53,12 +116,87 @@ label: # If, and only if, *groupsUrl* is set to the literal string `local`, # groups data is read from this file. The value of *groups* must be -# a list, with the same format as the regular `netinstall.yaml` file. -# See the `README.md` file in the *netinstall* module for documentation -# on the format of groups data. +# a list. Each item in the list is a group (of packages, or subgroups, +# or both). A standalone groups file contains just the list, +# without the top-level *groups* key. # -# This is recommended only for small static package lists. +# TODO: remove that restriction ^^ +# +# Using `local` is recommended only for small static package lists. +# Here it is used for documentation purposes. +# +# +### Groups Format +# +# Each item in the list describes one group. The following keys are +# required for each group: +# +# - *name* of the group; short and human-readable. Shown in the first +# column of the UI. +# - *description* of the group; longer and human-readable. Shown in the +# second column of the UI. This is one of the things that visually +# distinguishes groups (with descriptions) from packages (without). +# - *packages*, a list of packages that belong to this group. +# The items of the *packages* list are actual package names +# as passed to the package manager (e.g. `qt5-creator-dev`). +# This list may be empty (e.g. if your group contains only +# subgroups). This key isn't **really** required, either -- +# one of *subgroups* or *packages* is. +# +# The following keys are **optional** for a group: +# +# - *hidden*: if true, do not show the group on the page. Defaults to false. +# - *selected*: if true, display the group as selected. Defaults to the +# parent group's value, if there is a parent group; top-level groups +# are set to true by default. +# - *critical*: if true, make the installation process fail if installing +# any of the packages in the group fails. Otherwise, just log a warning. +# Defaults to false. If not set in a subgroup (see below), inherits from +# the parent group. +# - *immutable*: if true, the state of the group (and all its subgroups) +# cannot be changed; it really only makes sense in combination +# with *selected* set to true. This only affects the user-interface. +# - *expanded*: if true, the group is shown in an expanded form (that is, +# not-collapsed) in the treeview on start. This only affects the user- +# interface. Only top-level groups are show expanded-initially. +# - *immutable*: if true, the group cannot be changed (packages selected +# or deselected) and no checkboxes are shown for the group. +# - *subgroups*: if present this follows the same structure as the top level +# groups, allowing sub-groups of packages to an arbitary depth. +# - *pre-install*: an optional command to run within the new system before +# the group's packages are installed. It will run before **each** package in +# the group is installed. +# - *post-install*: an optional command to run within the new system after +# the group's packages are installed. It will run after **each** package in +# the group is installed. +# +# If you set both *hidden* and *selected* for a group, you are basically +# creating a "default" group of packages which will always be installed +# in the user's system. Setting *hidden* to true without *selected*, or with +# *selected* set to false, is kind of pointless. +# +# The *pre-install* and *post-install* commands are **not** passed to +# a shell; see the **packages** module configuration (i.e. `packages.conf`) +# for details. To use a full shell pipeline, call the shell explicitly. +# +# Non-critical groups are installed by calling the package manager +# individually, once for each package (and ignoring errors), while +# critical packages are installed in one single call to the package +# manager (and errors cause the installation to terminate). +# +# +# +# The *groups* key below contains some common patterns for packages +# and sub-groups, with documentation. + + groups: + # This group is hidden, so the name and description are not really + # important. Since it is selected, these packages will be installed. + # It's non-critical, so they are installed one-by-one. + # + # This is a good approach for something you want up-to-date installed + # in the target system every time. - name: "Default" description: "Default group" hidden: true @@ -67,6 +205,15 @@ groups: packages: - base - chakra-live-skel + # The Shells group contains only subgroups, no packages itself. + # The *critical* value is set for the subgroups that do not + # override it; *selected* is set to false but because one of + # the subgroups sets *selected* to true, the overall state of + # **this** group is partly-selected. + # + # Each of the sub-groups lists a bunch of packages that can + # be individually selected, so a user can pick (for instance) + # just one of the ZSH packages if they like. - name: "Shells" description: "Shells" hidden: false @@ -85,6 +232,11 @@ groups: - zsh - zsh-completion - zsh-extensions + # The kernel group has no checkbox, because it is immutable. + # It can be (manually) expanded, and the packages inside it + # will be shown, also without checkboxes. This is a way to + # inform users that something will always be installed, + # sort of like a hidden+selected group but visible. - name: "Kernel" description: "Kernel bits" hidden: false @@ -95,6 +247,7 @@ groups: - kernel - kernel-debugsym - kernel-nvidia + # *selected* defaults to true for top-level - name: Communications description: "Communications Software" packages: @@ -102,3 +255,56 @@ groups: - konversation - nheko - quaternion + # Setting *selected* is supported. + - name: Editors + description: "Editing" + selected: false + packages: + - vi + - emacs + - nano + # The "bare" package names can be intimidating, so you can use subgroups + # to provide human-readable names while hiding the packages themselves. + # This also allows you you group related packages -- suppose you feel + # that KDevelop should be installed always with PHP and Python support, + # but that support is split into multiple packages. + # + # So this subgroup (IDE) contains subgroups, one for each "package" + # we want to install. Each of those subgroups (Emacs, KDevelop) + # in turn contains **one** bogus subgroup, which then has the list + # of relevant packages. This extra-level-of-subgrouping allows us + # to list packages, while giving human-readable names. + # + # The name of the internal subgroup doesn't matter -- it is hidden + # from the user -- so we can give them all bogus names and + # descriptions, even the same name. Here, we use "bogus". + # + # Each internal subgroup is set to *hidden*, so it does not show up + # as an entry in the list, and it is set to *selected*, + # so that if you select its parent subgroup. + - name: IDE + description: "Development Environment" + selected: false + subgroups: + - name: Emacs + description: LISP environment and editor + subgroups: + - name: Bogus + description: Bogus + hidden: true + selected: true + packages: + - emacs + - name: KDevelop + description: KDE's C++, PHP and Python environment + subgroups: + - name: Bogus + description: Bogus + hidden: true + selected: true + packages: + - kdevelop + - kdevelop-dev + - kdev-php + - kdev-python + diff --git a/src/modules/netinstall/netinstall.yaml b/src/modules/netinstall/netinstall.yaml index e00f06c73..6a93d84ea 100644 --- a/src/modules/netinstall/netinstall.yaml +++ b/src/modules/netinstall/netinstall.yaml @@ -1,7 +1,15 @@ # Example configuration with groups and packages, taken from Chakra Linux. # -# This example is rather limited. See `README.md` for full documentation -# on the configuration format. +# This example is rather limited. See `netinstall.conf` for full documentation +# on the configuration format. The module configuration file `netinstall.conf` +# **may** contain the package-list, but that is only useful for static +# package-lists. If you are updating the package lists or changing the package +# offerings, an online `netinstall.yaml` is the way to go; or you can put the +# `netinstall.yaml` on the installation media and modify that, while keeping +# your Calamares configuration constant. +# +# Which approach works depends on what you want to offer and how your +# ISO-image toolchain works. - name: "Default" description: "Default group" hidden: true