| 1 |
commit: bcd9a43f9883d32e965080e71d22dc0937ef6464 |
| 2 |
Author: Markos Chandras <hwoarang <AT> gentoo <DOT> org> |
| 3 |
AuthorDate: Sat Nov 3 21:55:48 2012 +0000 |
| 4 |
Commit: Markos Chandras <hwoarang <AT> gentoo <DOT> org> |
| 5 |
CommitDate: Sat Nov 3 22:04:03 2012 +0000 |
| 6 |
URL: http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=bcd9a43f |
| 7 |
|
| 8 |
common-mistakes: Add more 'common-mistakes' from the devrel handbook |
| 9 |
|
| 10 |
--- |
| 11 |
ebuild-writing/common-mistakes/text.xml | 376 ++++++++++++++++++++++++++++++- |
| 12 |
1 files changed, 370 insertions(+), 6 deletions(-) |
| 13 |
|
| 14 |
diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml |
| 15 |
index fb4f0d2..cf7eabc 100644 |
| 16 |
--- a/ebuild-writing/common-mistakes/text.xml |
| 17 |
+++ b/ebuild-writing/common-mistakes/text.xml |
| 18 |
@@ -11,6 +11,10 @@ writing ebuilds. |
| 19 |
</body> |
| 20 |
|
| 21 |
<section> |
| 22 |
+<title>Common Ebuild Writing Mistakes</title> |
| 23 |
+<body> |
| 24 |
+ |
| 25 |
+<subsection> |
| 26 |
<title>Invalid use of <c>static</c> use-flag</title> |
| 27 |
<body> |
| 28 |
The <c>static</c> use-flag should only be used to make a binary use static |
| 29 |
@@ -18,9 +22,9 @@ linking instead of dynamic linking. It should not be used to make a library |
| 30 |
install static libraries. The package should always (if possible) install both |
| 31 |
the dynamic and static libraries. |
| 32 |
</body> |
| 33 |
-</section> |
| 34 |
+</subsection> |
| 35 |
|
| 36 |
-<section> |
| 37 |
+<subsection> |
| 38 |
<title>Invalid use of <c>ROOT</c></title> |
| 39 |
<body> |
| 40 |
<p> |
| 41 |
@@ -34,9 +38,9 @@ functions is not allowed. |
| 42 |
See also <uri link="::ebuild-writing/variables#ROOT"/>. |
| 43 |
</p> |
| 44 |
</body> |
| 45 |
-</section> |
| 46 |
+</subsection> |
| 47 |
|
| 48 |
-<section> |
| 49 |
+<subsection> |
| 50 |
<title>Referencing the full path to documentation files that could be |
| 51 |
compressed</title> |
| 52 |
<body> |
| 53 |
@@ -55,9 +59,9 @@ Do something like: |
| 54 |
elog "They are listed in the INSTALL file in /usr/share/doc/${PF}" |
| 55 |
</codesample> |
| 56 |
</body> |
| 57 |
-</section> |
| 58 |
+</subsection> |
| 59 |
|
| 60 |
-<section> |
| 61 |
+<subsection> |
| 62 |
<title>Build log not verbose</title> |
| 63 |
<body> |
| 64 |
When writing ebuilds, you should always check the build log, because the build |
| 65 |
@@ -86,6 +90,366 @@ option like 'V=1' to enable full verbosity. |
| 66 |
<note> If you notice non-verbose build log in any package open a bug and make it block the |
| 67 |
tracker bug #429308</note> |
| 68 |
</body> |
| 69 |
+</subsection> |
| 70 |
+ |
| 71 |
+<subsection> |
| 72 |
+<title>Missing/Invalid/Broken Header</title> |
| 73 |
+<body> |
| 74 |
+ |
| 75 |
+<p> |
| 76 |
+When you submit your ebuilds, the header should be <e>exactly</e> the same as |
| 77 |
+the one in <path>/usr/portage/skel.ebuild</path>. Most importantly, do not |
| 78 |
+modify it in any way and make sure that the <c>$Header: $</c> line is |
| 79 |
+intact. |
| 80 |
+</p> |
| 81 |
+ |
| 82 |
+<p> |
| 83 |
+The first three lines <e>must</e> look like this: |
| 84 |
+</p> |
| 85 |
+ |
| 86 |
+<pre caption="Valid Header"> |
| 87 |
+# Copyright 1999-2004 Gentoo Foundation |
| 88 |
+# Distributed under the terms of the GNU General Public License v2 |
| 89 |
+# $Header: $ |
| 90 |
+</pre> |
| 91 |
+ |
| 92 |
+<p> |
| 93 |
+Only if you are submitting a patched or version bumped ebuild, should you not |
| 94 |
+need to modify the <c>$Header: $</c> line. But the line must be present. |
| 95 |
+When we check the ebuild into CVS, it will modify that header with the |
| 96 |
+appropriate version and date information. So there is no need for you to |
| 97 |
+manually modify it. |
| 98 |
+</p> |
| 99 |
+ |
| 100 |
+</body> |
| 101 |
+</subsection> |
| 102 |
+<subsection> |
| 103 |
+<title>IUSE Missing</title> |
| 104 |
+<body> |
| 105 |
+ |
| 106 |
+<p> |
| 107 |
+By far the most common omission is the IUSE variable. You must (according to the |
| 108 |
+<uri link="::ebuild-writing/variables#iuse">Ebuild Writing tutorial</uri>) include the IUSE |
| 109 |
+variable even if there are no USE flags in use. If there are no USE flags |
| 110 |
+supported, then just add the following: |
| 111 |
+</p> |
| 112 |
+ |
| 113 |
+<pre caption="Empty IUSE"> |
| 114 |
+IUSE="" |
| 115 |
+</pre> |
| 116 |
+ |
| 117 |
+</body> |
| 118 |
+</subsection> |
| 119 |
+<subsection> |
| 120 |
+<title>Redefined P, PV, PN, PF</title> |
| 121 |
+<body> |
| 122 |
+ |
| 123 |
+<p> |
| 124 |
+You should never redefine those variables. Always use MY_P, MY_PN, MY_PV, |
| 125 |
+P0, etc. See other ebuilds that do it in portage for more information. Most |
| 126 |
+ebuilds use bash "Parameter Expansion". Please read the man page for bash to |
| 127 |
+understand how "Parameter Expansion" works. |
| 128 |
+</p> |
| 129 |
+ |
| 130 |
+<p> |
| 131 |
+By the way, if you find a package that re-defines it, don't copy it. Submit a |
| 132 |
+bug about that ebuild. |
| 133 |
+</p> |
| 134 |
+ |
| 135 |
+</body> |
| 136 |
+</subsection> |
| 137 |
+<subsection> |
| 138 |
+<title>Including version numbers in SRC_URI and S</title> |
| 139 |
+<body> |
| 140 |
+ |
| 141 |
+<p> |
| 142 |
+You should try not to include version numbers in the SRC_URI and S. Always try |
| 143 |
+to use ${PV} or ${P}. It makes maintaining the ebuild much easier. If a version |
| 144 |
+number is not consistent with the tarball/source, then use MY_P. An example |
| 145 |
+dev-python/pyopenal fetches a tarball called PyOpenAL, so we redefine it like: |
| 146 |
+</p> |
| 147 |
+ |
| 148 |
+<pre caption="Example versioning redefinition"> |
| 149 |
+MY_P=${P/pyopenal/PyOpenAL} |
| 150 |
+SRC_URI="http://oomadness.tuxfamily.org/downloads/${MY_P}.tar.gz" |
| 151 |
+S=${WORKDIR}/${MY_P} |
| 152 |
+</pre> |
| 153 |
+ |
| 154 |
+</body> |
| 155 |
+</subsection> |
| 156 |
+<subsection> |
| 157 |
+<title>DEPEND has syntactical errors</title> |
| 158 |
+<body> |
| 159 |
+ |
| 160 |
+<p> |
| 161 |
+There are many things that go wrong with user submitted DEPEND and RDEPEND |
| 162 |
+fields. Here are some important points to follow when you write the dependency |
| 163 |
+part. |
| 164 |
+</p> |
| 165 |
+ |
| 166 |
+<ul> |
| 167 |
+ <li> |
| 168 |
+ <e>Always include the CATEGORY.</e><br /> |
| 169 |
+ For example, use <c>>=x11-libs/gtk+-2</c> and not <c>>=gtk+-2</c>. |
| 170 |
+ </li> |
| 171 |
+ <li> |
| 172 |
+ <e>Do not put an asterisk (*) for >= dependencies.</e><br /> |
| 173 |
+ For example, it should be <c>>=x11-libs/gtk+-2</c> rather than |
| 174 |
+ <c>>=x11-libs/gtk+-2*</c>. |
| 175 |
+ </li> |
| 176 |
+ <li><e>GTK specific. Always use =x11-libs/gtk+-1.2* for GTK+1 apps.</e></li> |
| 177 |
+ <li> |
| 178 |
+ <e>Never depend on a meta package.</e><br /> |
| 179 |
+ So don't depend on gnome-base/gnome, always depend on the specific |
| 180 |
+ libraries like libgnome. |
| 181 |
+ </li> |
| 182 |
+ <li> |
| 183 |
+ <e>One dependency per line.</e><br /> |
| 184 |
+ Don't put multiple dependency on the same line. It makes it ugly to read |
| 185 |
+ and hard to follow. |
| 186 |
+ </li> |
| 187 |
+</ul> |
| 188 |
+ |
| 189 |
+</body> |
| 190 |
+</subsection> |
| 191 |
+<subsection> |
| 192 |
+<title>DEPEND is incomplete</title> |
| 193 |
+<body> |
| 194 |
+ |
| 195 |
+<p> |
| 196 |
+This is another very common error. The ebuild submitter submits an ebuild |
| 197 |
+that "just works" without checking if the dependencies are correct. Here are |
| 198 |
+some tips on how to find the correct dependencies. |
| 199 |
+</p> |
| 200 |
+ |
| 201 |
+<ul> |
| 202 |
+ <li> |
| 203 |
+ <e>Look in configure.in or configure.ac</e><br /> |
| 204 |
+ Look for checks for packages in here. Things to look out for are pkg-config |
| 205 |
+ checks or AM_* functions that check for a specific version. |
| 206 |
+ </li> |
| 207 |
+ <li> |
| 208 |
+ <e>Look at included .spec files</e><br /> |
| 209 |
+ A good indication of dependencies is to look at the included .spec files |
| 210 |
+ for relevant deps. However, do not trust them to be the definitive complete |
| 211 |
+ list of dependencies |
| 212 |
+ </li> |
| 213 |
+ <li> |
| 214 |
+ <e>Look at the application/library website</e><br /> |
| 215 |
+ Check the application website for possible dependencies that they suggest |
| 216 |
+ are needed. |
| 217 |
+ </li> |
| 218 |
+ <li> |
| 219 |
+ <e>Read the README and INSTALL for the package</e><br /> |
| 220 |
+ They usually also contain useful information about building and installing |
| 221 |
+ packages. |
| 222 |
+ </li> |
| 223 |
+ <li> |
| 224 |
+ <e>Remember non-binary dependencies such as pkg-config, doc generation |
| 225 |
+ programs, etc.</e><br /> |
| 226 |
+ Usually the build process requires some dependencies such as intltool, |
| 227 |
+ libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those |
| 228 |
+ are clearly stated. |
| 229 |
+ </li> |
| 230 |
+</ul> |
| 231 |
+ |
| 232 |
+</body> |
| 233 |
+</subsection> |
| 234 |
+<subsection> |
| 235 |
+<title>LICENSE Invalid</title> |
| 236 |
+<body> |
| 237 |
+ |
| 238 |
+<p> |
| 239 |
+Another common mistake users make when submitting ebuilds is supplying an |
| 240 |
+invalid license. For example, <c>GPL</c> is not a valid license. You need to |
| 241 |
+specify <c>GPL-1</c> or <c>GPL-2</c>. Same with <c>LGPL</c>. Make sure the |
| 242 |
+license you use in the <c>LICENSE</c> field is something that exists in |
| 243 |
+<path>/usr/portage/licenses</path>. As a tip, check the <path>COPYING</path> |
| 244 |
+in a source tarball for the license. If a package does not specify it |
| 245 |
+uses <c>GPL-1</c> or <c>GPL-2</c>, it is very likely it uses <c>GPL-2</c>. |
| 246 |
+</p> |
| 247 |
+ |
| 248 |
+<p> |
| 249 |
+If the license for the package you submit is unique and not in |
| 250 |
+<path>/usr/portage/licenses/</path>, then you must submit the new license in a |
| 251 |
+separate file. |
| 252 |
+</p> |
| 253 |
+ |
| 254 |
+</body> |
| 255 |
+</subsection> |
| 256 |
+<subsection> |
| 257 |
+<title>Untested ARCHs in KEYWORDS</title> |
| 258 |
+<body> |
| 259 |
+ |
| 260 |
+<p> |
| 261 |
+Please do not add other ARCHs into KEYWORDS unless the ebuild has been tested on |
| 262 |
+that ARCH. Also all new ebuilds should be ~x86 or whatever architecture it is. |
| 263 |
+Make sure when you bump a version, the stable KEYWORDS are all marked as |
| 264 |
+<c>~</c>. |
| 265 |
+</p> |
| 266 |
+ |
| 267 |
+</body> |
| 268 |
+</subsection> |
| 269 |
+<subsection> |
| 270 |
+<title>SLOT missing</title> |
| 271 |
+<body> |
| 272 |
+ |
| 273 |
+<p> |
| 274 |
+Make sure you have the SLOT variable in the ebuild. If you don't plan to use it, |
| 275 |
+don't remove it. Put in: |
| 276 |
+</p> |
| 277 |
+ |
| 278 |
+<pre caption="Default SLOT variable"> |
| 279 |
+SLOT="0" |
| 280 |
+</pre> |
| 281 |
+ |
| 282 |
+</body> |
| 283 |
+</subsection> |
| 284 |
+<subsection> |
| 285 |
+<title>DESCRIPTION and HOMEPAGE wrong</title> |
| 286 |
+<body> |
| 287 |
+ |
| 288 |
+<p> |
| 289 |
+Please check if the HOMEPAGE variable is right and leads users to the right |
| 290 |
+page if they want to find out more about the package. And make sure the |
| 291 |
+DESCRIPTION is not overly long. Good descriptions will describe the main |
| 292 |
+function of the package in a sentence. |
| 293 |
+</p> |
| 294 |
+ |
| 295 |
+</body> |
| 296 |
+</subsection> |
| 297 |
+<subsection> |
| 298 |
+<title>Wrongfully used spaces instead of TABS</title> |
| 299 |
+<body> |
| 300 |
+ |
| 301 |
+<p> |
| 302 |
+It is no fun reformatting lines of ebuilds because the submitter did not follow |
| 303 |
+the guidelines to use TABS rather than spaces. So <e>please</e> use tabs! |
| 304 |
+</p> |
| 305 |
+ |
| 306 |
+</body> |
| 307 |
+</subsection> |
| 308 |
+<subsection> |
| 309 |
+<title>Trailing whitespace</title> |
| 310 |
+<body> |
| 311 |
+ |
| 312 |
+<p> |
| 313 |
+I'm often guilty of this. Remember to run repoman over your ebuilds so it can |
| 314 |
+tell you if there is trailing whitespace at the end of lines or on empty lines. |
| 315 |
+</p> |
| 316 |
+ |
| 317 |
+</body> |
| 318 |
+</subsection> |
| 319 |
+<subsection> |
| 320 |
+<title>Adding redundant S=${WORKDIR}/${P}</title> |
| 321 |
+<body> |
| 322 |
+ |
| 323 |
+<p> |
| 324 |
+If <c>S=${WORKDIR}/${P}</c>, then you should not add it to your ebuild. This is |
| 325 |
+implied already, you should only add it if it is something other than |
| 326 |
+<c>${WORKDIR}/${P}</c>. |
| 327 |
+</p> |
| 328 |
+ |
| 329 |
+</body> |
| 330 |
+</subsection> |
| 331 |
+<subsection> |
| 332 |
+<title>Documentation missing</title> |
| 333 |
+<body> |
| 334 |
+ |
| 335 |
+<p> |
| 336 |
+If your package has documentation, make sure you install it using <c>dodoc</c> |
| 337 |
+or in <path>/usr/share/doc/${PF}</path>. Remember to check for errors when |
| 338 |
+running <c>dodoc</c>/<c>doins</c>. |
| 339 |
+</p> |
| 340 |
+ |
| 341 |
+</body> |
| 342 |
+</subsection> |
| 343 |
+ |
| 344 |
+</body> |
| 345 |
+</section> |
| 346 |
+ |
| 347 |
+ |
| 348 |
+<section> |
| 349 |
+<title>Common Ebuild Submission Mistakes</title> |
| 350 |
+<subsection> |
| 351 |
+<title>Introduction</title> |
| 352 |
+<body> |
| 353 |
+ |
| 354 |
+<p> |
| 355 |
+Please submit ebuilds properly by following the <uri |
| 356 |
+link="::ebuild-writing/ebuild-maintenance#adding-a-new-ebuild">Adding new Ebuild</uri> tutorial. |
| 357 |
+</p> |
| 358 |
+ |
| 359 |
+</body> |
| 360 |
+</subsection> |
| 361 |
+<subsection> |
| 362 |
+<title>Tarball'ing an ebuild</title> |
| 363 |
+<body> |
| 364 |
+ |
| 365 |
+<p> |
| 366 |
+Please please please do not attach ebuilds as tarballs. Attach patches |
| 367 |
+separately as well so we can easily examine them. |
| 368 |
+</p> |
| 369 |
+ |
| 370 |
+</body> |
| 371 |
+</subsection> |
| 372 |
+<subsection> |
| 373 |
+<title>Inlining Ebuilds</title> |
| 374 |
+<body> |
| 375 |
+ |
| 376 |
+<p> |
| 377 |
+Don't cut and paste an ebuild into bugzilla's comment field. |
| 378 |
+</p> |
| 379 |
+ |
| 380 |
+</body> |
| 381 |
+</subsection> |
| 382 |
+<subsection> |
| 383 |
+<title>No description on what the package is</title> |
| 384 |
+<body> |
| 385 |
+ |
| 386 |
+<p> |
| 387 |
+Please let us know what the package is, and fill in the URL with the home page |
| 388 |
+of the application, if any exists. |
| 389 |
+</p> |
| 390 |
+ |
| 391 |
+</body> |
| 392 |
+</subsection> |
| 393 |
+<subsection> |
| 394 |
+<title>Package updates without changing the ChangeLog</title> |
| 395 |
+<body> |
| 396 |
+ |
| 397 |
+<p> |
| 398 |
+If you submit a package update, then make sure you explain what changes you made |
| 399 |
+to the ebuild. For example if a package introduces a new features/option and you |
| 400 |
+use a USE flag, list it in your bug. Don't make us hunt for it. |
| 401 |
+</p> |
| 402 |
+ |
| 403 |
+<p> |
| 404 |
+It is wise to submit a diff for a package update rather than the whole ebuild. |
| 405 |
+The best way to generate it would be: |
| 406 |
+</p> |
| 407 |
+ |
| 408 |
+<pre caption="Creating a diff"> |
| 409 |
+$ <i>diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.diff</i> |
| 410 |
+</pre> |
| 411 |
+ |
| 412 |
+</body> |
| 413 |
+</subsection> |
| 414 |
+<subsection> |
| 415 |
+<title>Submitting unchanged ebuilds for version bumps</title> |
| 416 |
+<body> |
| 417 |
+ |
| 418 |
+<p> |
| 419 |
+If you are submitting a new version for a package in portage, make sure the |
| 420 |
+existing ebuild works and make sure changes are incorporated in the new ebuild |
| 421 |
+(such as added documentation.) If there are no required changes to the ebuild |
| 422 |
+from the previous version, then don't attach the ebuild. Just say so in the bug |
| 423 |
+report that you copied the ebuild over and verified that the package works and |
| 424 |
+installs properly. |
| 425 |
+</p> |
| 426 |
+ |
| 427 |
+</body> |
| 428 |
+</subsection> |
| 429 |
</section> |
| 430 |
|
| 431 |
</chapter> |
Archives