[PATCH v2] docs: Add fuller accounting of make check prerequisites

[PATCH v2] docs: Add fuller accounting of make check prerequisites

[Glenn Washburn]

Many of the prerequisites for exercising the full `make check' test suite
have not been documented. This adds them along with a note that some tests
require elevated privileges to run.

Also add documentation on trusted sources for finding cross compiling tool
chains.

Signed-off-by: Glenn Washburn <development@efficientek.com>
---
Changes since v1

* Add section on where to find cross compiling tool chains per Daniel's request.
* Missed needed modules loop and we need fuse for ntfs and exfat (though on
  very recent kernels the exfat module would be better to use).
* Also, romfs, isofs, and squashfs are not required either because we don't
  mount or use these images in loopback devices.
* Need exfat-fuse for all but recent kernels. And exfatprogs is better
  than exfat-utils (more compete support). But its a newer package, so
  may not be available on older systems. 
* g++ package is needed to build some tests.
* Gawk is not strictly needed, in that testing will work, but the process
  will complain without it.

---
Interdiff against v1:
  diff --git a/INSTALL b/INSTALL
  index 25e3740ff..bb086a902 100644
  --- a/INSTALL
  +++ b/INSTALL
  @@ -46,6 +46,11 @@ need the following.
   * Autoconf 2.63 or later
   * Automake 1.11 or later
   
  +Cross compiling tool chains can be found at the following trusted sites:
  +
  +* https://mirrors.kernel.org/pub/tools/crosstool/
  +* https://toolchains.bootlin.com/
  +
   Prerequisites for make-check:
   
   * qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
  @@ -57,14 +62,17 @@ Prerequisites for make-check:
   * mtools, FAT tools for EFI platforms
   
   * If running a Linux kernel the following modules must be loaded:
  -  - minix, hfs, mac-roman, hfsplus, exfat, reiserfs, xfs, f2fs, btrfs,
  -    nilfs2, jfs, fat, ext4, udf, romfs, isofs, squashfs
  +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
  +    nilfs2, jfs, fat, ext4, udf
  +  - On newer kernels, the exfat kernel modules may be used instead of the
  +    exfat FUSE filesystem.
   * The following are debian named packages required mostly for the full
     suite of filesystem testing (but some are needed by other tests as well
     - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
  -    zfs-fuse, dosfstools, exfat-utils, ntfs-3g, e2fsprogs, btrfs-progs,
  +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
       xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
  -    nilfs-tools, f2fs-tools, genromfs, attr
  +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
  +  - exfat-fuse, if not using the exfat kernel module
   
   Note that `make check' will run and many tests may complete successfully
   with only a subset of these prerequisites. However, some tests may be

 INSTALL | 32 ++++++++++++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/INSTALL b/INSTALL
index 5e152b71f..bb086a902 100644
--- a/INSTALL
+++ b/INSTALL
@@ -46,10 +46,37 @@ need the following.
 * Autoconf 2.63 or later
 * Automake 1.11 or later
 
+Cross compiling tool chains can be found at the following trusted sites:
+
+* https://mirrors.kernel.org/pub/tools/crosstool/
+* https://toolchains.bootlin.com/
+
 Prerequisites for make-check:
 
-* qemu, specifically the binary 'qemu-system-i386'
+* qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
+  architecture GRUB has been built for
+* OVMF, for EFI platforms
+* OpenBIOS, for ieee1275 platforms
 * xorriso 1.2.9 or later, for grub-mkrescue and grub-shell
+* wamerican, for grub-fs-tester
+* mtools, FAT tools for EFI platforms
+
+* If running a Linux kernel the following modules must be loaded:
+  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
+    nilfs2, jfs, fat, ext4, udf
+  - On newer kernels, the exfat kernel modules may be used instead of the
+    exfat FUSE filesystem.
+* The following are debian named packages required mostly for the full
+  suite of filesystem testing (but some are needed by other tests as well
+  - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
+    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
+    xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
+    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
+  - exfat-fuse, if not using the exfat kernel module
+
+Note that `make check' will run and many tests may complete successfully
+with only a subset of these prerequisites. However, some tests may be
+skipped or fail due to missing prerequisites.
 
 Configuring the GRUB
 ====================
@@ -101,7 +128,8 @@ The simplest way to compile this package is:
   6. Type `make' to compile the package.
 
   7. Optionally, type `make check' to run any self-tests that come with
-     the package.
+     the package.  Note that many of the tests require root privileges in
+     order to run.
 
   8. Type `make install' to install the programs and any data files and
      documentation.
-- 
2.27.0

Re: [PATCH v2] docs: Add fuller accounting of make check prerequisites

[Daniel Kiper]

On Tue, Oct 05, 2021 at 12:45:04AM -0500, Glenn Washburn wrote:
> Many of the prerequisites for exercising the full `make check' test suite

I would prefer if you are more consistent and use "" instead of `' or '' everywhere.

> have not been documented. This adds them along with a note that some tests
> require elevated privileges to run.
>
> Also add documentation on trusted sources for finding cross compiling tool
> chains.
>
> Signed-off-by: Glenn Washburn <development@efficientek.com>
> ---
> Changes since v1
>
> * Add section on where to find cross compiling tool chains per Daniel's request.
> * Missed needed modules loop and we need fuse for ntfs and exfat (though on
>   very recent kernels the exfat module would be better to use).
> * Also, romfs, isofs, and squashfs are not required either because we don't
>   mount or use these images in loopback devices.
> * Need exfat-fuse for all but recent kernels. And exfatprogs is better
>   than exfat-utils (more compete support). But its a newer package, so
>   may not be available on older systems.
> * g++ package is needed to build some tests.
> * Gawk is not strictly needed, in that testing will work, but the process
>   will complain without it.
>
> ---
> Interdiff against v1:
>   diff --git a/INSTALL b/INSTALL
>   index 25e3740ff..bb086a902 100644
>   --- a/INSTALL
>   +++ b/INSTALL
>   @@ -46,6 +46,11 @@ need the following.
>    * Autoconf 2.63 or later
>    * Automake 1.11 or later
>
>   +Cross compiling tool chains can be found at the following trusted sites:
>   +
>   +* https://mirrors.kernel.org/pub/tools/crosstool/
>   +* https://toolchains.bootlin.com/
>   +
>    Prerequisites for make-check:
>
>    * qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
>   @@ -57,14 +62,17 @@ Prerequisites for make-check:
>    * mtools, FAT tools for EFI platforms
>
>    * If running a Linux kernel the following modules must be loaded:
>   -  - minix, hfs, mac-roman, hfsplus, exfat, reiserfs, xfs, f2fs, btrfs,
>   -    nilfs2, jfs, fat, ext4, udf, romfs, isofs, squashfs
>   +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
>   +    nilfs2, jfs, fat, ext4, udf
>   +  - On newer kernels, the exfat kernel modules may be used instead of the
>   +    exfat FUSE filesystem.
>    * The following are debian named packages required mostly for the full
>      suite of filesystem testing (but some are needed by other tests as well
>      - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
>   -    zfs-fuse, dosfstools, exfat-utils, ntfs-3g, e2fsprogs, btrfs-progs,
>   +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
>        xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
>   -    nilfs-tools, f2fs-tools, genromfs, attr
>   +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
>   +  - exfat-fuse, if not using the exfat kernel module
>
>    Note that `make check' will run and many tests may complete successfully
>    with only a subset of these prerequisites. However, some tests may be
>
>  INSTALL | 32 ++++++++++++++++++++++++++++++--
>  1 file changed, 30 insertions(+), 2 deletions(-)
>
> diff --git a/INSTALL b/INSTALL
> index 5e152b71f..bb086a902 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -46,10 +46,37 @@ need the following.
>  * Autoconf 2.63 or later
>  * Automake 1.11 or later
>

I think you should add a sentence at the beginning of the file that packages
names are for Debian X and can be different for other distros.

> +Cross compiling tool chains can be found at the following trusted sites:

Could you list names of cross compiling packages for Debian X too?
I know at least gcc-aarch64-linux-gnu, gcc-arm-linux-gnueabihf,
gcc-mipsel-linux-gnu and mingw-w64.

The sites below should be listed as an option if the cross compilers are
not available for some architectures in a given distro.

> +* https://mirrors.kernel.org/pub/tools/crosstool/
> +* https://toolchains.bootlin.com/
> +
>  Prerequisites for make-check:
>
> -* qemu, specifically the binary 'qemu-system-i386'
> +* qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the

Again, could you name relevant qemu packages...

> +  architecture GRUB has been built for
> +* OVMF, for EFI platforms

IIRC the packages are called simply "ovmf" for amd64 and "ovmf-ia32" for x86.

> +* OpenBIOS, for ieee1275 platforms

Could name OpenBIOS package?

>  * xorriso 1.2.9 or later, for grub-mkrescue and grub-shell
> +* wamerican, for grub-fs-tester
> +* mtools, FAT tools for EFI platforms
> +
> +* If running a Linux kernel the following modules must be loaded:
> +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
> +    nilfs2, jfs, fat, ext4, udf
> +  - On newer kernels, the exfat kernel modules may be used instead of the
> +    exfat FUSE filesystem.
> +* The following are debian named packages required mostly for the full
> +  suite of filesystem testing (but some are needed by other tests as well
> +  - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
> +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
> +    xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
> +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
> +  - exfat-fuse, if not using the exfat kernel module

I am OK with the grouping but I would prefer if you sort the names of
packages in alphabetical order in each group.

Daniel

Re: [PATCH v2] docs: Add fuller accounting of make check prerequisites

[Glenn Washburn]

On Tue, 5 Oct 2021 18:08:10 +0200
Daniel Kiper <dkiper@net-space.pl> wrote:

> On Tue, Oct 05, 2021 at 12:45:04AM -0500, Glenn Washburn wrote:
> > Many of the prerequisites for exercising the full `make check' test suite
> 
> I would prefer if you are more consistent and use "" instead of `' or '' everywhere.

I was following a pre-existing convention from the INSTALL file itself.
I generally prefer '' because its easier and more natural for me. I'll
update to use ''.

> > have not been documented. This adds them along with a note that some tests
> > require elevated privileges to run.
> >
> > Also add documentation on trusted sources for finding cross compiling tool
> > chains.
> >
> > Signed-off-by: Glenn Washburn <development@efficientek.com>
> > ---
> > Changes since v1
> >
> > * Add section on where to find cross compiling tool chains per Daniel's request.
> > * Missed needed modules loop and we need fuse for ntfs and exfat (though on
> >   very recent kernels the exfat module would be better to use).
> > * Also, romfs, isofs, and squashfs are not required either because we don't
> >   mount or use these images in loopback devices.
> > * Need exfat-fuse for all but recent kernels. And exfatprogs is better
> >   than exfat-utils (more compete support). But its a newer package, so
> >   may not be available on older systems.
> > * g++ package is needed to build some tests.
> > * Gawk is not strictly needed, in that testing will work, but the process
> >   will complain without it.
> >
> > ---
> > Interdiff against v1:
> >   diff --git a/INSTALL b/INSTALL
> >   index 25e3740ff..bb086a902 100644
> >   --- a/INSTALL
> >   +++ b/INSTALL
> >   @@ -46,6 +46,11 @@ need the following.
> >    * Autoconf 2.63 or later
> >    * Automake 1.11 or later
> >
> >   +Cross compiling tool chains can be found at the following trusted sites:
> >   +
> >   +* https://mirrors.kernel.org/pub/tools/crosstool/
> >   +* https://toolchains.bootlin.com/
> >   +
> >    Prerequisites for make-check:
> >
> >    * qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
> >   @@ -57,14 +62,17 @@ Prerequisites for make-check:
> >    * mtools, FAT tools for EFI platforms
> >
> >    * If running a Linux kernel the following modules must be loaded:
> >   -  - minix, hfs, mac-roman, hfsplus, exfat, reiserfs, xfs, f2fs, btrfs,
> >   -    nilfs2, jfs, fat, ext4, udf, romfs, isofs, squashfs
> >   +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
> >   +    nilfs2, jfs, fat, ext4, udf
> >   +  - On newer kernels, the exfat kernel modules may be used instead of the
> >   +    exfat FUSE filesystem.
> >    * The following are debian named packages required mostly for the full
> >      suite of filesystem testing (but some are needed by other tests as well
> >      - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
> >   -    zfs-fuse, dosfstools, exfat-utils, ntfs-3g, e2fsprogs, btrfs-progs,
> >   +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
> >        xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
> >   -    nilfs-tools, f2fs-tools, genromfs, attr
> >   +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
> >   +  - exfat-fuse, if not using the exfat kernel module
> >
> >    Note that `make check' will run and many tests may complete successfully
> >    with only a subset of these prerequisites. However, some tests may be
> >
> >  INSTALL | 32 ++++++++++++++++++++++++++++++--
> >  1 file changed, 30 insertions(+), 2 deletions(-)
> >
> > diff --git a/INSTALL b/INSTALL
> > index 5e152b71f..bb086a902 100644
> > --- a/INSTALL
> > +++ b/INSTALL
> > @@ -46,10 +46,37 @@ need the following.
> >  * Autoconf 2.63 or later
> >  * Automake 1.11 or later
> >
> 
> I think you should add a sentence at the beginning of the file that packages
> names are for Debian X and can be different for other distros.

Sure, I can do that. Perhaps this sentence will suffice:

  Where this document refers to packages names, they are named
  according to the Debian 11 package repositories.

> > +Cross compiling tool chains can be found at the following trusted sites:
> 
> Could you list names of cross compiling packages for Debian X too?
> I know at least gcc-aarch64-linux-gnu, gcc-arm-linux-gnueabihf,
> gcc-mipsel-linux-gnu and mingw-w64.

I am not familiar with such packages nor have any experience in using
them. I don't feel comfortable adding them. I can add something saying
that "your distro may provide you with cross compiling packages and if
not the following are reputable sites from which to get pre-built
cross compiling tool chains." If you have experience in this area feel
free to modify the patch as you deem fit and add yourself as coauthor.

> The sites below should be listed as an option if the cross compilers are
> not available for some architectures in a given distro.

Personally, I think listing these is fine as is.

> 
> > +* https://mirrors.kernel.org/pub/tools/crosstool/
> > +* https://toolchains.bootlin.com/
> > +
> >  Prerequisites for make-check:
> >
> > -* qemu, specifically the binary 'qemu-system-i386'
> > +* qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
> 
> Again, could you name relevant qemu packages...

The package qemu-system pulls in the mains ones: qemu-system-arm,
qemu-system-mips, qemu-system-ppc, qemu-system-sparc, qemu-system-x86,
and qemu-system-misc. I don't think we need to cater to the segment of
people who can't figure out how to use the package manager (search for
qemu packages and find the appropriate one). It might be worth
mentioning that the 'qemu-system' package pulls in all qemu-system
architectures.

> 
> > +  architecture GRUB has been built for
> > +* OVMF, for EFI platforms
> 
> IIRC the packages are called simply "ovmf" for amd64 and "ovmf-ia32" for x86.

OVNM is not a package name, its a project name, just as Autoconf above
is not a package name. I can append "(eg. Debian packages ovmf,
ovmf-ia32, qemu-efi-arm, and qemu-efi-aarch64)".

> 
> > +* OpenBIOS, for ieee1275 platforms
> 
> Could name OpenBIOS package?

Again, this is the project name. Debian package names would be
openbios-ppc and openbios-sparc.

> 
> >  * xorriso 1.2.9 or later, for grub-mkrescue and grub-shell
> > +* wamerican, for grub-fs-tester
> > +* mtools, FAT tools for EFI platforms
> > +
> > +* If running a Linux kernel the following modules must be loaded:
> > +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
> > +    nilfs2, jfs, fat, ext4, udf
> > +  - On newer kernels, the exfat kernel modules may be used instead of the
> > +    exfat FUSE filesystem.
> > +* The following are debian named packages required mostly for the full
> > +  suite of filesystem testing (but some are needed by other tests as well
> > +  - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
> > +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
> > +    xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
> > +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
> > +  - exfat-fuse, if not using the exfat kernel module
> 
> I am OK with the grouping but I would prefer if you sort the names of
> packages in alphabetical order in each group.

By grouping you mean how tar and cpio are grouped and gzip, lzop, and
xz-utils are grouped? Or is that all considered one group? They are
partially ordered, but not lexographically sorted.

Glenn

Re: [PATCH v2] docs: Add fuller accounting of make check prerequisites

[Daniel Kiper]

On Fri, Oct 08, 2021 at 01:10:07PM -0500, Glenn Washburn wrote:
> On Tue, 5 Oct 2021 18:08:10 +0200
> Daniel Kiper <dkiper@net-space.pl> wrote:
>
> > On Tue, Oct 05, 2021 at 12:45:04AM -0500, Glenn Washburn wrote:
> > > Many of the prerequisites for exercising the full `make check' test suite
> >
> > I would prefer if you are more consistent and use "" instead of `' or '' everywhere.
>
> I was following a pre-existing convention from the INSTALL file itself.
> I generally prefer '' because its easier and more natural for me. I'll
> update to use ''.

OK, I understand you are native English speaker. Am I right? So, could
you explain to me a difference between "", `' and '' for you guys?

> > > have not been documented. This adds them along with a note that some tests
> > > require elevated privileges to run.
> > >
> > > Also add documentation on trusted sources for finding cross compiling tool
> > > chains.
> > >
> > > Signed-off-by: Glenn Washburn <development@efficientek.com>
> > > ---
> > > Changes since v1
> > >
> > > * Add section on where to find cross compiling tool chains per Daniel's request.
> > > * Missed needed modules loop and we need fuse for ntfs and exfat (though on
> > >   very recent kernels the exfat module would be better to use).
> > > * Also, romfs, isofs, and squashfs are not required either because we don't
> > >   mount or use these images in loopback devices.
> > > * Need exfat-fuse for all but recent kernels. And exfatprogs is better
> > >   than exfat-utils (more compete support). But its a newer package, so
> > >   may not be available on older systems.
> > > * g++ package is needed to build some tests.
> > > * Gawk is not strictly needed, in that testing will work, but the process
> > >   will complain without it.
> > >
> > > ---
> > > Interdiff against v1:
> > >   diff --git a/INSTALL b/INSTALL
> > >   index 25e3740ff..bb086a902 100644
> > >   --- a/INSTALL
> > >   +++ b/INSTALL
> > >   @@ -46,6 +46,11 @@ need the following.
> > >    * Autoconf 2.63 or later
> > >    * Automake 1.11 or later
> > >
> > >   +Cross compiling tool chains can be found at the following trusted sites:
> > >   +
> > >   +* https://mirrors.kernel.org/pub/tools/crosstool/
> > >   +* https://toolchains.bootlin.com/
> > >   +
> > >    Prerequisites for make-check:
> > >
> > >    * qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
> > >   @@ -57,14 +62,17 @@ Prerequisites for make-check:
> > >    * mtools, FAT tools for EFI platforms
> > >
> > >    * If running a Linux kernel the following modules must be loaded:
> > >   -  - minix, hfs, mac-roman, hfsplus, exfat, reiserfs, xfs, f2fs, btrfs,
> > >   -    nilfs2, jfs, fat, ext4, udf, romfs, isofs, squashfs
> > >   +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
> > >   +    nilfs2, jfs, fat, ext4, udf
> > >   +  - On newer kernels, the exfat kernel modules may be used instead of the
> > >   +    exfat FUSE filesystem.
> > >    * The following are debian named packages required mostly for the full
> > >      suite of filesystem testing (but some are needed by other tests as well
> > >      - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
> > >   -    zfs-fuse, dosfstools, exfat-utils, ntfs-3g, e2fsprogs, btrfs-progs,
> > >   +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
> > >        xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
> > >   -    nilfs-tools, f2fs-tools, genromfs, attr
> > >   +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
> > >   +  - exfat-fuse, if not using the exfat kernel module
> > >
> > >    Note that `make check' will run and many tests may complete successfully
> > >    with only a subset of these prerequisites. However, some tests may be
> > >
> > >  INSTALL | 32 ++++++++++++++++++++++++++++++--
> > >  1 file changed, 30 insertions(+), 2 deletions(-)
> > >
> > > diff --git a/INSTALL b/INSTALL
> > > index 5e152b71f..bb086a902 100644
> > > --- a/INSTALL
> > > +++ b/INSTALL
> > > @@ -46,10 +46,37 @@ need the following.
> > >  * Autoconf 2.63 or later
> > >  * Automake 1.11 or later
> > >
> >
> > I think you should add a sentence at the beginning of the file that packages
> > names are for Debian X and can be different for other distros.
>
> Sure, I can do that. Perhaps this sentence will suffice:
>
>   Where this document refers to packages names, they are named
>   according to the Debian 11 package repositories.

Works for me!

> > > +Cross compiling tool chains can be found at the following trusted sites:
> >
> > Could you list names of cross compiling packages for Debian X too?
> > I know at least gcc-aarch64-linux-gnu, gcc-arm-linux-gnueabihf,
> > gcc-mipsel-linux-gnu and mingw-w64.
>
> I am not familiar with such packages nor have any experience in using
> them. I don't feel comfortable adding them. I can add something saying
> that "your distro may provide you with cross compiling packages and if
> not the following are reputable sites from which to get pre-built
> cross compiling tool chains." If you have experience in this area feel
> free to modify the patch as you deem fit and add yourself as coauthor.

If you do not want or what not to look for more cross compilers packages
in the Debian 11 just put the list which I gave you. You can say that it
can be incomplete...

> > The sites below should be listed as an option if the cross compilers are
> > not available for some architectures in a given distro.
>
> Personally, I think listing these is fine as is.

...and more cross compilers can be found at the sites mentioned below...

> > > +* https://mirrors.kernel.org/pub/tools/crosstool/
> > > +* https://toolchains.bootlin.com/
> > > +
> > >  Prerequisites for make-check:
> > >
> > > -* qemu, specifically the binary 'qemu-system-i386'
> > > +* qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
> >
> > Again, could you name relevant qemu packages...
>
> The package qemu-system pulls in the mains ones: qemu-system-arm,
> qemu-system-mips, qemu-system-ppc, qemu-system-sparc, qemu-system-x86,
> and qemu-system-misc. I don't think we need to cater to the segment of
> people who can't figure out how to use the package manager (search for
> qemu packages and find the appropriate one). It might be worth
> mentioning that the 'qemu-system' package pulls in all qemu-system
> architectures.

I am fine with listing qemu-system package and saying that it pulls in
all supported QEMU architectures on Debian 11.

> > > +  architecture GRUB has been built for
> > > +* OVMF, for EFI platforms
> >
> > IIRC the packages are called simply "ovmf" for amd64 and "ovmf-ia32" for x86.
>
> OVNM is not a package name, its a project name, just as Autoconf above

Yeah, I know but giving packages names ease people life. Then they do
not need to guess them and just put their names into the installer.

> is not a package name. I can append "(eg. Debian packages ovmf,
> ovmf-ia32, qemu-efi-arm, and qemu-efi-aarch64)".

Yeah, that would be nice...

> > > +* OpenBIOS, for ieee1275 platforms
> >
> > Could name OpenBIOS package?
>
> Again, this is the project name. Debian package names would be
> openbios-ppc and openbios-sparc.

Please list them. This can be helpful for people...

> > >  * xorriso 1.2.9 or later, for grub-mkrescue and grub-shell
> > > +* wamerican, for grub-fs-tester
> > > +* mtools, FAT tools for EFI platforms
> > > +
> > > +* If running a Linux kernel the following modules must be loaded:
> > > +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
> > > +    nilfs2, jfs, fat, ext4, udf
> > > +  - On newer kernels, the exfat kernel modules may be used instead of the
> > > +    exfat FUSE filesystem.
> > > +* The following are debian named packages required mostly for the full
> > > +  suite of filesystem testing (but some are needed by other tests as well
> > > +  - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
> > > +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
> > > +    xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
> > > +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
> > > +  - exfat-fuse, if not using the exfat kernel module
> >
> > I am OK with the grouping but I would prefer if you sort the names of
> > packages in alphabetical order in each group.
>
> By grouping you mean how tar and cpio are grouped and gzip, lzop, and
> xz-utils are grouped? Or is that all considered one group? They are

I consider "tar, ... gawk" as a group. Or bullet point if you prefer but
here there is a dash instead of bullet... :-) Dash point? :-)

> partially ordered, but not lexographically sorted.

I was thinking about alphabetical/lexicographical ordering in a given
bullet point.

Daniel

Re: [PATCH v2] docs: Add fuller accounting of make check prerequisites

[Glenn Washburn]

On Mon, 11 Oct 2021 17:27:19 +0200
Daniel Kiper <dkiper@net-space.pl> wrote:

> On Fri, Oct 08, 2021 at 01:10:07PM -0500, Glenn Washburn wrote:
> > On Tue, 5 Oct 2021 18:08:10 +0200
> > Daniel Kiper <dkiper@net-space.pl> wrote:
> >
> > > On Tue, Oct 05, 2021 at 12:45:04AM -0500, Glenn Washburn wrote:
> > > > Many of the prerequisites for exercising the full `make check' test suite
> > >
> > > I would prefer if you are more consistent and use "" instead of `' or '' everywhere.
> >
> > I was following a pre-existing convention from the INSTALL file itself.
> > I generally prefer '' because its easier and more natural for me. I'll
> > update to use ''.
> 
> OK, I understand you are native English speaker. Am I right? So, could
> you explain to me a difference between "", `' and '' for you guys?

Yes, I'm a native English speaker, and I don't think I can explain the
difference fully. From what I've gathered the `' is a tradition that
pre-dates me and seems to only be used in software documentation
(mostly GNU stuff). I'd be curious to know the rationale behind its use
as well. A wild guess that just came to me is that `' is used to
indicate commands because the `` is interpreted as a command by various
shells. But `` is not used to prevent the command from accidentally be
run if the test is interpreted by the shell. So just the first ` is
used to note that it is a command and ' is used to end because its
visually close to `.

As far as I'm aware, '' isn't used much in normal English text as the
single quote is used as an apostrophe to indicate possession mostly.
Double quotes, "", are used to indicate speech or text pulled verbatim
from another source. As an aside, I do like the idea of use `` for
commands because it means code in markdown and also

I misread your previous response, and thought you were asking for me to
choose between `' and '', instead of requesting the use of "". I'm fine
with using "".

> 
> > > > have not been documented. This adds them along with a note that some tests
> > > > require elevated privileges to run.
> > > >
> > > > Also add documentation on trusted sources for finding cross compiling tool
> > > > chains.
> > > >
> > > > Signed-off-by: Glenn Washburn <development@efficientek.com>
> > > > ---
> > > > Changes since v1
> > > >
> > > > * Add section on where to find cross compiling tool chains per Daniel's request.
> > > > * Missed needed modules loop and we need fuse for ntfs and exfat (though on
> > > >   very recent kernels the exfat module would be better to use).
> > > > * Also, romfs, isofs, and squashfs are not required either because we don't
> > > >   mount or use these images in loopback devices.
> > > > * Need exfat-fuse for all but recent kernels. And exfatprogs is better
> > > >   than exfat-utils (more compete support). But its a newer package, so
> > > >   may not be available on older systems.
> > > > * g++ package is needed to build some tests.
> > > > * Gawk is not strictly needed, in that testing will work, but the process
> > > >   will complain without it.
> > > >
> > > > ---
> > > > Interdiff against v1:
> > > >   diff --git a/INSTALL b/INSTALL
> > > >   index 25e3740ff..bb086a902 100644
> > > >   --- a/INSTALL
> > > >   +++ b/INSTALL
> > > >   @@ -46,6 +46,11 @@ need the following.
> > > >    * Autoconf 2.63 or later
> > > >    * Automake 1.11 or later
> > > >
> > > >   +Cross compiling tool chains can be found at the following trusted sites:
> > > >   +
> > > >   +* https://mirrors.kernel.org/pub/tools/crosstool/
> > > >   +* https://toolchains.bootlin.com/
> > > >   +
> > > >    Prerequisites for make-check:
> > > >
> > > >    * qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
> > > >   @@ -57,14 +62,17 @@ Prerequisites for make-check:
> > > >    * mtools, FAT tools for EFI platforms
> > > >
> > > >    * If running a Linux kernel the following modules must be loaded:
> > > >   -  - minix, hfs, mac-roman, hfsplus, exfat, reiserfs, xfs, f2fs, btrfs,
> > > >   -    nilfs2, jfs, fat, ext4, udf, romfs, isofs, squashfs
> > > >   +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
> > > >   +    nilfs2, jfs, fat, ext4, udf
> > > >   +  - On newer kernels, the exfat kernel modules may be used instead of the
> > > >   +    exfat FUSE filesystem.
> > > >    * The following are debian named packages required mostly for the full
> > > >      suite of filesystem testing (but some are needed by other tests as well
> > > >      - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
> > > >   -    zfs-fuse, dosfstools, exfat-utils, ntfs-3g, e2fsprogs, btrfs-progs,
> > > >   +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
> > > >        xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
> > > >   -    nilfs-tools, f2fs-tools, genromfs, attr
> > > >   +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
> > > >   +  - exfat-fuse, if not using the exfat kernel module
> > > >
> > > >    Note that `make check' will run and many tests may complete successfully
> > > >    with only a subset of these prerequisites. However, some tests may be
> > > >
> > > >  INSTALL | 32 ++++++++++++++++++++++++++++++--
> > > >  1 file changed, 30 insertions(+), 2 deletions(-)
> > > >
> > > > diff --git a/INSTALL b/INSTALL
> > > > index 5e152b71f..bb086a902 100644
> > > > --- a/INSTALL
> > > > +++ b/INSTALL
> > > > @@ -46,10 +46,37 @@ need the following.
> > > >  * Autoconf 2.63 or later
> > > >  * Automake 1.11 or later
> > > >
> > >
> > > I think you should add a sentence at the beginning of the file that packages
> > > names are for Debian X and can be different for other distros.
> >
> > Sure, I can do that. Perhaps this sentence will suffice:
> >
> >   Where this document refers to packages names, they are named
> >   according to the Debian 11 package repositories.
> 
> Works for me!
> 
> > > > +Cross compiling tool chains can be found at the following trusted sites:
> > >
> > > Could you list names of cross compiling packages for Debian X too?
> > > I know at least gcc-aarch64-linux-gnu, gcc-arm-linux-gnueabihf,
> > > gcc-mipsel-linux-gnu and mingw-w64.
> >
> > I am not familiar with such packages nor have any experience in using
> > them. I don't feel comfortable adding them. I can add something saying
> > that "your distro may provide you with cross compiling packages and if
> > not the following are reputable sites from which to get pre-built
> > cross compiling tool chains." If you have experience in this area feel
> > free to modify the patch as you deem fit and add yourself as coauthor.
> 
> If you do not want or what not to look for more cross compilers packages
> in the Debian 11 just put the list which I gave you. You can say that it
> can be incomplete...

Ok, will do.

> 
> > > The sites below should be listed as an option if the cross compilers are
> > > not available for some architectures in a given distro.
> >
> > Personally, I think listing these is fine as is.
> 
> ...and more cross compilers can be found at the sites mentioned below...

Ack.

> 
> > > > +* https://mirrors.kernel.org/pub/tools/crosstool/
> > > > +* https://toolchains.bootlin.com/
> > > > +
> > > >  Prerequisites for make-check:
> > > >
> > > > -* qemu, specifically the binary 'qemu-system-i386'
> > > > +* qemu, specifically the binary 'qemu-system-ARCH' where ARCH is the
> > >
> > > Again, could you name relevant qemu packages...
> >
> > The package qemu-system pulls in the mains ones: qemu-system-arm,
> > qemu-system-mips, qemu-system-ppc, qemu-system-sparc, qemu-system-x86,
> > and qemu-system-misc. I don't think we need to cater to the segment of
> > people who can't figure out how to use the package manager (search for
> > qemu packages and find the appropriate one). It might be worth
> > mentioning that the 'qemu-system' package pulls in all qemu-system
> > architectures.
> 
> I am fine with listing qemu-system package and saying that it pulls in
> all supported QEMU architectures on Debian 11.

Ok.

> 
> > > > +  architecture GRUB has been built for
> > > > +* OVMF, for EFI platforms
> > >
> > > IIRC the packages are called simply "ovmf" for amd64 and "ovmf-ia32" for x86.
> >
> > OVNM is not a package name, its a project name, just as Autoconf above
> 
> Yeah, I know but giving packages names ease people life. Then they do
> not need to guess them and just put their names into the installer.

Ack.

> 
> > is not a package name. I can append "(eg. Debian packages ovmf,
> > ovmf-ia32, qemu-efi-arm, and qemu-efi-aarch64)".
> 
> Yeah, that would be nice...

Ack.

> 
> > > > +* OpenBIOS, for ieee1275 platforms
> > >
> > > Could name OpenBIOS package?
> >
> > Again, this is the project name. Debian package names would be
> > openbios-ppc and openbios-sparc.
> 
> Please list them. This can be helpful for people...

Ack.

> 
> > > >  * xorriso 1.2.9 or later, for grub-mkrescue and grub-shell
> > > > +* wamerican, for grub-fs-tester
> > > > +* mtools, FAT tools for EFI platforms
> > > > +
> > > > +* If running a Linux kernel the following modules must be loaded:
> > > > +  - fuse, loop, minix, hfs, mac-roman, hfsplus, reiserfs, xfs, f2fs, btrfs,
> > > > +    nilfs2, jfs, fat, ext4, udf
> > > > +  - On newer kernels, the exfat kernel modules may be used instead of the
> > > > +    exfat FUSE filesystem.
> > > > +* The following are debian named packages required mostly for the full
> > > > +  suite of filesystem testing (but some are needed by other tests as well
> > > > +  - tar, cpio, gzip, lzop, xz-utils, parted, util-linux, squashfs-tools,
> > > > +    zfs-fuse, dosfstools, exfatprogs, ntfs-3g, e2fsprogs, btrfs-progs,
> > > > +    xfsprogs, hfsprogs, recode, jfsutils, reiserfsprogs, udftools,
> > > > +    nilfs-tools, f2fs-tools, genromfs, attr, g++, gawk
> > > > +  - exfat-fuse, if not using the exfat kernel module
> > >
> > > I am OK with the grouping but I would prefer if you sort the names of
> > > packages in alphabetical order in each group.
> >
> > By grouping you mean how tar and cpio are grouped and gzip, lzop, and
> > xz-utils are grouped? Or is that all considered one group? They are
> 
> I consider "tar, ... gawk" as a group. Or bullet point if you prefer but
> here there is a dash instead of bullet... :-) Dash point? :-)

I guess you consider gawk a part of that group because its something
you'd likely fine on a base install. I wasn't considering it part of
the group because its not a file archival program. But its not a big
deal for me, I'll put it in that group.

As for using the dash, it makes it easier to visually note the
list heirarchy.

> 
> > partially ordered, but not lexographically sorted.
> 
> I was thinking about alphabetical/lexicographical ordering in a given
> bullet point.

Yes, I'll add more list items and sort within each item.

Glenn