[PATCH 0/1] README: restructure & format building manual

[PATCH 0/1] README: restructure & format building manual

[Andrey Albershteyn]

I'm new to the xfstests, I've tried to set things up for testing and found out
that building manual in the README is not up-to-date and a little bit difficult
to follow as it's not clear which steps are necessary to get started and which
can be skipped.

In this patch I updated installation package list commands and restructured
"BUILDING THE FSQA SUITE" section. Package list is up-to-date for the latest
distors (Ubuntu 21.10, Debian 11, Fedora 35, RHEL 8).

Andrey Albershteyn (1):
  README: restructure & format building manual

 README | 342 ++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 205 insertions(+), 137 deletions(-)

-- 
2.27.0

[PATCH 1/1] README: restructure & format building manual

[Andrey Albershteyn]

The commands for package managers for both Ubuntu and RHEL weren't
up-to-date. A few packages doesn't exist anymore or missing from the
latest repositories (e.g. liburing-devel, btrfs-progs-devel). Ubuntu's
list missed a few packages listed in RHEL's list. There are a few repeating
steps. The indent of avaliable environment variables is not clear.

This patch:
- Update package dependencies for Ubuntu/Debian/RHEL/CentOS/Fedora
- Unify list of packages between Ubuntu/Debian and RHEL/CentOS/Fedora
- Add list of tool packages for other FS
- Add links to tools not in the standard repository for RHEL/CentOS
- Drop xfsprogs-qa-devel reference for old systems
- Replace note about EPEL with installation step with link to Fedora
  manual
- Add configuration examples in 'Setup Environment'
- Small clarification details, such as size of the partition and
  KCONFIG_PATH description
- Removal of repeating steps (install administrative tools, partitions
  content)
- Restructuring and formatting of "BUILDING THE FSQA SUITE" section
- Drop IRIXDEV references in variable set up

Signed-off-by: Andrey Albershteyn <aalbersh@redhat.com>
---
 README | 342 ++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 205 insertions(+), 137 deletions(-)

diff --git a/README b/README
index e9284b22..99d102df 100644
--- a/README
+++ b/README
@@ -2,148 +2,216 @@ _______________________
 BUILDING THE FSQA SUITE
 _______________________
 
-- cd into the xfstests directory
-- install prerequisite packages
-  For example, for Ubuntu:
-	sudo apt-get install xfslibs-dev uuid-dev libtool-bin \
-	e2fsprogs automake gcc libuuid1 quota attr make \
-	libacl1-dev libaio-dev xfsprogs libgdbm-dev gawk fio dbench \
-	uuid-runtime python sqlite3 liburing-dev libcap-dev
-  For Fedora, RHEL, or CentOS:
-	yum install acl attr automake bc dbench dump e2fsprogs fio \
-	gawk gcc indent libtool lvm2 make psmisc quota sed \
-	xfsdump xfsprogs \
-	libacl-devel libaio-devel libuuid-devel \
-	xfsprogs-devel btrfs-progs-devel python sqlite liburing-devel \
-	libcap-devel
-	(Older distributions may require xfsprogs-qa-devel as well.)
-	(Note that for RHEL and CentOS, you may need the EPEL repo.)
-- run make
-- run make install
-- create fsgqa test user ("sudo useradd -m fsgqa")
-- create fsgqa group ("sudo groupadd fsgqa")
-- create 123456-fsgqa test user ("sudo useradd 123456-fsgqa")
-  this 2nd user creation step can be safely skipped if your system
-  doesn't support names starting with digits, only a handful of tests
-  require it.
-- create fsgqa2 test user ("sudo useradd fsgqa2")
+Ubuntu, or Debian
+-----------------
+
+1. Make sure that package list is up-to-date and install all necessary packages:
+
+   $ sudo apt-get update
+   $ sudo apt-get install \
+           acl attr automake bc dbench fio gawk gcc git indent libtool lvm2 \
+           make psmisc python3 quota sed \
+           dump e2fsprogs \
+           xfsdump xfsprogs \
+           libacl1-dev libaio-dev libcap-dev libgdbm-dev libtool-bin \
+           liburing-dev libuuid1 uuid-dev uuid-runtime \
+           linux-headers-$(uname -r) sqlite3 xfslibs-dev
+
+2. (Optional) For udf, exfat, f2fs, ocfs2 install:
+
+   $ sudo apt-get install \
+       udftools \
+       exfatprogs \
+       f2fs-tools \
+       ocfs2-tools
+
+   For OverlayFS install:
+    - see https://github.com/hisilicon/overlayfs-progs
+
+Fedora, RHEL, or CentOS
+-----------------------
+
+0. For RHEL and CentOS, enable EPEL repository:
+    - see https://docs.fedoraproject.org/en-US/epel/#How_can_I_use_these_extra_packages.3F
+
+1. Install all packages which are available from standard repository:
+
+   $ sudo yum install \
+        acl attr automake bc dbench fio indent gawk gcc git libtool lvm2 \
+        make psmisc python3 quota sed \
+        dump e2fsprogs \
+        xfsdump xfsprogs \
+        libcap-devel gdbm-devel kernel-devel libacl-devel libaio-devel \
+        libuuid-devel sqlite udftools xfsprogs-devel
+
+   Or, EPEL packages could be compiled from sources, see:
+    - https://dbench.samba.org/web/download.html
+    - https://www.gnu.org/software/indent/
+
+3. For Fedora, install also:
+
+    $ sudo yum install liburing-devel
+
+   For RHEL and CentOS:
+    - see https://github.com/axboe/liburing.
+
+4. (Optional) Install tools for particular filesystems:
+
+   For BTRFS on Fedora:
+    $ sudo yum install btrfs-progs
+
+   For exfat on Fedora, RHEL, or CentOS:
+    $ sudo yum install exfatprogs
+
+   For f2fs on Fedora install:
+    $ sudo yum install f2fs-tools
+   For f2fs on RHEL, or CentOS install:
+    - see https://git.kernel.org/pub/scm/linux/kernel/git/jaegeuk/f2fs-tools.git/about/
+
+   For ocfs2 on Fedora install:
+    $ sudo yum install ocfs2-tools
+   For ocfs2 on RHEL or CentOS install:
+    - see https://github.com/markfasheh/ocfs2-tools
+
+   For OverlayFS install:
+    - see https://github.com/hisilicon/overlayfs-progs
+
+Build and install test, libs and utils
+--------------------------------------
+
+$ git clone git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
+$ cd xfstests-dev
+$ make
+$ sudo make install
+
+Setup Environment
+-----------------
+
+1. Compile XFS/EXT4/BTRFS/etc. into your kernel or load as module. For example,
+   for XFS, enable XFS_FS in your kernel configuration, or compile it as a
+   module and load it with 'sudo modprobe xfs'. Most of the distributions will
+   have these filesystems already in the kernel/as module.
+
+2. Create one or two partitions (at least 10G each) to use for testing
+    - TEST partition - format as XFS, mount & optionally populate with
+      NON-IMPORTANT stuff
+    - SCRATCH partition (optional) - leave empty and expect this partition to be
+      clobbered by some tests. If this is not provided, many tests will not be
+      run. Note that SCRATCH and TEST must be two DIFFERENT partitions.
+    - BTRFS only: some btrfs test cases will need 3 or more independent SCRATCH
+      disks which should be set using SCRATCH_DEV_POOL (e.g.
+      SCRATCH_DEV_POOL="/dev/sda /dev/sdb /dev/sdc") with which SCRATCH_DEV
+      should be unused by the tester, and for the legacy support SCRATCH_DEV
+      will be set to the first disk of the SCRATCH_DEV_POOL by xfstests script.
+      Note that these partitions should not have anything usefull, as it will be
+      clobbered by tests.
+
+   For example, to run the tests with loopback partitions:
+   # dd if=/dev/zero of=./test.img bs=1M count=10000
+   # dd if=/dev/zero of=./scratch.img bs=1M count=10000
+   # mkfs.xfs test.img
+   # mkfs.xfs scratch.img
+   # losetup /dev/loop0 ./test.img
+   # losetup /dev/loop1 ./scratch.img
+   # mkdir -p /mnt/test && mount /dev/loop0 /mnt/test
+   # mkdir -p /mnt/scratch && mount /dev/loop1 /mnt/scratch
+
+3. Copy local.config.example to local.config and edit as needed. The TEST_DEV
+   and TEST_DIR are required.
+
+   For example, the config for the setup above is:
+   $ cat local.config
+   export TEST_DEV=/dev/loop0
+   export TEST_DIR=/mnt/test
+   export SCRATCH_DEV=/dev/loop1
+   export SCRATCH_MNT=/mnt/scratch
+
+From this point you can run some basic tests, see 'USING THE FSQA SUITE' below.
+
+Additional Setup
+----------------
+
+Some tests require additional configuration of the system and in your
+local.config. Add these variables to a local.config and keep that file in your
+workarea. Or add a case to the switch in common/config assigning these variables
+based on the hostname of your test machine. Or use 'setenv' to set them.
+
+ - Create fsgqa test users and groups:
+
+   $ sudo useradd -m fsgqa
+   $ sudo useradd 123456-fsgqa
+   $ sudo useradd fsgqa2
+   $ sudo groupadd fsgqa
+
+   The "123456-fsgqa" user creation step can be safely skipped if your system
+   doesn't support names starting with digits, only a handful of tests require
+   it.
+ - If you wish to run the udf components of the suite install mkudffs. Also
+   download and build the Philips UDF Verification Software from
+   https://www.lscdweb.com/registered/udf_verifier.html, then copy the udf_test
+   binary to xfstests/src/.
+ - If you wish to disable UDF verification test set the environment variable
+   DISABLE_UDF_TEST to 1.
+ - Set TAPE_DEV to "tape device for testing xfsdump". Note that if testing
+   xfsdump, make sure the tape devices have a tape which can be overwritten.
+ - Set RMT_TAPE_DEV to "remote tape device for testing xfsdump"
+ - Set SCRATCH_LOGDEV to "device for scratch-fs external log"
+ - Set SCRATCH_RTDEV to "device for scratch-fs realtime data"
+ - Set TEST_LOGDEV to "device for test-fs external log"
+ - Set TEST_RTDEV to "device for test-fs realtime data"
+ - If TEST_LOGDEV and/or TEST_RTDEV, these will always be used.
+ - If SCRATCH_LOGDEV and/or SCRATCH_RTDEV, the USE_EXTERNAL environment
+   variable set to "yes" will enable their use.
+ - Set DIFF_LENGTH to "number of diff lines to print from a failed test",
+   by default 10, set to 0 to print the full diff
+ - Set FSTYP to "the filesystem you want to test", the filesystem type is
+   devised from the TEST_DEV device, but you may want to override it; if
+   unset, the default is 'xfs'
+ - Set FSSTRESS_AVOID and/or FSX_AVOID, which contain options added to
+   the end of fsstresss and fsx invocations, respectively, in case you wish
+   to exclude certain operational modes from these tests.
+ - Set TEST_XFS_REPAIR_REBUILD=1 to have _check_xfs_filesystem run
+   xfs_repair -n to check the filesystem; xfs_repair to rebuild metadata
+   indexes; and xfs_repair -n (a third time) to check the results of the
+   rebuilding.
+ - xfs_scrub, if present, will always check the test and scratch
+   filesystems if they are still online at the end of the test. It is no
+   longer necessary to set TEST_XFS_SCRUB.
+ - Set LOGWRITES_DEV to a block device to use for power fail testing.
+ - Set PERF_CONFIGNAME to a arbitrary string to be used for identifying
+   the test setup for running perf tests. This should be different for
+   each type of performance test you wish to run so that relevant results
+   are compared. For example 'spinningrust' for configurations that use
+   spinning disks and 'nvme' for tests using nvme drives.
+ - Set USE_KMEMLEAK=yes to scan for memory leaks in the kernel after every
+   test, if the kernel supports kmemleak.
+ - Set KEEP_DMESG=yes to keep dmesg log after test
+ - Set TEST_FS_MODULE_RELOAD=1 to unload the module and reload it between
+   test invocations. This assumes that the name of the module is the same
+   as FSTYP.
+ - Set DUMP_CORRUPT_FS=1 to record metadata dumps of XFS or ext*
+   filesystems if a filesystem check fails.
+ - Set DUMP_COMPRESSOR to a compression program to compress metadumps of
+   filesystems. This program must accept '-f' and the name of a file to
+   compress; and it must accept '-d -f -k' and the name of a file to
+   decompress. In other words, it must emulate gzip.
+ - Set MIN_FSSIZE to specify the minimal size (bytes) of a filesystem we
+   can create. Setting this parameter will skip the tests creating a
+   filesystem less than MIN_FSSIZE.
+ - Set MODPROBE_PATIENT_RM_TIMEOUT_SECONDS to specify the amount of time we
+   should try a patient module remove. The default is 50 seconds. Set this
+   to "forever" and we'll wait forever until the module is gone.
+ - Set FORCE_XFS_CHECK_PROG=yes to have _check_xfs_filesystem run xfs_check
+   to check the filesystem. As of August 2021, xfs_repair finds all
+   filesystem corruptions found by xfs_check, and more, which means that
+   xfs_check is no longer run by default.
+ - Set KCONFIG_PATH to specify your preferred location of kernel config
+   file. The config is used by tests to check if kernel feature is enabled.
 
 ______________________
 USING THE FSQA SUITE
 ______________________
 
-Preparing system for tests:
-
-    - compile XFS into your kernel or load XFS modules
-    - install administrative tools specific to the filesystem you wish to test
-    - If you wish to run the udf components of the suite install
-      mkudffs. Also download and build the Philips UDF Verification Software
-      from https://www.lscdweb.com/registered/udf_verifier.html, then copy the udf_test
-      binary to xfstests/src/. If you wish to disable UDF verification test
-      set the environment variable DISABLE_UDF_TEST to 1.
-
-    - create one or two partitions to use for testing
-        - one TEST partition
-            - format as XFS, mount & optionally populate with
-              NON-IMPORTANT stuff
-        - one SCRATCH partition (optional)
-            - leave empty and expect this partition to be clobbered
-              by some tests.  If this is not provided, many tests will
-              not be run.
-              (SCRATCH and TEST must be two DIFFERENT partitions)
-              OR
-        - for btrfs only: some btrfs test cases will need 3 or more independent
-              SCRATCH disks which should be set using SCRATCH_DEV_POOL (for eg:
-              SCRATCH_DEV_POOL="/dev/sda /dev/sdb /dev/sdc") with which
-              SCRATCH_DEV should be unused by the tester, and for the legacy
-              support SCRATCH_DEV will be set to the first disk of the
-              SCRATCH_DEV_POOL by xfstests script.
-
-    - setup your environment
-	Quick start:
-	- copy local.config.example to local.config and edit as needed
-	Or:
-        - setenv TEST_DEV "device containing TEST PARTITION"
-        - setenv TEST_DIR "mount point of TEST PARTITION"
-	- optionally:
-             - setenv SCRATCH_DEV "device containing SCRATCH PARTITION" OR
-               (btrfs only) setenv SCRATCH_DEV_POOL "to 3 or more SCRATCH disks for
-               testing btrfs raid concepts"
-             - setenv SCRATCH_MNT "mount point for SCRATCH PARTITION"
-             - setenv TAPE_DEV "tape device for testing xfsdump"
-             - setenv RMT_TAPE_DEV "remote tape device for testing xfsdump"
-             - setenv RMT_IRIXTAPE_DEV "remote IRIX tape device for testing xfsdump"
-	     - setenv SCRATCH_LOGDEV "device for scratch-fs external log"
-             - setenv SCRATCH_RTDEV "device for scratch-fs realtime data"
-	     - setenv TEST_LOGDEV "device for test-fs external log"
-             - setenv TEST_RTDEV "device for test-fs realtime data"
-             - if TEST_LOGDEV and/or TEST_RTDEV, these will always be used.
-             - if SCRATCH_LOGDEV and/or SCRATCH_RTDEV, the USE_EXTERNAL
-               environment variable set to "yes" will enable their use.
-             - setenv DIFF_LENGTH "number of diff lines to print from a failed test",
-               by default 10, set to 0 to print the full diff
-             - setenv FSTYP "the filesystem you want to test", the filesystem
-               type is devised from the TEST_DEV device, but you may want to
-               override it; if unset, the default is 'xfs'
-             - setenv FSSTRESS_AVOID and/or FSX_AVOID, which contain options
-               added to the end of fsstresss and fsx invocations, respectively,
-               in case you wish to exclude certain operational modes from these
-               tests.
-             - set TEST_XFS_REPAIR_REBUILD=1 to have _check_xfs_filesystem
-               run xfs_repair -n to check the filesystem; xfs_repair to rebuild
-               metadata indexes; and xfs_repair -n (a third time) to check the
-               results of the rebuilding.
-             - xfs_scrub, if present, will always check the test and scratch
-               filesystems if they are still online at the end of the test.
-               It is no longer necessary to set TEST_XFS_SCRUB.
-             - setenv LOGWRITES_DEV to a block device to use for power fail
-               testing.
-             - setenv PERF_CONFIGNAME to a arbitrary string to be used for
-               identifying the test setup for running perf tests.  This should
-               be different for each type of performance test you wish to run so
-               that relevant results are compared.  For example 'spinningrust'
-               for configurations that use spinning disks and 'nvme' for tests
-               using nvme drives.
-             - set USE_KMEMLEAK=yes to scan for memory leaks in the kernel
-               after every test, if the kernel supports kmemleak.
-             - set KEEP_DMESG=yes to keep dmesg log after test
-             - Set TEST_FS_MODULE_RELOAD=1 to unload the module and reload
-               it between test invocations.  This assumes that the name of
-               the module is the same as FSTYP.
-             - Set DUMP_CORRUPT_FS=1 to record metadata dumps of XFS or ext*
-               filesystems if a filesystem check fails.
-             - Set DUMP_COMPRESSOR to a compression program to compress
-               metadumps of filesystems.  This program must accept '-f' and the
-               name of a file to compress; and it must accept '-d -f -k' and
-               the name of a file to decompress.  In other words, it must
-               emulate gzip.
-	     - Set MIN_FSSIZE to specify the minimal size (bytes) of a
-               filesystem we can create. Setting this parameter will
-               skip the tests creating a filesystem less than
-               MIN_FSSIZE.
-	     - Set MODPROBE_PATIENT_RM_TIMEOUT_SECONDS to specify the amount of
-	       time we should try a patient module remove. The default is 50
-	       seconds. Set this to "forever" and we'll wait forever until the
-	       module is gone.
-             - Set FORCE_XFS_CHECK_PROG=yes to have _check_xfs_filesystem run
-               xfs_check to check the filesystem.  As of August 2021,
-               xfs_repair finds all filesystem corruptions found by xfs_check,
-               and more, which means that xfs_check is no longer run by default.
-	     - Set KCONFIG_PATH to specify your preferred location of kernel
-	       config file.
-
-        - or add a case to the switch in common/config assigning
-          these variables based on the hostname of your test
-          machine
-	- or add these variables to a file called local.config and keep that
-	  file in your workarea.
-
-    - if testing xfsdump, make sure the tape devices have a
-      tape which can be overwritten.
-
-    - make sure $TEST_DEV is a mounted XFS partition
-    - make sure that $SCRATCH_DEV or $SCRATCH_DEV_POOL contains nothing useful
-
 Running tests:
 
     - cd xfstests
-- 
2.27.0

Re: [PATCH 1/1] README: restructure & format building manual

[Dave Chinner]

Hi Andrey,

This is a good start, but I think it can be improved further.

On Mon, Feb 21, 2022 at 09:25:58PM +0100, Andrey Albershteyn wrote:
> The commands for package managers for both Ubuntu and RHEL weren't
> up-to-date. A few packages doesn't exist anymore or missing from the
> latest repositories (e.g. liburing-devel, btrfs-progs-devel). Ubuntu's
> list missed a few packages listed in RHEL's list. There are a few repeating
> steps. The indent of avaliable environment variables is not clear.

A couple of housekeeping notes first.

Commit messages should be line wrapped at 68-72 columns so that they
can easily be cut/paste/quoted into email which typically wraps at
68-72 columns.

If you use vim, you can set up a column marker and text wrapping to
do this automatically with .vimrc rules like this:

" default text width is 80 columns
set	textwidth=80

" set the textwidth to 68 characters for guilt commit messages
 au BufNewFile,BufRead guilt.msg.*,.gitsendemail.*,git.*,*/.git/*  set tw=68

And you set the textwidth highlight with:

" highlight textwidth
set cc=+1

You'll want to highlight whitespace damage, too.

" highlight whitespace damage
highlight RedundantSpaces ctermbg=red guibg=red
match RedundantSpaces /\s\+$\| \+\ze\t/

Also, if you use mutt for email, then add this to your .muttrc:

set editor="vim -c 'set ft=mail tw=68'"

And all it will set up the defaults for 68 column mail editting by
default.

IOWs, the textwidth the editor defaults to will now change
automatically depending on whether you are writing email, editting
code or git commit messages...

> This patch:
> - Update package dependencies for Ubuntu/Debian/RHEL/CentOS/Fedora
> - Unify list of packages between Ubuntu/Debian and RHEL/CentOS/Fedora
> - Add list of tool packages for other FS
> - Add links to tools not in the standard repository for RHEL/CentOS
> - Drop xfsprogs-qa-devel reference for old systems
> - Replace note about EPEL with installation step with link to Fedora
>   manual
> - Add configuration examples in 'Setup Environment'
> - Small clarification details, such as size of the partition and
>   KCONFIG_PATH description
> - Removal of repeating steps (install administrative tools, partitions
>   content)
> - Restructuring and formatting of "BUILDING THE FSQA SUITE" section
> - Drop IRIXDEV references in variable set up

Normally we ask for one change per patch so that we can see the
individual changes in isolation. For a documentation update like
this it isn't really necessary, but it can still help.

> 
> Signed-off-by: Andrey Albershteyn <aalbersh@redhat.com>
> ---
>  README | 342 ++++++++++++++++++++++++++++++++++-----------------------
>  1 file changed, 205 insertions(+), 137 deletions(-)
> 
> diff --git a/README b/README
> index e9284b22..99d102df 100644
> --- a/README
> +++ b/README
> @@ -2,148 +2,216 @@ _______________________
>  BUILDING THE FSQA SUITE
>  _______________________
>  
> -- cd into the xfstests directory
> -- install prerequisite packages
> -  For example, for Ubuntu:
> -	sudo apt-get install xfslibs-dev uuid-dev libtool-bin \
> -	e2fsprogs automake gcc libuuid1 quota attr make \
> -	libacl1-dev libaio-dev xfsprogs libgdbm-dev gawk fio dbench \
> -	uuid-runtime python sqlite3 liburing-dev libcap-dev
> -  For Fedora, RHEL, or CentOS:
> -	yum install acl attr automake bc dbench dump e2fsprogs fio \
> -	gawk gcc indent libtool lvm2 make psmisc quota sed \
> -	xfsdump xfsprogs \
> -	libacl-devel libaio-devel libuuid-devel \
> -	xfsprogs-devel btrfs-progs-devel python sqlite liburing-devel \
> -	libcap-devel
> -	(Older distributions may require xfsprogs-qa-devel as well.)
> -	(Note that for RHEL and CentOS, you may need the EPEL repo.)
> -- run make
> -- run make install
> -- create fsgqa test user ("sudo useradd -m fsgqa")
> -- create fsgqa group ("sudo groupadd fsgqa")
> -- create 123456-fsgqa test user ("sudo useradd 123456-fsgqa")
> -  this 2nd user creation step can be safely skipped if your system
> -  doesn't support names starting with digits, only a handful of tests
> -  require it.
> -- create fsgqa2 test user ("sudo useradd fsgqa2")
> +Ubuntu, or Debian
> +-----------------

No trailing comma before and/or.

> +
> +1. Make sure that package list is up-to-date and install all necessary packages:

Line over 80 columns in width.

> +
> +   $ sudo apt-get update
> +   $ sudo apt-get install \
> +           acl attr automake bc dbench fio gawk gcc git indent libtool lvm2 \
> +           make psmisc python3 quota sed \
> +           dump e2fsprogs \
> +           xfsdump xfsprogs \
> +           libacl1-dev libaio-dev libcap-dev libgdbm-dev libtool-bin \
> +           liburing-dev libuuid1 uuid-dev uuid-runtime \
> +           linux-headers-$(uname -r) sqlite3 xfslibs-dev

I'd pack this list rather than having it broken up into random
length lines. Also, rather than include a couple of filesystem
specific packages here, I'd list all the packages that are needed
regardless of the fs being tested. This would mean e2fsprogs and
xfsprogs will be in the above list, but xfsdump and xfslibs-dev
shouldn't be. They would get listed in #2:

> +2. (Optional) For udf, exfat, f2fs, ocfs2 install:

"2. Install pacakages for the filesystem(s) being tested:"

> +
> +   $ sudo apt-get install \
> +       udftools \
> +       exfatprogs \
> +       f2fs-tools \
> +       ocfs2-tools
> +
> +   For OverlayFS install:
> +    - see https://github.com/hisilicon/overlayfs-progs
> +
> +Fedora, RHEL, or CentOS
> +-----------------------

Fedora, RHEL or CentOS

> +
> +0. For RHEL and CentOS, enable EPEL repository:
> +    - see https://docs.fedoraproject.org/en-US/epel/#How_can_I_use_these_extra_packages.3F
> +
> +1. Install all packages which are available from standard repository:
> +
> +   $ sudo yum install \
> +        acl attr automake bc dbench fio indent gawk gcc git libtool lvm2 \
> +        make psmisc python3 quota sed \
> +        dump e2fsprogs \
> +        xfsdump xfsprogs \
> +        libcap-devel gdbm-devel kernel-devel libacl-devel libaio-devel \
> +        libuuid-devel sqlite udftools xfsprogs-devel
> +
> +   Or, EPEL packages could be compiled from sources, see:
> +    - https://dbench.samba.org/web/download.html
> +    - https://www.gnu.org/software/indent/
> +
> +3. For Fedora, install also:
> +
> +    $ sudo yum install liburing-devel
> +
> +   For RHEL and CentOS:
> +    - see https://github.com/axboe/liburing.
> +
> +4. (Optional) Install tools for particular filesystems:
> +
> +   For BTRFS on Fedora:
> +    $ sudo yum install btrfs-progs
> +
> +   For exfat on Fedora, RHEL, or CentOS:
> +    $ sudo yum install exfatprogs
> +
> +   For f2fs on Fedora install:
> +    $ sudo yum install f2fs-tools
> +   For f2fs on RHEL, or CentOS install:
> +    - see https://git.kernel.org/pub/scm/linux/kernel/git/jaegeuk/f2fs-tools.git/about/
> +
> +   For ocfs2 on Fedora install:
> +    $ sudo yum install ocfs2-tools
> +   For ocfs2 on RHEL or CentOS install:
> +    - see https://github.com/markfasheh/ocfs2-tools
> +
> +   For OverlayFS install:
> +    - see https://github.com/hisilicon/overlayfs-progs

THis seems like it might be better to separate Fedora from
RHEL/CentOS - only step 1 has any commonality between these distros.

> +Build and install test, libs and utils
> +--------------------------------------
> +
> +$ git clone git://git.kernel.org/pub/scm/fs/xfs/xfstests-dev.git
> +$ cd xfstests-dev
> +$ make
> +$ sudo make install
> +
> +Setup Environment
> +-----------------
> +
> +1. Compile XFS/EXT4/BTRFS/etc. into your kernel or load as module. For example,
> +   for XFS, enable XFS_FS in your kernel configuration, or compile it as a
> +   module and load it with 'sudo modprobe xfs'. Most of the distributions will
> +   have these filesystems already in the kernel/as module.
> +
> +2. Create one or two partitions (at least 10G each) to use for testing
> +    - TEST partition - format as XFS, mount & optionally populate with
> +      NON-IMPORTANT stuff

Separate test/scratch/scratch-pool devices into three separate steps.

2. Create TEST device.
	- format as the filesystem type you wish to test.
	- optionally populate with destroyable data.
	- should be at least 10GB in size.
	- device contents may be destroyed.

> +    - SCRATCH partition (optional) - leave empty and expect this partition to be
> +      clobbered by some tests. If this is not provided, many tests will not be
> +      run. Note that SCRATCH and TEST must be two DIFFERENT partitions.

3. (optional) Create SCRATCH device.
	- should be at least 10GB in size.
	- device contents will be destroyed.
	- many tests depend on the SCRATCH device existing.
	- Must be different to TEST device.

> +    - BTRFS only: some btrfs test cases will need 3 or more independent SCRATCH
> +      disks which should be set using SCRATCH_DEV_POOL (e.g.
> +      SCRATCH_DEV_POOL="/dev/sda /dev/sdb /dev/sdc") with which SCRATCH_DEV
> +      should be unused by the tester, and for the legacy support SCRATCH_DEV
> +      will be set to the first disk of the SCRATCH_DEV_POOL by xfstests script.
> +      Note that these partitions should not have anything usefull, as it will be
> +      clobbered by tests.

4. (optional) Create SCRATCH device pool
	- needed for BTRFS testing
	- specifies 3 or more independent SCRATCH devices via the
	  SCRATCH_DEV_POOL variable.
	- device contents will be destroyed.
	- e.g SCRATCH_DEV_POOL="/dev/sda /dev/sdb /dev/sdc"
	- SCRATCH device should be left unset, it will be overridden
	  by the SCRATCH_DEV_POOL implementation.

> +
> +   For example, to run the tests with loopback partitions:
> +   # dd if=/dev/zero of=./test.img bs=1M count=10000
> +   # dd if=/dev/zero of=./scratch.img bs=1M count=10000

Faster to just preallocate the image files:

xfs_io -f -c "fallocate 0 10g" test.img
xfs_io -f -c "fallocate 0 10g" scratch.img

> +   # mkfs.xfs test.img
> +   # mkfs.xfs scratch.img

No need to mkfs the scratch device - tests always do this before
they use it.

> +   # losetup /dev/loop0 ./test.img
> +   # losetup /dev/loop1 ./scratch.img
> +   # mkdir -p /mnt/test && mount /dev/loop0 /mnt/test
> +   # mkdir -p /mnt/scratch && mount /dev/loop1 /mnt/scratch
> +
> +3. Copy local.config.example to local.config and edit as needed. The TEST_DEV
> +   and TEST_DIR are required.
> +
> +   For example, the config for the setup above is:
> +   $ cat local.config
> +   export TEST_DEV=/dev/loop0
> +   export TEST_DIR=/mnt/test
> +   export SCRATCH_DEV=/dev/loop1
> +   export SCRATCH_MNT=/mnt/scratch
> +
> +From this point you can run some basic tests, see 'USING THE FSQA SUITE' below.
> +
> +Additional Setup
> +----------------
> +
> +Some tests require additional configuration of the system and in your
> +local.config. Add these variables to a local.config and keep that file in your
> +workarea. Or add a case to the switch in common/config assigning these variables
> +based on the hostname of your test machine. Or use 'setenv' to set them.
> +
> + - Create fsgqa test users and groups:
> +
> +   $ sudo useradd -m fsgqa
> +   $ sudo useradd 123456-fsgqa
> +   $ sudo useradd fsgqa2
> +   $ sudo groupadd fsgqa
> +
> +   The "123456-fsgqa" user creation step can be safely skipped if your system
> +   doesn't support names starting with digits, only a handful of tests require
> +   it.
> + - If you wish to run the udf components of the suite install mkudffs. Also
> +   download and build the Philips UDF Verification Software from
> +   https://www.lscdweb.com/registered/udf_verifier.html, then copy the udf_test
> +   binary to xfstests/src/.

Hmmm - shouldn't that be in the initial setup information?

> + - If you wish to disable UDF verification test set the environment variable
> +   DISABLE_UDF_TEST to 1.
> + - Set TAPE_DEV to "tape device for testing xfsdump". Note that if testing
> +   xfsdump, make sure the tape devices have a tape which can be overwritten.
> + - Set RMT_TAPE_DEV to "remote tape device for testing xfsdump"
> + - Set SCRATCH_LOGDEV to "device for scratch-fs external log"
> + - Set SCRATCH_RTDEV to "device for scratch-fs realtime data"
> + - Set TEST_LOGDEV to "device for test-fs external log"
> + - Set TEST_RTDEV to "device for test-fs realtime data"
> + - If TEST_LOGDEV and/or TEST_RTDEV, these will always be used.
> + - If SCRATCH_LOGDEV and/or SCRATCH_RTDEV, the USE_EXTERNAL environment
> +   variable set to "yes" will enable their use.
> + - Set DIFF_LENGTH to "number of diff lines to print from a failed test",
> +   by default 10, set to 0 to print the full diff
> + - Set FSTYP to "the filesystem you want to test", the filesystem type is
> +   devised from the TEST_DEV device, but you may want to override it; if
> +   unset, the default is 'xfs'
> + - Set FSSTRESS_AVOID and/or FSX_AVOID, which contain options added to
> +   the end of fsstresss and fsx invocations, respectively, in case you wish
> +   to exclude certain operational modes from these tests.
> + - Set TEST_XFS_REPAIR_REBUILD=1 to have _check_xfs_filesystem run
> +   xfs_repair -n to check the filesystem; xfs_repair to rebuild metadata
> +   indexes; and xfs_repair -n (a third time) to check the results of the
> +   rebuilding.
> + - xfs_scrub, if present, will always check the test and scratch
> +   filesystems if they are still online at the end of the test. It is no
> +   longer necessary to set TEST_XFS_SCRUB.
> + - Set LOGWRITES_DEV to a block device to use for power fail testing.
> + - Set PERF_CONFIGNAME to a arbitrary string to be used for identifying
> +   the test setup for running perf tests. This should be different for
> +   each type of performance test you wish to run so that relevant results
> +   are compared. For example 'spinningrust' for configurations that use
> +   spinning disks and 'nvme' for tests using nvme drives.
> + - Set USE_KMEMLEAK=yes to scan for memory leaks in the kernel after every
> +   test, if the kernel supports kmemleak.
> + - Set KEEP_DMESG=yes to keep dmesg log after test
> + - Set TEST_FS_MODULE_RELOAD=1 to unload the module and reload it between
> +   test invocations. This assumes that the name of the module is the same
> +   as FSTYP.
> + - Set DUMP_CORRUPT_FS=1 to record metadata dumps of XFS or ext*
> +   filesystems if a filesystem check fails.
> + - Set DUMP_COMPRESSOR to a compression program to compress metadumps of
> +   filesystems. This program must accept '-f' and the name of a file to
> +   compress; and it must accept '-d -f -k' and the name of a file to
> +   decompress. In other words, it must emulate gzip.
> + - Set MIN_FSSIZE to specify the minimal size (bytes) of a filesystem we
> +   can create. Setting this parameter will skip the tests creating a
> +   filesystem less than MIN_FSSIZE.
> + - Set MODPROBE_PATIENT_RM_TIMEOUT_SECONDS to specify the amount of time we
> +   should try a patient module remove. The default is 50 seconds. Set this
> +   to "forever" and we'll wait forever until the module is gone.
> + - Set FORCE_XFS_CHECK_PROG=yes to have _check_xfs_filesystem run xfs_check
> +   to check the filesystem. As of August 2021, xfs_repair finds all
> +   filesystem corruptions found by xfs_check, and more, which means that
> +   xfs_check is no longer run by default.
> + - Set KCONFIG_PATH to specify your preferred location of kernel config
> +   file. The config is used by tests to check if kernel feature is enabled.

I find this harder to read that the previous list - it much denser
text with less whitespace, so individual rules/notes are harder to
separate. I would separate this out into multiple groups that are
blank line separated. e.g:

- Extra TEST device specifications:
	- Set TEST_LOGDEV to "device for test-fs external log"
	- Set TEST_RTDEV to "device for test-fs realtime data"
	- If TEST_LOGDEV and/or TEST_RTDEV, these will always be used.

- Extra SCRATCH device specifications
	- Set SCRATCH_LOGDEV to "device for scratch-fs external log"
	- Set SCRATCH_RTDEV to "device for scratch-fs realtime data"
	- If SCRATCH_LOGDEV and/or SCRATCH_RTDEV, the USE_EXTERNAL
	  environment variable set to "yes" will enable their use.

- Tape device specification for xfsdump testing:
	- Set TAPE_DEV to "tape device for testing xfsdump". Note
	  that if testing xfsdump, make sure the tape devices have a
	  tape which can be overwritten.
	- Set RMT_TAPE_DEV to "remote tape device for testing
	  xfsdump"

(group xfs repair/check configs together)
(group dump configs together)
(etc)

This makes it easier to read and to find different options that
someone might want to use.

Cheers,

Dave.
-- 
Dave Chinner
david@fromorbit.com