[v2] doc: add 'cd' command before 'make check-gcc' command in install.texi

This patch add 'cd' command before 'make check-gcc' command
when run the testsuite on selected tests.

Richard and I agree it would be good for clarity and
emphasis to have the cd in the example as well, although
the text above the example was trying to restrict that to
objdir/gcc.

Tested on x86_64. OK for master?

Regards!
Hujp

---
 gcc/doc/install.texi | 17 +++++++++--------
 1 file changed, 9 insertions(+), 8 deletions(-)

On Sat, 29 Aug 2020, Hu Jiangping wrote:

> This patch add 'cd' command before 'make check-gcc' command
> when run the testsuite on selected tests.

No, don't do that; those targets work fine from the toplevel
too, and then include the language libs.

> Richard and I agree it would be good for clarity and
> emphasis to have the cd in the example as well, although
> the text above the example was trying to restrict that to
> objdir/gcc.

Aha, I guess you misinterpreted the existing "cd @var{objdir};
make -k check", because I see no /gcc there.

Please remove the /gcc from the patch.

Some <specific>.exp just exist in the gcc dir, but that's not
the point of these examples and the extra iteration from the
toplevel doesn't take more than a second or two.  The bigger
risk is missing testing in the target libraries.

(Incidentally, while GNU make is required such that "-C objdir"
would be equivalent, for newcomers I agree the "cd" is
clearer in examples.)

brgds, H-P

Hi, H-P

Thanks for comment.

> On Sat, 29 Aug 2020, Hu Jiangping wrote:
> 
> > This patch add 'cd' command before 'make check-gcc' command
> > when run the testsuite on selected tests.
> 
> No, don't do that; those targets work fine from the toplevel
> too, and then include the language libs.
Yes, I know that 'make check-gcc' work well from the toplevel,
but 'make check-g++' does not. Is there anything wrong with
the Makefile?

I pasted the original error in the v1 submitting text.
https://gcc.gnu.org/pipermail/gcc-patches/2020-August/552761.html

> 
> > Richard and I agree it would be good for clarity and
> > emphasis to have the cd in the example as well, although
> > the text above the example was trying to restrict that to
> > objdir/gcc.
> 
> Aha, I guess you misinterpreted the existing "cd @var{objdir};
> make -k check", because I see no /gcc there.
Does the "cd @var{objdir}; make -k check" mean to execute command
from the toplevel.

I understand the context like this:
1. We can execute 'make -k check' from the toplevel to run all testsuites
2. And also, We can execute 'make check-gcc' from gcc subdirectory
   to run selected targets
3. And 'A more selective way', We can execute command with 'RUNTESTFLAGS' 
   option to run selected test(s).

	"In order to run sets of tests selectively, there are targets
	@samp{make check-gcc}, @samp{make check-g++} and language specific
	@samp{make check-c},
	@samp{make check-c++}, @samp{make check-d}, @samp{make check-fortran},
	@samp{make check-ada}, @samp{make check-objc}, @samp{make check-obj-c++},
	@samp{make check-lto}
	in the @file{gcc} subdirectory of the object directory.  You can also
	just run @samp{make check} in a subdirectory of the object directory."

I think the text above the 'make check-gcc' command implies point 2.
So, if the following commands which are examples of point 3 are also
executed from gcc subdirectory, it will make the context more logical
(The tests to be performed are more specific than point 2).

But it does not mean the commands must be executed from gcc subdirectory.
If anyone wants to execute the testsuites including the target libraries,
he should refer to other documents, or directly the Makefile under toplevel.
Or we can make a note here to illustrate that.

	i.e.:
	Note that if run 'make check-testsuite' from the object directory,
      not only the tests under gcc subdirectory but also the tests under
      the target libriaries will be performed.

What do you think?

Regards!
Hujp

> 
> Please remove the /gcc from the patch.
> 
> Some <specific>.exp just exist in the gcc dir, but that's not
> the point of these examples and the extra iteration from the
> toplevel doesn't take more than a second or two.  The bigger
> risk is missing testing in the target libraries.
> 
> (Incidentally, while GNU make is required such that "-C objdir"
> would be equivalent, for newcomers I agree the "cd" is
> clearer in examples.)
> 
> brgds, H-P
>

On Mon, 7 Sep 2020, Hu, Jiangping wrote:
> Hi, H-P
>
> Thanks for comment.
>
> > On Sat, 29 Aug 2020, Hu Jiangping wrote:
> >
> > > This patch add 'cd' command before 'make check-gcc' command
> > > when run the testsuite on selected tests.
> >
> > No, don't do that; those targets work fine from the toplevel
> > too, and then include the language libs.
> Yes, I know that 'make check-gcc' work well from the toplevel,
> but 'make check-g++' does not. Is there anything wrong with
> the Makefile?

IIUC check-g++ is somewhat a historic artefact, but for
consistency it should be added to the toplevel Makefile too as
a synonym for check-c++.

> 	i.e.:
> 	Note that if run 'make check-testsuite' from the object directory,
>       not only the tests under gcc subdirectory but also the tests under
>       the target libriaries will be performed.

(There's no "make check-testsuite".)

> What do you think?

I think that after re-reading the patch, I retract my objection,
thanks.

FWIW, note also "check-gcc-<LANGUAGE>" where LANGUAGE="c, c++,
fortran, ada" which do consider the library testsuite.

brgds, H-P

Hi, H-P

> > > On Sat, 29 Aug 2020, Hu Jiangping wrote:
> > >
> > > > This patch add 'cd' command before 'make check-gcc' command
> > > > when run the testsuite on selected tests.
> > >
> > > No, don't do that; those targets work fine from the toplevel
> > > too, and then include the language libs.
> > Yes, I know that 'make check-gcc' work well from the toplevel,
> > but 'make check-g++' does not. Is there anything wrong with
> > the Makefile?
> 
> IIUC check-g++ is somewhat a historic artefact, but for
> consistency it should be added to the toplevel Makefile too as
> a synonym for check-c++.
Thanks for your suggestion. I'm submitting a patch for that.
Any advice will be appreciated.

> 
> > 	i.e.:
> > 	Note that if run 'make check-testsuite' from the object directory,
> >       not only the tests under gcc subdirectory but also the tests under
> >       the target libriaries will be performed.
> 
> (There's no "make check-testsuite".)
Oh, I mean 'check-@var{testsuite}'.

If the patch for Makefile is ok, then the patch here will be modified accordingly. 
For example, it is no need to add cd objdir/gcc before the ‘make check-<testsuite>’
commands, but in the text above the commands we need to describe the difference
between the targets in the gcc subdirectory and the object directory.

Regards!
Hujp

> 
> > What do you think?
> 
> I think that after re-reading the patch, I retract my objection,
> thanks.
> 
> FWIW, note also "check-gcc-<LANGUAGE>" where LANGUAGE="c, c++,
> fortran, ada" which do consider the library testsuite.
> 
> brgds, H-P
>