Re: Cross-test documentation

["Carlos O'Donell" <carlos at systemhalted dot org>]

On Tue, Oct 30, 2012 at 12:19 PM, Joseph S. Myers
<joseph@codesourcery.com> wrote:
> Perhaps this documentation patch should have had its own subject, rather
> than being buried in another thread.  Anyway, I haven't seen any comments
> on this patch <http://sourceware.org/ml/libc-alpha/2012-10/msg00722.html>;
> here it is again:
>
> 2012-10-25  Joseph Myers  <joseph@codesourcery.com>
>
>         * manual/install.texi (Configuring and compiling): Document
>         general use of test-wrapper and test-wrapper-env.
>         * INSTALL: Regenerated.
>
> diff --git a/INSTALL b/INSTALL
> index 9c62786..03d6eb7 100644
> --- a/INSTALL
> +++ b/INSTALL
> @@ -204,6 +204,17 @@ HOSTNAME is the host name of a system that can run the newly built
>  binaries of the GNU C Library.  The source and build directories must
>  be visible at the same locations on both the build system and HOSTNAME.
>
> +   In general, `test-wrapper' may be set when testing the GNU C Library
> +to the name and arguments of any program to run newly built binaries.

I agree with Andreas that this might be clearer as:
~~~
When testing the GNU C library, the variable `test-wrapper' may be set to
the name and arguments of any program to run the newly built binaries.
~~~

I also think that we need to explain the purpose of the wrapper:
~~~
The primary purpose of `test-wrapper' is to provide a level of
indirection that would allow the test to run on a remote system
during cross-testing.
~~~

That way you set the expectation that this infrastructure is
first and foremost designed for cross-testing, but could be used
for something else.

> +This program must preserve the arguments to the binary being run, its
> +working directory, all environment variables set as part of testing and
> +the standard input, output and error file descriptors.  If
> +`TEST-WRAPPER env' will not work to run a program with environment
> +variables set, then `test-wrapper-env' must be set to a program that
> +runs a newly built program with environment variable assignments in
> +effect, those assignments being specified as `VAR=VALUE' before the
> +name of the program to be run.
> +
>  Installing the C Library
>  ========================
>
> diff --git a/manual/install.texi b/manual/install.texi
> index c82b918..850e696 100644
> --- a/manual/install.texi
> +++ b/manual/install.texi
> @@ -233,6 +233,17 @@ the newly built binaries of @theglibc{}.  The source and build
>  directories must be visible at the same locations on both the build
>  system and @var{hostname}.
>
> +In general, @samp{test-wrapper} may be set when testing @theglibc{} to
> +the name and arguments of any program to run newly built binaries.
> +This program must preserve the arguments to the binary being run, its
> +working directory, all environment variables set as part of testing
> +and the standard input, output and error file descriptors.  If
> +@samp{@var{test-wrapper} env} will not work to run a program with
> +environment variables set, then @samp{test-wrapper-env} must be set to
> +a program that runs a newly built program with environment variable
> +assignments in effect, those assignments being specified as
> +@samp{@var{var}=@var{value}} before the name of the program to be run.
> +
>
>  @node Running make install
>  @appendixsec Installing the C Library

Cheers,
Carlos.