Re: Documenting test script arguments and revising runtest_file_p

[Jacob Bachmeyer]

Ben Elliston wrote:
> On Fri, Jan 11, 2019 at 07:02:09PM -0600, Jacob Bachmeyer wrote:
>
>   
> > Also, runtest_file_p tries to hide the structure of runtests, but
> > should also implicitly use it, instead of requiring that it be
> > passed as an argument.
> >     
>
> Keep in mind that runtest_file_p is part of the DejaGnu library
> API. It is used by some testsuites such as for GCC. I don't think we
> can easily do much with it.
>   

Currently, runtest_file_p can only be called with two arguments.  I 
propose permitting it to be called with one argument, effectively making 
the first argument optional.  Existing calls will continue to work (and 
the testsuite will continue to exercise this, as it is more convenient 
for testing multiple cases quickly) but newer code can use a cleaner 
"runtest_file_p $file" instead of needing to explicitly refer to the 
"runtests" variable.

Actually removing global "runtests" would be one of the breaking changes 
for DejaGnu 2.0, after a lengthy deprecation period, if done at all.

Is the contents of the "runtests" variable part of the DejaGnu API 
currently?  The variable is not documented and runtest_file_p exists to 
abstract its meaning.

I suppose the real question is:  should "runtests" be promoted to "API" 
status or should some new mechanism be added for passing arguments to 
test scripts?

...and I looked at the runtest_file_p API documentation and it is wrong; 
patch included below:

----
ChangeLog entry:
        * doc/dejagnu.texi (runtest_file_p procedure): Fix description of
        the structure of the "runtests" argument.
---
diff --git a/doc/dejagnu.texi b/doc/dejagnu.texi
index 11d433e..7e2f1be 100644
--- a/doc/dejagnu.texi
+++ b/doc/dejagnu.texi
@@ -4984,8 +4984,8 @@ is a file.
@table @asis
@item @code{runtests}

address@hidden is a list of two elements.  The first is a copy of what
-was on the right side of the @code{=} if @code{foo.exp="..."} was
address@hidden is a list of two elements.  The second is a copy of
+what was on the right side of the @code{=} if @code{foo.exp="..."} was
specified, or an empty string if no such argument is present.

@item @code{testcase}
----



-- Jacob