Merge branch 'issue-1227'

FIXES #1227

(Well, "fixes" .. documents the situation)

src/modules/netinstall/README.md

@@ -1,86 +1,116 @@
 # Netinstall module
 
-The netinstall module allows distribution maintainers to ship minimal ISOs with only a basic set of preinstall packages.
+The netinstall module allows distribution maintainers to ship minimal ISOs with
-At installation time, the user is presented with the choice to install groups of packages from a predefined list.
+only a basic set of preinstall packages. At installation time, the user is
+presented with the choice to install groups of packages from a predefined list.
 
 Calamares will then invoke the correct backend to install the packages.
 
-## Configuration of the packages
 
-Every distribution can choose which groups to display and which packages should be in the groups.
+## Module Configuration
 
-The *netinstall.conf* file should have this format:
+The `netinstall.conf` file is self-describing, and at the very
+lease should contain a *groupsUrl* key:
 
+```
     ----
     groupsUrl: <URL to YAML file>
+```
 
-The URL must point to a YAML file. Here is a short example of how the YAML file should look.
+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.
 
-      - name: "Group name"
+
-        description: "Description of the group"
+## Groups Configuration
-        packages:
+
-          - lsb-release
+ Here is a short example
-          - avahi
+of how the YAML file should look.
-          - grub
+
-      - name: "Second group name"
+```
+    - 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 entry, each describing one group. The keys *name*, *description* and *packages* are required.
+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 are supported:
+More keys (per group) are supported:
 
-      - hidden: if true, do not show the group on the page. Defaults to false.
+ - *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.
+ - *selected*: if true, display the group as selected. Defaults to false.
-      - critical: if true, make the installation process fail if installing
+ - critical*: if true, make the installation process fail if installing
-        any of the packages in the group fails. Otherwise, just log a warning.
+   any of the packages in the group fails. Otherwise, just log a warning.
-        Defaults to false.
+   Defaults to false.
-      - subgroups: if present this follows the same structure as the top level
+ - *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
+   of the YAML file, allowing there to be sub-groups of packages to an
-        arbitary depth
+   arbitary depth
-      - pre-install: an optional command to run within the new system before
+ - *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's packages are installed. It will run before each package in
-        the group is installed.
+   the group is installed.
-      - post-install: an optional command to run within the new system after
+ - *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's packages are installed. It will run after each package in
-        the group is installed.
+   the group is installed.
 
-If you set both *hidden* and *selected* for a group, you are basically creating a "default" group of packages
+If you set both *hidden* and *selected* for a group, you are basically creating
-which will always be installed in the user's system.
+a "default" group of packages which will always be installed in the user's
+system.
 
-## Configuration of the module
+> The note below applies to Calamares up-to-and-including 3.2.13, but will
+> change in a later release.
 
-Here is the set of instructions to have the module work in your Calamares. As of July 2016, this has been successfully
+The *pre-install* and *post-install* commands are **not** passed to
-tested using the live installation of Chakra Fermi.
+a shell; see the **packages** module configuration (i.e. `packages.conf`)
+for details. To use a full shell pipeline, call the shell explicitly.
 
-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 below *required*.
 
-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
+## Overall Configuration
-to install packages. Make sure it is configured to use the correct package manager for your distribution; this
-is configured in src/modules/packages/packages.conf.
 
-The **exec** list in *settings.conf* should contain the following items in
+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
+**unpackfs** creates the chroot where the installation is performed, and unpacks
-structure; **networkcfg** set ups a working network in the chroot; and finally **packages** can install packages
+the root image with the filesystem structure; **networkcfg** set ups a working
-in the chroot.
+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
+If launching the package manager command returns you negative exit statuses and
-is likely an error in the setup of the chroot; check that the parameter **rootMountPoint** is set to the correct
+nothing is actually invoked, this is likely an error in the setup of the chroot;
-value in the Calamares configuration.
+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
+If the command is run, but exits with error, check that the network is
-exists and that it's not empty.
+working in the chroot. Make sure `/etc/resolv.conf` exists and that
+it's not empty.

src/modules/netinstall/netinstall.conf

@@ -4,6 +4,13 @@
 #   groupsUrl: http://example.org/netinstall.php
 # or it can be a locally installed file:
 #   groupsUrl: file:///usr/share/calamares/netinstall.yaml
+#
+# Note that the contents of the groups file is the **inmportant**
+# part of the configuration of this module. It specifies what
+# the user may select and what commands are to be run.
+#
+# The format of the groups file is documented in `README.md`.
+#
 # groupsUrl: file:///usr/share/calamares/netinstall.yaml
 
 # If the installation can proceed without netinstall (e.g. the Live CD

src/modules/netinstall/netinstall.yaml

@@ -1,3 +1,7 @@
+# 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.
 - name: "Default"
   description: "Default group"
   hidden: true

src/modules/packages/packages.conf

@@ -31,9 +31,9 @@ backend: dummy
 #
 # Set "update_db" to 'true' for refreshing the database on the
 # target system. On target installations, which got installed by
-# unsquashing, a full system update may be needed. Otherwise 
+# unsquashing, a full system update may be needed. Otherwise
 # post-installing additional packages may result in conflicts.
-# Therefore set also "update_system" to 'true'. 
+# Therefore set also "update_system" to 'true'.
 #
 skip_if_no_internet: false
 update_db: true
@@ -87,9 +87,25 @@ update_system: false
 #     pre-script: touch /tmp/installing-vi
 #     post-script: rm -f /tmp/installing-vi
 #
-# The pre- and post-scripts are optional, but you cannot leave both out: using
+# The pre- and post-scripts are optional, but you cannot leave both out
-# "package: vi" with neither script option will trick Calamares into
+# if you do use the *package* key: using "package: vi" with neither script
-# trying to install a package named "package: vi", which is unlikely to work.
+# option will trick Calamares into trying to install a package named
+# "package: vi", which is unlikely to work.
+#
+# The pre- and post-scripts are **not** executed by a shell unless you
+# explicitly invoke `/bin/sh` in them. The command-lines are passed
+# to exec(), which does not understand shell syntax. In other words:
+#
+#     pre-script: ls | wc -l
+#
+# Will fail, because `|` is passed as a command-line argument to ls,
+# as are `wc`, and `-l`. No shell pipeline is set up, and ls is likely
+# to complain. Invoke the shell explicitly:
+#
+#     pre-script: /bin/sh -c \"ls | wc -l\"
+#
+# The above note on shell-expansion applies to versions up-to-and-including
+# Calamares 3.2.12, but will change in future.
 #
 # Any package name may be localized; this is used to install localization
 # packages for software based on the selected system locale. By including
@@ -104,7 +120,7 @@ update_system: false
 #
 # Take care that just plain `LOCALE` will not be replaced, so `foo-LOCALE` will
 # be left unchanged, while `foo-$LOCALE` will be changed. However, `foo-LOCALE`
-# **will** be removed from the list of packages (i.e. not installed), if 
+# **will** be removed from the list of packages (i.e. not installed), if
 # English is selected. If a non-English locale is selected, then `foo-LOCALE`
 # will be installed, unchanged (no language-name-substitution occurs).
 #