| 1 |
commit: b2ad7639d04e296312820025c9b8f77d22272028 |
| 2 |
Author: Florian Schmaus <flo <AT> geekplace <DOT> eu> |
| 3 |
AuthorDate: Sun Aug 2 17:17:15 2020 +0000 |
| 4 |
Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Wed Aug 19 17:29:42 2020 +0000 |
| 6 |
URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b2ad7639 |
| 7 |
|
| 8 |
ebuild-writing/functions/src_test: re-organize, merge sections |
| 9 |
|
| 10 |
Merge "Common src_test Tasks" and "Skipping Tests" sections into a new |
| 11 |
section right after "Sample src_test". |
| 12 |
|
| 13 |
Also forward the reader to the related paragraph on test-only |
| 14 |
dependencies in this new section. Before that, the src_test |
| 15 |
documentation page was silent about that, rather important, |
| 16 |
topic. This also includes the RESTRICT="!test? ( test )" idiom. |
| 17 |
|
| 18 |
Signed-off-by: Florian Schmaus <flo <AT> geekplace.eu> |
| 19 |
Closes: https://bugs.gentoo.org/735570 |
| 20 |
[Whitespace changes] |
| 21 |
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org> |
| 22 |
|
| 23 |
ebuild-writing/functions/src_test/text.xml | 108 ++++++++++++++++------------- |
| 24 |
1 file changed, 60 insertions(+), 48 deletions(-) |
| 25 |
|
| 26 |
diff --git a/ebuild-writing/functions/src_test/text.xml b/ebuild-writing/functions/src_test/text.xml |
| 27 |
index c278aa0..fbd0751 100644 |
| 28 |
--- a/ebuild-writing/functions/src_test/text.xml |
| 29 |
+++ b/ebuild-writing/functions/src_test/text.xml |
| 30 |
@@ -62,6 +62,66 @@ src_test() { |
| 31 |
</body> |
| 32 |
</section> |
| 33 |
|
| 34 |
+<section> |
| 35 |
+<title>Supporting test suites in packages</title> |
| 36 |
+<body> |
| 37 |
+ |
| 38 |
+<p> |
| 39 |
+If the packaged software is equipped with a test suite, it is sensible |
| 40 |
+to make the package aware of it. This allows the package manager to |
| 41 |
+run the software's unit tests. Packages with a test suite must |
| 42 |
+announce the "test" USE flag. |
| 43 |
+</p> |
| 44 |
+ |
| 45 |
+<codesample lang="ebuild"> |
| 46 |
+IUSE="test" |
| 47 |
+</codesample> |
| 48 |
+ |
| 49 |
+<p> |
| 50 |
+The next important aspect to consider are test-only dependencies, i.e. |
| 51 |
+dependencies that are only required to run the test suite. Test-only |
| 52 |
+dependencies should be specified in a DEPEND behind a USE flag. |
| 53 |
+Please refer to the section on |
| 54 |
+<uri link="::general-concepts/dependencies/#Test Dependencies"/> |
| 55 |
+for more information. |
| 56 |
+</p> |
| 57 |
+ |
| 58 |
+<p> |
| 59 |
+Often the default <c>src_test</c> is fine. Sometimes it is necessary |
| 60 |
+to remove certain tests from the list if they cannot be used with a |
| 61 |
+portage environment. Reasons for such a failure could include: |
| 62 |
+</p> |
| 63 |
+ |
| 64 |
+<ul> |
| 65 |
+ <li> |
| 66 |
+ Needing to work with files which are disallowed by the sandbox. |
| 67 |
+ </li> |
| 68 |
+ <li>Requiring user input (<c>src_test</c> must not be interactive).</li> |
| 69 |
+ <li>Requiring root privileges.</li> |
| 70 |
+</ul> |
| 71 |
+ |
| 72 |
+<p> |
| 73 |
+Usually, removing the relevant test from the <c>Makefile</c> |
| 74 |
+using <c>sed</c> or skipping a particular <c>make</c> target is |
| 75 |
+sufficient. |
| 76 |
+</p> |
| 77 |
+ |
| 78 |
+<p> |
| 79 |
+Try to ensure that tests work properly for your ebuild. A good test |
| 80 |
+suite is extremely helpful for arch maintainers. |
| 81 |
+Sometimes it is necessary to skip tests entirely. This can be done by |
| 82 |
+setting <c>RESTRICT="test"</c> in the ebuild. |
| 83 |
+</p> |
| 84 |
+ |
| 85 |
+<note> |
| 86 |
+If upstream provides a test suite that doesn't work, consider talking |
| 87 |
+to them about getting it fixed. A broken test suite requires developers |
| 88 |
+to investigate each test failure in order to determine whether it is |
| 89 |
+genuine or indicates a broken test. |
| 90 |
+</note> |
| 91 |
+</body> |
| 92 |
+</section> |
| 93 |
+ |
| 94 |
<section> |
| 95 |
<title>Tests that require network or service access</title> |
| 96 |
<body> |
| 97 |
@@ -207,53 +267,5 @@ src_test() { |
| 98 |
</body> |
| 99 |
</section> |
| 100 |
|
| 101 |
-<section> |
| 102 |
-<title>Common <c>src_test</c> Tasks</title> |
| 103 |
-<body> |
| 104 |
-<p> |
| 105 |
-Often the default <c>src_test</c> is fine. Sometimes it is necessary |
| 106 |
-to remove certain tests from the list if they cannot be used with a |
| 107 |
-portage environment. Reasons for such a failure could include: |
| 108 |
-</p> |
| 109 |
- |
| 110 |
-<ul> |
| 111 |
- <li> |
| 112 |
- Needing to work with files which are disallowed by the sandbox. |
| 113 |
- </li> |
| 114 |
- <li>Requiring user input (src_test must not be interactive).</li> |
| 115 |
- <li>Requiring root privileges.</li> |
| 116 |
-</ul> |
| 117 |
- |
| 118 |
-<p> |
| 119 |
-Usually, removing the relevant test from the <c>Makefile</c> |
| 120 |
-using <c>sed</c> or skipping a particular <c>make</c> target is |
| 121 |
-sufficient. |
| 122 |
-</p> |
| 123 |
- |
| 124 |
-<p> |
| 125 |
-Try to ensure that tests work properly for your ebuild. A good test |
| 126 |
-suite is extremely helpful for arch maintainers. |
| 127 |
-</p> |
| 128 |
- |
| 129 |
-</body> |
| 130 |
-</section> |
| 131 |
- |
| 132 |
-<section> |
| 133 |
-<title>Skipping Tests</title> |
| 134 |
-<body> |
| 135 |
-<p> |
| 136 |
-Sometimes it is necessary to skip tests entirely. This can be done by |
| 137 |
-setting <c>RESTRICT="test"</c> in the ebuild. |
| 138 |
-</p> |
| 139 |
- |
| 140 |
-<note> |
| 141 |
-If upstream provides a test suite that doesn't work, consider talking |
| 142 |
-to them about getting it fixed. A broken test suite requires developers |
| 143 |
-to investigate each test failure in order to determine whether it is |
| 144 |
-genuine or indicates a broken test. |
| 145 |
-</note> |
| 146 |
-</body> |
| 147 |
-</section> |
| 148 |
- |
| 149 |
</chapter> |
| 150 |
</guide> |
Archives