Re: [PATCH 3/4] xfstests: Partially expand the documentation [ver #5]

Eryu Guan
2017-04-05T10:42:07Z

On Tue, Apr 04, 2017 at 04:55:25PM +0100, David Howells wrote:
> Partially expand the documentation available in xfstests to include
> requirements checking and auxiliary programs for testing.
>
> Signed-off-by: David Howells <dhowells@redhat.com>
> Reviewed-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>
> doc/auxiliary-programs.txt | 56 ++++++++++++++++++++++++++++++++++
> doc/requirement-checking.txt | 69 ++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 125 insertions(+)
> create mode 100644 doc/auxiliary-programs.txt
> create mode 100644 doc/requirement-checking.txt
>
> diff --git a/doc/auxiliary-programs.txt b/doc/auxiliary-programs.txt
> new file mode 100644
> index 0000000..17797b0
> --- /dev/null
> +++ b/doc/auxiliary-programs.txt
> @@ -0,0 +1,56 @@
> + ==============================
> + AUXILIARY PROGRAMS FOR TESTING
> + ==============================
> +
> +Not everything a test script can do is easily done within a test script;
> +sometimes it makes a lot more sense to write auxiliary program in C and have
> +the test script call them. Auxiliary commands can be found in the src/
> +directory and in other packages.
> +
> +Tests wanting to use an auxiliary program found in the src/ directory should
> +note the dependency with:
> +
> + _require_test_program "<program-name>"
> +
> +
> +Contents:
> +
> + - af_unix -- Create an AF_UNIX socket
> + - stat_test -- statx syscall exercise
> + - xfs_io -- General I/O operation exercise
> +
> +
> +==================
> +QUICK DESCRIPTIONS
> +==================
> +
> +af_unix
> +
> + The af_unix program creates an AF_UNIX socket at the given location.
> +
> +stat_test
> +
> + The stat_test program is primarily designed to exercise the statx()
> + system call. It can check statx() against fstatat() and it can
> + compare and check various file attributes.
> +
> + See also:
> + _require_statx
> +
> +
> +xfs_io
> +
> + The xfs_io program can be found in the xfsprogs package and can be used
> + to perform sequences of I/O commands, though it is limited to what it
> + can do on open files.
> +
> + xfs_io is a debugging tool that is aimed at examining regular file I/O
> + paths rather than a raw XFS volume itself. These code paths include
> + not only the obvious read/write/mmap interfaces for manipulating files,
> + but also cover all of the XFS extensions (such as space preallocation,
> + additional inode flags, etc).
> +
> + Most of its commands can also be used with other filesystems.
> +
> + See also:
> + _require_xfs_io_command
> diff --git a/doc/requirement-checking.txt b/doc/requirement-checking.txt
> new file mode 100644
> index 0000000..29f0b74
> --- /dev/null
> +++ b/doc/requirement-checking.txt
> @@ -0,0 +1,69 @@
> + ========================================
> + TESTING FOR REQUIREMENTS IN TEST SCRIPTS
> + ========================================
> +
> +Test scripts need to indicate to the infrastructure what sorts of requirements
> +they have. This is done with _require_<xxx> macros, which may take parameters.
> +
> + (1) General requirements.
> +
> + _require_command
> + _require_test
> + _require_test_program
> + _require_xfs_io_command
> +
> + (2) System call requirements.
> +
> + _require_statx
> +
> +
> +====================
> +GENERAL REQUIREMENTS
> +====================
> +
> +_require_command "$VAR" name
> +
> + The test requires an external command, called 'name' be present on the
> + system and that '$VAR' should be set with the path to that command. $VAR
> + should then be used to refer to the command when executing it. For
> + example:
> +
> + _require_command "$NC_PROG" "nc"
> +
> + to locate the netcat command and then:
> +
> + $NC_PROG -U -l $TEST_DIR/$seq-sock

Hmm, NC_PROG is not defined/used anymore, perhaps it's not a good
example for document purpose. How about $KILLALL_PROG? It's often
forgotten and it could be a reminder in doc.

Thanks,
Eryu