The next important topic besides the default and a sample src_test implementation is probably the declaration of test-only dependencies (and idioms like RESTRICT="!test? ( test )"). The documentation of src_test is currently silent about that topic, while we have a good "Test Dependencies" documentation at a different section of the devmanual. Attached is a patch that forwards the interested reader of the src_test documentation to the related paragraph on test dependencies. Another option would be to move the paragraph "Test Dependencies" from general-concepts/dependencies/#Test Dependencies to ebuild-writing/functions/src_test, *or* create an extra page about ebuild testsuites (ebuild-writing/testing ?). Reproducible: Always
Created attachment 652386 [details, diff] 0001-src_test-link-to-general-concepts-dependencies-Test-.patch
Adding a section just for a single cross reference seems a bit much. Maybe it could be added to one of the existing sections instead?
I considered that but did not find any matching section. Eventually the "Skipping Tests" is of same length. How about merging the sections "Common src_test Tasks", "Skipping Tests", "Sample src_test" and the new "Test Dependencies" into one new section "Writing ebuilds with the 'test' feature enabled", placed right after "Default src_test"?
The "Default ..." and "Sample ..." appear in all chapters about ebuild functions, so I'd rather leave them in place. "Common src_test Tasks", "Skipping Tests", and "Test Dependencies" could be joined though. If they are, the new section should indeed be moved up and placed right after "Sample src_test".
Created attachment 652700 [details, diff] 0001-src_test-re-organize-merge-sections.patch Merged the sections and the information on "Test Dependencies" into a new section right placed after "Sample src_test".
(In reply to Florian Schmaus from comment #5) > Created attachment 652700 [details, diff] [details, diff] > 0001-src_test-re-organize-merge-sections.patch +If the packaged software is equipped with a test suite, it is sensible +to make the package aware of this test suite, allowing the package +manager to run the test suite. Packages with a test suite must announce +the "test" USE flag. Four times "test suite" in two sentences. Certainly this could be worded better? Also, please don't remove the blank lines before block-level elements like <p>. (See the DevBook XML Guide: https://devmanual.gentoo.org/appendices/devbook-guide/index.html#coding-style)
Created attachment 652940 [details, diff] 0001-src_test-re-organize-merge-sections.patch Your are right, changed the text to If the packaged software is equipped with a test suite, it is sensible to make the package aware of it. This allows the package manager to run the software's unit tests. Packages with a test suite must announce the "test" USE flag. Hope that is better.
Devmanual team, please review.
FYI I forgot to re-add the blank lines before the block-level elements. Will do so in the next iteration after the review.
The bug has been closed via the following commit(s): https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b2ad7639d04e296312820025c9b8f77d22272028 commit b2ad7639d04e296312820025c9b8f77d22272028 Author: Florian Schmaus <flo@geekplace.eu> AuthorDate: 2020-08-02 17:17:15 +0000 Commit: Ulrich Müller <ulm@gentoo.org> CommitDate: 2020-08-19 17:29:42 +0000 ebuild-writing/functions/src_test: re-organize, merge sections Merge "Common src_test Tasks" and "Skipping Tests" sections into a new section right after "Sample src_test". Also forward the reader to the related paragraph on test-only dependencies in this new section. Before that, the src_test documentation page was silent about that, rather important, topic. This also includes the RESTRICT="!test? ( test )" idiom. Signed-off-by: Florian Schmaus <flo@geekplace.eu> Closes: https://bugs.gentoo.org/735570 [Whitespace changes] Signed-off-by: Ulrich Müller <ulm@gentoo.org> ebuild-writing/functions/src_test/text.xml | 108 ++++++++++++++++------------- 1 file changed, 60 insertions(+), 48 deletions(-)
Merged. Thank you for the contribution. (In reply to Florian Schmaus from comment #9) > FYI I forgot to re-add the blank lines before the block-level elements. Will > do so in the next iteration after the review. Done.
