[LTP] [PATCH] doc: Add basic shell test description

[Petr Vorel]

> Hi!
> > > > And here would have subtitle "shell loader test library".  Why? It'd be good to
> > > > admit we have plain shell (which uses tst_test.sh) and shell loader. Of course,
> > > > shell loader could be a mentioned first, then old API:

> > > Generally I would like to avoid mixing documentation for different APIs.
> > > I'm afraid that would make things unnecessarily confusing.

> > OK, no problem (I did not get you want to document only Shell Loader). But
> > hiding the fact that vast majority of the shell tests use tst_test.h is not
> > optimal (it might be confusing for new users).

> I'm not trying to hide it. I'm trying to write at least some
> documentation for the shell loader, that is independed task from
> converting the documentation we have for the older shell library into
> rst and putting it in it's own menu item.

Go ahead and merge as is. Actually the only my objections were
that previously "Shell API" was tst_test.sh, now it's shell loader.
I wanted to have the same name "Shell Loader" we have used in git commit logs
to match the docs to not confuse users which API we mean (we now have 3 shell
APIs). But I'm ok with the current version.

> > Also, Shell Loader does not have useful functions from tst_test.h, e.g.
> > ROD(), EXPECT_PASS(). But ok, nobody needs them so far (although ROD() could be
> > useful) and I would also ask people to use C API if possible.

> Indeed the shell loader is currently under construction, but it allows
> us to write a simple tests already and should be good enough for simple
> enough tests.

Sure. I just realized that we might need slightly extend the API during rewrite,
but that's of course not a problem.

> > Could we decide that tst_test.sh becomes "legacy/old" shell API which could be
> > on a separate page doc/developers/legacy_api_shell_tests.rst which would just
> > mention it's deprecated and linked:
> > https://github.com/linux-test-project/ltp/blob/master/doc/old/Shell-Test-API.asciidoc
> > (AI would convert it quickly to RST, but I'd be ok to keep just a link.)

> Yes, that is what I think would be ideal solution, much better than
> mixing the two APIs in a single page.

OK, I'll try to convert it soon, under doc/developers/legacy_api_shell_tests.rst.
There will be a warning - use new "Shell API (which is Shell loader).

> > And test.h becomes undocumented "legacy legacy" shell API (test.h is still used
> > by few tests).

> You mean 'test.sh' I suppose, yes there are a few tests using it. We
> should clean that up eventually.

Yes, I'm sorry, I meant test.sh.

FYI we need to rewrite 52 tests:
$ git grep -l -e ' test\.sh' -e TST_USE_LEGACY_API=1 |wc -l
52

Some of them are very obsolete tests, e.g. power_management, smack, ftrace, ...
I guess that is what holds the rewrite.

9 of them are network tests (ftp/http should be rewritten:
https://github.com/linux-test-project/ltp/issues/1207),
the rest would be trivial to convert even to shell loader.

$ git grep -l TST_USE_LEGACY_API=1 
testcases/network/multicast/mc_cmds/mc_cmds.sh
testcases/network/multicast/mc_commo/mc_commo.sh
testcases/network/multicast/mc_member/mc_member.sh
testcases/network/multicast/mc_opts/mc_opts.sh
testcases/network/stress/dns/dns-stress.sh
testcases/network/stress/ftp/ftp-download-stress.sh
testcases/network/stress/ftp/ftp-upload-stress.sh
testcases/network/stress/http/http-stress.sh
testcases/network/tcp_cmds/tcpdump/tcpdump01.sh

Kind regards,
Petr