diff options
Diffstat (limited to 'ebuild-writing')
48 files changed, 5009 insertions, 3159 deletions
diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index ff906fd..134990c 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/common-mistakes/"> <chapter> -<title>Common Mistakes</title> +<title>Common mistakes</title> <body> <p> @@ -11,15 +11,30 @@ writing ebuilds. </body> <section> -<title>Common Ebuild Writing Mistakes</title> +<title>Common ebuild writing mistakes</title> + +<subsection> +<title>Unguarded external calls</title> <body> +<p> +Calls to external tools should be guarded with <c>|| die</c> (or use +<c>assert</c>) in almost all cases to allow failure to be detected. +See <uri link="::ebuild-writing/error-handling/"/>. +</p> + +</body> +</subsection> + <subsection> -<title>Invalid use of <c>static</c> use-flag</title> +<title>Invalid use of <c>static</c> USE flag</title> <body> +<p> The <c>static</c> use-flag should only be used to make a binary use static linking instead of dynamic linking. It should not be used to make a library -install static libraries. Instead, the <c>static-libs</c> use-flag is used for this. +install static libraries. Instead, the <c>static-libs</c> use-flag is used for +this. +</p> </body> </subsection> @@ -28,13 +43,16 @@ install static libraries. Instead, the <c>static-libs</c> use-flag is used for t <body> <p> The usage of <c>ROOT</c> is only designed to influence the way the package is -installed (ie. into <c>ROOT</c>) - building and compiling should not depend on -<c>ROOT</c>. As a consequence of this the usage of <c>ROOT</c> in <c>src_*</c> -functions is not allowed. +installed (ie. into <c>ROOT</c>) <d/> building and compiling should not depend +on <c>ROOT</c>. As a consequence of this, the usage of <c>ROOT</c> in +<c>src_*</c> functions is not allowed. <c>pkgcheck</c> can now detect some +such cases via its <c>MisplacedVariable</c> check. +See <uri link="https://bugs.gentoo.org/775191">bug 775191</uri> for more +information. </p> <p> -See also <uri link="::ebuild-writing/variables#ROOT"/>. +See also <uri link="::ebuild-writing/variables/#ROOT"/>. </p> </body> </subsection> @@ -43,16 +61,20 @@ See also <uri link="::ebuild-writing/variables#ROOT"/>. <title>Referencing the full path to documentation files that could be compressed</title> <body> +<p> When printing out to the users where to find files like INSTALL, do not specify the full path since <c>PORTAGE_COMPRESS</c> comes into play. The file could be compressed with gzip, bzip2, or some other random compression tool. So, instead of doing this: +</p> <codesample lang="ebuild"> elog "They are listed in /usr/share/doc/${PF}/INSTALL.gz" </codesample> +<p> Do something like: +</p> <codesample lang="ebuild"> elog "They are listed in the INSTALL file in /usr/share/doc/${PF}" @@ -63,124 +85,166 @@ elog "They are listed in the INSTALL file in /usr/share/doc/${PF}" <subsection> <title>Build log not verbose</title> <body> +<p> When writing ebuilds, you should always check the build log, because the build system might ignore CC/CXX/LD/CFLAGS/LDFLAGS and such or add undesired flags by default. In order to analyze this and have complete information, in case someone reports a bug for your package, the <b>build log must always be verbose.</b> -<p> -There are several ways to fix non-verbose build logs depending on the build system: </p> <p> -For <c>cmake</c> based build systems it should be sufficient that the ebuild calls -cmake-utils_src_compile which picks up the cmake-utils.eclass variable 'CMAKE_VERBOSE=1' -by default. If you call emake directly for whatever reason, you can do 'emake VERBOSE=1' -(note that cmake-utils_src_compile takes arguments as well which are passed to make). +There are several ways to fix non-verbose build logs depending on the build system: </p> -<p> -For <c>autotools</c> based build systems you can pass '--disable-silent-rules' to econf, -or use EAPI 5 where that argument is passed automatically. 'emake V=1' should also work. -</p> +<ul> + <li> + For <c>cmake</c>-based build systems, it should be sufficient that the + ebuild calls cmake_src_compile which picks up the cmake.eclass variable + <c>CMAKE_VERBOSE=1</c> by default. If you call emake directly for whatever + reason, you can do <c>emake VERBOSE=1</c> (note that 'cmake_src_compile' + takes arguments as well which are passed to make). + </li> + <li> + For <c>autotools</c> based build systems, <c>econf</c> automatically + passes '--disable-silent-rules' to <c>./configure</c>. If necessary, + <c>emake V=1</c> should also work. Note that <c>V=1</c> is not a universal + parameter so may not always work. + </li> + <li> + For custom Makefiles, you often have to write a patch. Try to get + upstream to include an option like 'V=1' to enable full verbosity. + </li> + <li> + Note that when building Go manually outside of the eclass, you + will need GOFLAGS="-x". + </li> +</ul> -<p> -For custom Makefiles you often have to write a patch. Try to get upstream to include an -option like 'V=1' to enable full verbosity. -</p> <note>In case you encounter an affected package which uses a build system not -controllable by portage or eclasses you should file a bug (preferably with a patch) -and make it block the tracker bug #429308. Solutions above ebuild level are -preferred.</note> +controllable by Portage or eclasses, you should file a bug (preferably with +a patch) and make it block the tracker +<uri link="https://bugs.gentoo.org/429308">bug 429308</uri>. Solutions above +ebuild level are preferred.</note> + </body> </subsection> <subsection> <title>-Werror compiler flag not removed</title> <body> -"-Werror" is a flag which turns all warnings into errors and thus will abort compiling if any warning is encountered. +<p> +"-Werror" is a flag which turns all warnings into errors and thus will abort +compiling if any warning is encountered. +See <uri link="https://bugs.gentoo.org/260867">bug 260867</uri> for more +information and real-life examples/fixes in the Gentoo tree. +</p> -<p><b>Rationale</b><p /> -This flag is not recommended for releases and should always be disabled when encountered in build-logs, because there are numerous cases where this breaks without purpose, e.g.: +<p><b>Rationale</b></p> +<p> +This flag is not recommended for releases and should always be disabled when +encountered in build logs, because there are numerous cases where this breaks +without purpose, e.g.: +</p> <ul> <li> - new warnings on version bumps of GCC/GLIBC the developer was not aware of at the point of coding + new warnings on version bumps of GCC/glibc of which the developer was not + aware at the point of coding </li> <li> some autoconf checks will fail badly </li> <li> - libraries adding deprecated API warnings although that API is still working/supported + libraries adding deprecated API warnings although that API is still + working/supported </li> <li> - on less known architectures we may get different/more warnings than on common ones + on less known architectures we may get different/more warnings than on + common ones </li> <li> - random breakage depending on what distro/architecture/library version/kernel/userland the developer was testing "-Werror" on + random breakage depending on what distro/architecture/library + version/kernel/userland the developer was testing "-Werror" on </li> </ul> -Turning off "-Werror" we will still see the warnings, but there is no reason that they cause compile failure. Also note that portage already emits QA notices about gcc warnings that can cause runtime breakage. +<p> +By turning off "-Werror", we will still see the warnings, but there is no reason +that they cause compile failure. Note that Portage already emits QA +notices about GCC warnings that can cause runtime breakage. </p> -<p><b>How to fix</b><p /> +<p><b>How to fix</b></p> +<p> To fix the affected build system you should try the following methods: +</p> <ul> <li> - remove the compiler flag from the build system, <e>e.g. Makefile.am or configure.ac</e> or even provide a switch (for autotools based build systems that could be "--disable-werror", which is good for sending a patch upstream) + remove the compiler flag from the build system, <e>e.g. Makefile.am or + configure.ac</e> or even provide a switch (for autotools based build + systems that could be "--disable-werror", which is good for sending a patch + upstream) </li> <li> - use <e>append-flags -Wno-error</e> (needs flag-o-matic.eclass); for this to work the environment flags have to be respected and placed after build system flags; this method is not preferred as it will disable all "-Werror=specific-warning" flags as well, see next section + use <e>append-flags -Wno-error</e> (needs flag-o-matic.eclass); for this + to work the environment flags have to be respected and placed after build + system flags; this method is not preferred as it will disable all + "-Werror=specific-warning" flags as well, see next section </li> </ul> +<p> Always check that it's really gone in the build log. </p> -<p><b>Specific -Werror=... flags</b><p /> -GCC can turn any specific warning into an error. A specific -Werror flag would be "-Werror=implicit-function-declaration" for example and will only affect warnings about implicit function declarations. It's mostly safe to leave these untouched, cause they are pinned to this issue and should not cause random build time breakage. Also, we can expect that upstream did this on purpose to avoid known runtime errors and not just for testing their builds. However you should check the specified warnings yourself or ask other developers if unsure. +<p><b>Specific -Werror=... flags</b></p> +<p> +The compiler (e.g. GCC) can turn any specific warning into an error. A +specific -Werror flag would be "-Werror=implicit-function-declaration" for +example and will only affect warnings about implicit function declarations. It's +mostly safe to leave these untouched, because they are pinned to this issue and +should not cause random build-time breakage. Also, we can expect that upstream +did this on purpose to avoid known runtime errors and not just for testing their +builds. However, you should check the specified warnings yourself or ask other +developers if unsure. </p> -<p><b>Exceptions</b><p /> -Removing "-Werror" from configure.ac can cause breakage in very rare cases where the configure phase relies on the exit code. See <uri link="http://sourceforge.net/tracker/?func=detail&aid=2959749&group_id=204462&atid=989708">app-emulation/open-vm-tools bug</uri>. But even then we remove it from the resulting Makefile. +<p><b>Exceptions</b></p> +<p> +Removing "-Werror" from configure.ac can cause breakage in very rare +cases where the configure phase relies on the exit code. See +<uri link="https://sourceforge.net/p/open-vm-tools/tracker/81/"> +app-emulation/open-vm-tools bug</uri>. But even then we remove it from +the resulting Makefile. </p> </body> </subsection> <subsection> -<title>Missing/Invalid/Broken Header</title> +<title>Missing/invalid/broken header</title> <body> <p> -When you submit your ebuilds, the header should be <e>exactly</e> the same as -the one in <path>/usr/portage/skel.ebuild</path>. Most importantly, do not -modify it in any way and make sure that the <c>$Header: $</c> line is -intact. +When you submit your ebuilds, the header must be <e>exactly</e> the same as +the one in +<uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/skel.ebuild"> +skel.ebuild</uri>. </p> <p> -The first three lines <e>must</e> look like this: +The first two lines <e>must</e> look like this: </p> -<pre caption="Valid Header"> -# Copyright 1999-2004 Gentoo Foundation +<pre> +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ </pre> -<p> -Only if you are submitting a patched or version bumped ebuild, should you not -need to modify the <c>$Header: $</c> line. But the line must be present. -When we check the ebuild into CVS, it will modify that header with the -appropriate version and date information. So there is no need for you to -manually modify it. -</p> - </body> </subsection> <subsection> -<title>Redefined P, PV, PN, PF</title> +<title>Redefined P, PV, PN, PF variables</title> <body> <p> You should never redefine those variables. Always use MY_P, MY_PN, MY_PV, -P0, etc. See other ebuilds that do it in portage for more information. Most +P0, etc. See other ebuilds that do it in Portage for more information. Most ebuilds use bash "Parameter Expansion". Please read the man page for bash to understand how "Parameter Expansion" works. </p> @@ -203,9 +267,9 @@ number is not consistent with the tarball/source, then use MY_P. An example dev-python/pyopenal fetches a tarball called PyOpenAL, so we redefine it like: </p> -<pre caption="Example versioning redefinition"> +<pre> MY_P=${P/pyopenal/PyOpenAL} -SRC_URI="http://oomadness.tuxfamily.org/downloads/${MY_P}.tar.gz" +SRC_URI="http://download.gna.org/pyopenal/${MY_P}.tar.gz" S=${WORKDIR}/${MY_P} </pre> @@ -223,23 +287,23 @@ part. <ul> <li> - <e>Always include the CATEGORY.</e><br /> + <e>Always include the CATEGORY.</e> For example, use <c>>=x11-libs/gtk+-2</c> and not <c>>=gtk+-2</c>. </li> <li> - <e>Do not put an asterisk (*) for >= dependencies.</e><br /> + <e>Do not put an asterisk (*) for >= dependencies.</e> For example, it should be <c>>=x11-libs/gtk+-2</c> rather than <c>>=x11-libs/gtk+-2*</c>. </li> <li><e>GTK specific. Always use =x11-libs/gtk+-1.2* for GTK+1 apps.</e></li> <li> - <e>Never depend on a meta package.</e><br /> + <e>Never depend on a meta package.</e> So don't depend on gnome-base/gnome, always depend on the specific libraries like libgnome. </li> <li> - <e>One dependency per line.</e><br /> - Don't put multiple dependency on the same line. It makes it ugly to read + <e>One dependency per line.</e> + Don't put multiple dependency on the same line. It makes it ugly to read and hard to follow. </li> </ul> @@ -250,6 +314,11 @@ part. <title>DEPEND is incomplete</title> <body> +<note> +The tips in this section apply to all dependency classes, not just +<c>DEPEND</c>. +</note> + <p> This is another very common error. The ebuild submitter submits an ebuild that "just works" without checking if the dependencies are correct. Here are @@ -258,54 +327,54 @@ some tips on how to find the correct dependencies. <ul> <li> - <e>Look in configure.in or configure.ac</e><br /> + <e>Look in configure.in or configure.ac.</e> Look for checks for packages in here. Things to look out for are pkg-config checks or AM_* functions that check for a specific version. </li> <li> - <e>Look at included .spec files</e><br /> + <e>Look at included .spec files.</e> A good indication of dependencies is to look at the included .spec files for relevant deps. However, do not trust them to be the definitive complete - list of dependencies + list of dependencies. </li> <li> - <e>Look at the application/library website</e><br /> + <e>Look at the application/library website.</e> Check the application website for possible dependencies that they suggest are needed. </li> <li> - <e>Read the README and INSTALL for the package</e><br /> + <e>Read the README and INSTALL for the package.</e> They usually also contain useful information about building and installing packages. </li> <li> <e>Remember non-binary dependencies such as pkg-config, doc generation - programs, etc.</e><br /> + programs, etc.</e> Usually the build process requires some dependencies such as intltool, libtool, pkg-config, doxygen, scrollkeeper, gtk-doc, etc. Make sure those - are clearly stated. + are clearly stated, usually in <c>BDEPEND</c>. </li> </ul> </body> </subsection> <subsection> -<title>LICENSE Invalid</title> +<title>LICENSE invalid</title> <body> <p> Another common mistake users make when submitting ebuilds is supplying an -invalid license. For example, <c>GPL</c> is not a valid license. You need to -specify <c>GPL-1</c> or <c>GPL-2</c>. Same with <c>LGPL</c>. Make sure the -license you use in the <c>LICENSE</c> field is something that exists in -<path>/usr/portage/licenses</path>. As a tip, check the <path>COPYING</path> +invalid license. For example, <c>GPL</c> is not a valid license. You need to +specify <c>GPL-1</c> or <c>GPL-2</c>. Same with <c>LGPL</c>. Make sure the +license you use in the <c>LICENSE</c> field is something that exists in +the <c>licenses</c> directory. As a tip, check the <c>COPYING</c> in a source tarball for the license. If a package does not specify it uses <c>GPL-1</c> or <c>GPL-2</c>, it is very likely it uses <c>GPL-2</c>. </p> <p> If the license for the package you submit is unique and not in -<path>/usr/portage/licenses/</path>, then you must submit the new license in a +<c>licenses/</c>, then you must submit the new license in a separate file. </p> @@ -325,6 +394,20 @@ Make sure when you bump a version, the stable KEYWORDS are all marked as </body> </subsection> <subsection> +<title>Unused flags and eclass inherits</title> +<body> + +<p> +Sometimes obsolete USE flags remain in IUSE despite having no function, e.g. +a dependency may have become mandatory but the USE flag remains in IUSE and +*DEPEND. Similarly, eclasses often become redundant due to changes in the +ebuild, or new EAPIs, e.g. <c>eutils.eclass</c> should be obsolete in modern +EAPIs. Remember to prune these. +</p> + +</body> +</subsection> +<subsection> <title>SLOT missing</title> <body> @@ -333,7 +416,7 @@ Make sure you have the SLOT variable in the ebuild. If you don't plan to use it, don't remove it. Put in: </p> -<pre caption="Default SLOT variable"> +<pre> SLOT="0" </pre> @@ -344,21 +427,27 @@ SLOT="0" <body> <p> -Please check if the HOMEPAGE variable is right and leads users to the right -page if they want to find out more about the package. And make sure the -DESCRIPTION is not overly long. Good descriptions will describe the main -function of the package in a sentence. +Make sure the <c>DESCRIPTION</c> is not overly long. Good descriptions will +describe the main function of the package in a sentence. +</p> + +<p> +Please check if the <c>HOMEPAGE</c> variable is right and leads users to the +right page if they want to find out more about the package. If no homepage for +the package is available, set the <c>HOMEPAGE</c> variable to +<c>https://wiki.gentoo.org/wiki/No_homepage</c>. Please also strive to test +HTTPS support for the site used in <c>HOMEPAGE</c>. </p> </body> </subsection> <subsection> -<title>Wrongfully used spaces instead of TABS</title> +<title>Wrongfully used spaces instead of TABs</title> <body> <p> It is no fun reformatting lines of ebuilds because the submitter did not follow -the guidelines to use TABS rather than spaces. So <e>please</e> use tabs! +the guidelines to use TABs rather than spaces. So <e>please</e> use TABs! </p> </body> @@ -368,8 +457,8 @@ the guidelines to use TABS rather than spaces. So <e>please</e> use tabs! <body> <p> -I'm often guilty of this. Remember to run repoman over your ebuilds so it can -tell you if there is trailing whitespace at the end of lines or on empty lines. +Remember to run <c>pkgcheck</c> over your ebuilds so it can tell you if there +is trailing whitespace at the end of lines or on empty lines. </p> </body> @@ -379,8 +468,8 @@ tell you if there is trailing whitespace at the end of lines or on empty lines. <body> <p> -If <c>S=${WORKDIR}/${P}</c>, then you should not add it to your ebuild. This is -implied already, you should only add it if it is something other than +If <c>S=${WORKDIR}/${P}</c>, then you should not add it to your ebuild. This is +implied already, you should only add it if it is something other than <c>${WORKDIR}/${P}</c>. </p> @@ -392,7 +481,7 @@ implied already, you should only add it if it is something other than <p> If your package has documentation, make sure you install it using <c>dodoc</c> -or in <path>/usr/share/doc/${PF}</path>. Remember to check for errors when +or in <c>/usr/share/doc/${PF}</c>. Remember to check for errors when running <c>dodoc</c>/<c>doins</c>. </p> @@ -420,36 +509,69 @@ at least when the ebuild hits the stable branch. </body> </subsection> +<subsection> +<title>Not using latest EAPI</title> +<body> + +<p> +Often, user-submitted ebuilds do not use the latest EAPI and may even +be several versions behind. EAPIs bring new helper functions and improved +methods for completing common tasks. It's recommended that submitted ebuilds +use the latest EAPI possible (subject to eclass constraints) to improve +the ebuild's quality and ease review. +</p> +</body> +</subsection> + +<subsection> +<title>Calling pkg-config directly</title> +<body> + +<p> +You should not call <c>pkg-config</c> directly in ebuilds because this is +problematic for e.g. cross-compiling. The correct helper respects +<c>${PKG_CONFIG}</c>. Instead, use <c>tc-getPKG_CONFIG</c> from +<c>toolchain-funcs.eclass</c>, e.g. +</p> + +<codesample lang="ebuild"> +sed -i -e "s:-lncurses:$($(tc-getPKG_CONFIG) --libs ncurses):" || die +</codesample> + +<p> +Don't then forget to add <c>virtual/pkgconfig</c> to BDEPEND! +</p> + </body> +</subsection> </section> - <section> -<title>Common Ebuild Submission Mistakes</title> +<title>Common ebuild submission mistakes</title> <subsection> <title>Introduction</title> <body> <p> -Please submit ebuilds properly by following the <uri -link="::ebuild-writing/ebuild-maintenance#adding-a-new-ebuild">Adding new Ebuild</uri> tutorial. +Please submit ebuilds properly by following the +<uri link="::ebuild-maintenance/new-ebuild/"/> tutorial. </p> </body> </subsection> <subsection> -<title>Tarball'ing an ebuild</title> +<title>Tarballing an ebuild</title> <body> <p> -Please please please do not attach ebuilds as tarballs. Attach patches -separately as well so we can easily examine them. +Please do not attach ebuilds or patches as tarballs. It avoids extra +operations when reviewing. </p> </body> </subsection> <subsection> -<title>Inlining Ebuilds</title> +<title>Inlining ebuilds</title> <body> <p> @@ -470,7 +592,7 @@ of the application, if any exists. </body> </subsection> <subsection> -<title>Package updates without changing the ChangeLog</title> +<title>Package updates without explaining what has changed</title> <body> <p> @@ -484,8 +606,8 @@ It is wise to submit a diff for a package update rather than the whole ebuild. The best way to generate it would be: </p> -<pre caption="Creating a diff"> -$ <i>diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.diff</i> +<pre> +$ diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-package-0.2.0.patch </pre> </body> @@ -495,7 +617,7 @@ $ <i>diff -u some-package-0.1.0.ebuild some-package-0.2.0.ebuild > ~/some-pac <body> <p> -If you are submitting a new version for a package in portage, make sure the +If you are submitting a new version for a package in Portage, make sure the existing ebuild works and make sure changes are incorporated in the new ebuild (such as added documentation.) If there are no required changes to the ebuild from the previous version, then don't attach the ebuild. Just say so in the bug diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml index 3faab22..26795cf 100644 --- a/ebuild-writing/eapi/text.xml +++ b/ebuild-writing/eapi/text.xml @@ -1,20 +1,21 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/eapi/"> <chapter> -<title>EAPI Usage and Description</title> - +<title>EAPI usage and description</title> <body> + <p> -The Package Manager Specification (PMS) is a standardization -effort to ensure that the ebuild file format, the ebuild repository format -(of which the portage tree is Gentoo's main incarnation) as well as behavior -of the package managers interacting with these ebuilds is properly written -down and agreed upon. +The <uri link="https://wiki.gentoo.org/wiki/Project:PMS">Package Manager +Specification (PMS)</uri> is a standardization effort to ensure that the +ebuild file format, the ebuild repository format (of which the Gentoo +repository is Gentoo's main incarnation) as well as behaviour of the package +managers interacting with these ebuilds is properly written down and agreed +upon. </p> <p> EAPI is a version defined in ebuilds and other package manager related files -which inform the package manager about the file syntax and content. It is, +which informs the package manager about the file syntax and content. It is, in effect, the version of the package manager specification (PMS) that the file adheres to. </p> @@ -23,840 +24,1397 @@ file adheres to. This section provides usage and descriptions of the different EAPIs. </p> +</body> + <section> <title>Usage of EAPIs</title> <body> + <important> An overview about the important features of each EAPI is provided in the appendix of the Package Manager Specification. The two-page leaflet can be printed out, consulted for reference and is available as <c>app-doc/pms</c> in the main tree. </important> + <p> -If EAPI is undefined in an ebuild, then EAPI=0 is selected. You should -set the EAPI variable, by specifying it at the top of the ebuild: +You must set the EAPI variable by specifying it at the top of the ebuild: </p> -<note> -Most developers prefer to set the EAPI version without quotes. However, the PMS allows single and double quotes as well. -</note> - <codesample lang="ebuild"> -# Copyright 1999-2013 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -EAPI=5 -inherit eutils +EAPI=7 </codesample> +<note> +Most developers prefer to set the EAPI version without quotes. However, the PMS +allows single and double quotes as well. +</note> + <important> EAPI must only be defined in ebuild files, not eclasses. (eclasses may have EAPI-conditional code) </important> <p> -When writing new ebuilds developers can choose whathever EAPI they think +When writing new ebuilds developers can choose whatever EAPI they think is the best. Using the features of the latest EAPI is encouraged. </p> - </body> -</section> -<section> -<title>EAPI=1</title> +<subsection> +<title>Upgrade path</title> <body> -<ul> - <li> - <p><b>Default src_compile Phase Function</b></p> - <p> - Support for the <c>ECONF_SOURCE</c> variable, which is also supported by - <c>econf</c>, has been added to the default <c>src_compile</c> implementation. - </p> - <codesample lang="ebuild"> -src_compile() { - if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then - emake || die "emake failed" - fi -} - </codesample> - </li> - <li> - <p><b>SLOT dependencies</b></p> - <p> - Any valid atom can be constrained to match a specific SLOT. This - is accomplished by appending a colon to the atom, followed by a - SLOT value. - </p> - <p> - <b>SLOT dependency examples:</b> - <ul> - <li><c>x11-libs/qt:3</c></li> - <li><c>~x11-libs/qt-3.3.8:3</c></li> - <li><c>>=x11-libs/qt-3.3.8:3</c></li> - <li><c>=x11-libs/qt-3.3*:3</c></li> - </ul> - </p> - </li> - <li> - <p><b>IUSE defaults</b></p> - <p> - Add + or - before the name of the use flag in IUSE to turn it on or off by - default. - </p> - - <important> - The default USE-ordering is <c>USE_ORDER="env:pkg:conf:defaults:pkginternal:env.d"</c> - (see man make.conf) - </important> - <important> - Disabling default IUSE is pretty much useless as it does not - override the profile and user config (make.conf and package.use) - </important> - - <codesample lang="ebuild"> -# Copyright 1999-2010 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -EAPI=1 +<p> +Gentoo policy is to support upgrades for installations at least a year old +with no/little intervention and up to two years old with minor intervention. +To achieve this, developers must avoid using the latest EAPI in ebuilds within +the <c>@system</c> set +(see <uri link="::general-concepts/dependencies/#Implicit system dependency"/>) +or its dependencies. +</p> -IUSE="foo +bar" +<p> +The Base System project has +<uri link="https://wiki.gentoo.org/wiki/Project:Base#Rules_and_limitations">rules</uri> +governing their use of newer EAPIs, as does the +<uri link="https://projects.gentoo.org/python/guide/package-maintenance.html#porting-packages-to-a-new-eapi">Python project</uri>. +</p> - </codesample> - </li> -</ul> +<p> +It is also convention that blockers within ebuilds are retained for at least +2 years after the last ebuild matching the block is removed from the tree to +avoid file collisions for users upgrading older systems. <c>pkgcheck</c> has +a warning for this called <c>OutdatedBlocker</c> (or even +<c>NonexistentBlocker</c> for when the match is from pre-git times if using +a non-grafted repository). +</p> </body> +</subsection> </section> - <section> -<title>EAPI=2</title> +<title>EAPIs 0 to 4</title> <body> +<p> +EAPIs 0 to 4 are obsolete and must no longer be used. Refer to the Package +Manager Specification for details about them. +</p> + +</body> +</section> + +<section> +<title>EAPI 5</title> + <subsection> -<title>Helpers</title> +<title>EAPI 5 metadata</title> <body> -<ul> - <li> - <p><b>doman Language Support</b></p> - <p> - <c>doman</c> automatically detects language codes and puts it in the - appropriate directory. - <codesample lang="ebuild"> -doman foo.1 -# will go into /usr/share/man/man1/foo.1 -doman foo.lang.1 -# will go into /usr/share/man/lang/man1/foo.1 with EAPI=2 - </codesample> - </p> - </li> -</ul> + +<dl> + <dt>REQUIRED_USE supports new at-most-one-of operator</dt> + <dd> + The new <b>at-most-one-of</b> operator consists of the string <c>??</c>, + and is satisfied if zero or one (but no more) of its child elements is + matched. + </dd> + <dt>SLOT supports optional "sub-slot" part</dt> + <dd> + The <c>SLOT</c> variable may contain an optional <b>sub-slot</b> part that + follows the regular slot and is delimited by a <c>/</c> character. + The sub-slot must be a valid slot name. The sub-slot is used to represent + cases in which an upgrade to a new version of a package with a different + sub-slot may require dependent packages to be rebuilt. When the sub-slot + part is omitted from the SLOT definition, the package is considered to have + an implicit sub-slot which is equal to the regular slot. + </dd> + <dt>Slot operators and sub-slots in dependencies</dt> + <dd> + <p> + A slot dependency may contain an optional sub-slot part that follows the + regular slot and is delimited by a <c>/</c> character. This can be useful + for packages installing pre-built binaries that require a library with a + specific soname version which corresponds to the sub-slot. For example: + </p> +<codesample lang="ebuild"> +RDEPEND="dev-libs/foo:0/3" +</codesample> + <p> + Package dependency specifications can use <b>slot operators</b> to clarify + what should happen if the slot and/or sub-slot of a runtime dependency + changes: + </p> + <ul> + <li> + <c>:*</c> Indicates that any slot value is acceptable. In addition, + for runtime dependencies, indicates that the package specifying the + dependency will not break if the package matching the dependency is + replaced by a different matching package with a different slot and/or + sub-slot. + </li> + <li> + <c>:=</c> Indicates that any slot value is acceptable. In addition, + for runtime dependencies, indicates that the package specifying the + dependency will break unless there is available a package matching + the dependency and whose slot and sub-slot are equal to the slot and + sub-slot of the best installed version that had matched this dependency + at the time when the package specifying this dependency had been + installed. + </li> + <li> + <p> + <c>:slot=</c> Indicates that only a specific slot value is acceptable, + and otherwise behaves identically to the <c>:=</c> operator. + </p> + <note> + use <c>:slot/subslot</c> without a <c>=</c> to depend on a specific + slot and sub-slot pair; it's a syntax error to use <c>:slot/subslot=</c> + in an ebuild. + </note> + </li> + </ul> + <p> + The <c>:slot</c> dependency syntax continues to behave like in EAPI=4 or + earlier, i.e. it indicates that only the specific slot value is acceptable, + but the package will not break when the version matching the runtime + dependency is replaced by a version with a different sub-slot. + </p> + <p> + For example: + </p> +<codesample lang="ebuild"> +RDEPEND="dev-libs/foo:2= + >=dev-libs/bar-0.9:= + media-gfx/baz:* + x11-misc/wombat:0" +</codesample> + <p> + means that the package should be rebuilt when <c>foo:2</c> or + <c>>=bar-0.9</c> are upgraded to versions with different subslots, + but that changes in subslots of <c>baz</c> or <c>wombat:0</c> should be + ignored. + </p> + </dd> +</dl> + </body> </subsection> <subsection> -<title>Metadata</title> +<title>EAPI 5 profiles</title> <body> -<ul> - <li> - <p><b>Blocker Atoms</b></p> - <p> - <ul> - <li> - <p><b>New Meaning for Old Syntax</b></p> - <p> - Blocker atoms which use the previously existing !atom syntax now - have a slightly different meaning. These blocker atoms indicate - that conflicting packages may be temporarily installed - simultaneously. When temporary simultaneous installation of - conflicting packages occurs, the installation of a newer package - may overwrite any colliding files that belong to an older package - which is explicitly blocked. When such file collisions occur, the - colliding files cease to belong to the older package, and they - remain installed after the older package is eventually - uninstalled. The older package is uninstalled only after any newer - blocking packages have been merged on top of it. - </p> - </li> - <li> - <p><b>New !!atom Syntax</b></p> - <p> - A new !!atom syntax is now supported, for use in special cases for - which temporary simultaneous installation of conflicting packages - should not be allowed. If a given package happens to be blocked by - a mixture of atoms consisting of both the !atom and !!atom - syntaxes, the !!atom syntax takes precedence over the !atom - syntax. - </p> - </li> - </ul> - </p> - </li> - <li> - <p><b>USE Dependencies</b></p> - <p> - It is possible to depend on USE-flags of packages. - </p> - <p>Examples: - <ul> - <li><c>foo[bar]</c> means that package foo must have USE-flag bar - enabled</li> - <li><c>foo[bar,baz]</c> means that the package foo must have both - the bar and baz USE-flags enabled - </li> - <li><c>foo[-bar,baz]</c> means that the package foo must have the - bar USE-flag disabled and baz USE-flag enabled</li> - <li><c>foo[bar?]</c> means <c>bar? ( foo[bar] ) !bar? ( foo )</c></li> - <li><c>foo[!bar?]</c> means <c>bar? ( foo ) !bar? ( foo[-bar] )</c></li> - <li><c>foo[bar=]</c> means <c>bar? ( foo[bar] ) !bar? ( foo[-bar] )</c></li> - <li><c>foo[!bar=]</c> means <c>bar? ( foo[-bar] ) !bar? ( foo[bar] )</c></li> - </ul> - </p> - </li> - <li> - <p><b>Customization of Output File Names in SRC_URI</b></p> - <p> - A new syntax is supported which allows customization of the output - file name for a given URI. In order to customize the output file - name, a given URI should be followed by a "<c>-></c>" operator which, in - turn, should be followed by the desired output file name. As - usual, all tokens, including the operator and output file name, - should be separated by whitespace. - </p> - <p>Example:</p> - <codesample lang="ebuild"> -SRC_URI="http://dl.google.com/earth/client/GE4/release_4_3/GoogleEarthLinux.bin - -> GoogleEarthLinux-${PV}.bin" - </codesample> - </li> -</ul> + +<dl> + <dt>Profile stable USE forcing and masking</dt> + <dd> + In profile directories with an EAPI supporting stable masking, new USE + configuration files are supported: <c>use.stable.mask</c>, + <c>use.stable.force</c>, <c>package.use.stable.mask</c> and + <c>package.use.stable.force</c>. These files behave similarly to previously + supported USE configuration files, except that they only influence packages + that are merged due to a stable keyword. + </dd> +</dl> </body> </subsection> <subsection> -<title>Phases</title> +<title>EAPI 5 helpers</title> <body> -<ul> - <li> - <p><b>New <c>src_prepare</c> Phase Function</b></p> - <p> - A new src_prepare function is called after the <c>src_unpack</c> - function, with cwd initially set to <c>$S</c>. - </p> - </li> - <li> - <p><b>New <c>src_configure</c> Phase Function</b></p> - <p> - The configure portion of the <c>src_compile</c> function has been split - into a separate function which is named <c>src_configure</c>. The - <c>src_configure</c> function is called in-between the <c>src_prepare</c> and - <c>src_compile</c> functions. - </p> - <p>The default <c>src_configure</c> and <c>src_compile</c> - functions in EAPI=2: - <codesample lang="ebuild"> -src_configure() { - if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi -} -src_compile() { - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then - emake || die "emake failed" - fi -} - </codesample> - </p> - </li> - <li> - <p><b>Execution Order of Phase Functions</b></p> - <p> - <ul> - <li><c>pkg_setup</c></li> - <li><c>src_unpack</c></li> - <li><c>src_prepare</c></li> - <li><c>src_configure</c></li> - <li><c>src_compile</c></li> - <li><c>src_test</c></li> - <li><c>src_install</c></li> - <li><c>pkg_preinst</c></li> - <li><c>pkg_postinst</c></li> - <li><c>pkg_prerm</c></li> - <li><c>pkg_postrm</c></li> - </ul> - </p> - </li> - <li> - <p><b>Default Phase Functions</b></p> - <p> - The default <c>pkg_nofetch</c> and <c>src_*</c> phase functions are now - accessible via a function having a name that begins with <c>default_</c> - and ends with the respective phase function name. For example, a - call to a function with the name <c>default_src_compile</c> is equivalent - to a call to the default <c>src_compile</c> implementation. - </p> - <p>The default phase functions are: - <ul> - <li><c>default_pkg_nofetch</c></li> - <li><c>default_src_unpack</c></li> - <li><c>default_src_prepare</c></li> - <li><c>default_src_configure</c></li> - <li><c>default_src_compile</c></li> - <li><c>default_src_test</c></li> - </ul> - </p> - </li> - <li> - <p><b>Default Phase Function Alias</b></p> - <p> - A function named "<c>default</c>" is redefined for each phase so that it - will call the <c>default_*</c> function corresponding to the current - phase. For example, a call to the function named "<c>default</c>" during - the <c>src_compile</c> phase is equivalent to a call to the function - named <c>default_src_compile</c>. - </p> - </li> -</ul> +<dl> + <dt>econf adds --disable-silent-rules</dt> + <dd> + This option will automatically be passed if <c>--disable-silent-rules</c> + occurs in the output of <c>configure --help</c>. + </dd> + <dt>new* commands can read from standard input</dt> + <dd> + Standard input is read when the first parameter is <c>-</c> (a hyphen). + </dd> + <dt>New option --host-root for {has,best}_version</dt> + <dd> + This option <c>--host-root</c> will cause the query to apply to the host + root instead of ROOT. + </dd> + <dt>New doheader helper function</dt> + <dd> + Installs the given header files into <c>/usr/include/</c>. If option + <c>-r</c> is specified, descends recursively into any directories given. + </dd> + <dt>New usex helper function</dt> + <dd> + <!-- We probably need an example here --> +<pre> +USAGE: usex <USE flag> [true output] [false output] [true suffix] [false suffix] +DESCRIPTION: +If USE flag is set, echo [true output][true suffix] (defaults to "yes"), + otherwise echo [false output][false suffix] (defaults to "no"). +</pre> + </dd> +</dl> + </body> </subsection> +<subsection> +<title>EAPI 5 phases</title> +<body> + +<dl> + <dt>src_test supports parallel tests</dt> + <dd> + Unlike older EAPIs, the default <c>src_test</c> implementation will not + pass the -j1 option to emake. + </dd> +</dl> + </body> -</section> -<section> -<title>EAPI=3</title> +</subsection> + +<subsection> +<title>EAPI 5 variables</title> <body> -<ul> - <li> - <p><b>Gentoo Prefix support</b></p> - <p> - Support for the <c>EPREFIX</c>, <c>EROOT</c>, and <c>ED</c> - variables. If an ebuild uses one of these, it must be EAPI3 aware. - See <uri link="http://www.gentoo.org/proj/en/gentoo-alt/prefix/techdocs.xml#doc_chap2">Gentoo Prefix Techdocs</uri> for more information. - </p> - </li> - <li> - <p><b>unpack supports .xz and .tar.xz</b></p> - <p> - The <c>unpack</c> command supports xz-archives and xz-compressed tar - files. - </p> - </li> -</ul> +<dl> + <dt>EBUILD_PHASE_FUNC</dt> + <dd> + During execution of an ebuild phase function (such as <c>pkg_setup</c> or + <c>src_unpack</c>), the <c>EBUILD_PHASE_FUNC</c> variable will contain the + name of the phase function that is currently executing. + </dd> +</dl> </body> +</subsection> </section> <section> -<title>EAPI=4</title> -<body> +<title>EAPI 6</title> <subsection> -<title>Helpers</title> +<title>EAPI 6 Bash version</title> <body> -<ul> - <li> - <p><b>utilities die on their own, unless the nonfatal command is used</b></p> - <p> - <!-- TODO link auf fuunction-reference --> - Ebuild functions all die on their own in EAPI=4. In case that this - non-zero exit status is expected, you may call <c>nonfatal function - [arg,...]</c>. - </p> - <p>Example:</p> - <codesample lang="ebuild"> -EAPI=1 -... -src_install() { - emake DESTDIR="${D}" install || die "make install failed" - dodoc ChangeLog README -} - </codesample> - <codesample lang="ebuild"> -EAPI=4 -... -src_install() { - emake DESTDIR="${D}" install - nonfatal dodoc ChangeLog README -} - </codesample> - </li> - <li> - <p><b>recursive dodoc</b></p> - <p> - <c>dodoc</c> supports <c>-r</c> as the first argument, which leads - <c>dodoc</c> to install the specified documentation directory - recursively into the docdir. - </p> - <p>Example:</p> - <codesample lang="ebuild"> -src_install() { - default - dodoc ChangeLog - dodoc -r doc/ -} - </codesample> - </li> - <li> - <p><b>doins symlink supports</b></p> - <p> - Within EAPI=4, <c>doins</c> supports installing symlinks as symlinks - when installing recursively. For older EAPIs, the symlink behaviour - is undefined. - </p> - </li> - <li> - <p><b>dosed and dohard are banned</b></p> - <p> - The <c>dosed</c> and <c>dohard</c> commands are banned in this EAPI. - </p> - </li> - <li> - <p><b>econf adds --disable-dependency-tracking</b></p> - <p> - Within EAPI=4, <c>econf</c> adds - <c>--disable-dependency-tracking</c> to the default configure - options. - </p> - </li> - <li> - <p><b>controllable compression via docompress</b></p> - <p> - To compress files in the destination-folder <c>${D}</c>, the - <c>docompress</c> command may be used in <c>src_install</c>. - To control which items should be compressed and which shouldn't - be compressed, you may include or exclude directories or plain - files. The default inclusion list contains: - <ul> - <li><c>/usr/share/doc</c></li> - <li><c>/usr/share/info</c></li> - <li><c>/usr/share/man</c></li> - </ul> - The default exclusion list contains: - <ul> - <li><c>/usr/share/doc/${PF}/html</c></li> - </ul> - When a directory is in- or excluded, all files and directories in - the given directories shall be added to the corresponding list. - If a file is in- or excluded, the file shall be added to the - corresponding list (exclusion is stronger than inclusion <d/> - if a file is in both lists, the inclusion will be ignored). - </p> - <p> - If the first argument of <c>docompress</c> is <c>-x</c>, the items - specified will be added to the exclusion list, otherwise they will - be added to the inclusion list. - </p> - <note> - When <c>docompress</c> is called, it is <e>not</e> required that - the paths specified as its arguments are pointing to existing files - or directories. However, if a file still doesn't exist when - <c>src_install</c> has completed, it will be ignored with a - warning. - </note> - </li> -</ul> + +<dl> + <dt>Bash version</dt> + <dd> + Ebuilds can use features of Bash version 4.2 (was 3.2 before). + </dd> +</dl> + </body> </subsection> <subsection> -<title>Metadata</title> +<title>EAPI 6 ebuild environment</title> <body> -<ul> - <li> - <p><b>use dependencies default</b></p> - <p> - In addition to the use-deps specified in EAPI=2, a <c>(+)</c> or - <c>(-)</c> may be added to the use-dep to define a default-value in - case the use-flag does not exist in the given package. The - <c>(+)</c> means that this use-flag is assumed to be enabled, - <c>(-)</c> the opposite. - <p>Example:</p> - <codesample lang="ebuild"> -DEPEND=" - >=dev-libs/boost-1.32[boost(+)] - sys-devel/gcc[openmp(-)]" - </codesample> - </p> - </li> -</ul> + +<dl> + <dt>Locale settings</dt> + <dd> + Behaviour of case modification and collation order (<c>LC_CTYPE</c> and + <c>LC_COLLATE</c>) are guaranteed to be the same as in the C locale, as far + as characters in the ASCII range are concerned. + </dd> + <dt><c>failglob</c> enabled</dt> + <dd> + For <c>EAPI=6</c>, the <c>failglob</c> option of bash is set in the global + scope of ebuilds. If set, failed pattern matches during filename expansion + result in an error when the ebuild is being sourced. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Phases</title> +<title>EAPI 6 phases</title> <body> -<ul> - <li> - <p><b>new pkg_pretend phase</b></p> - <p> - The new <c>pkg_pretend</c> phase can be used to do sanity checks - before the main phase function sequence is run (meaning this phase is - executed after the package manager has calculated the dependencies - and before installing them). - This phase typically checks for a kernel configuration and may - <c>eerror</c> and <c>die</c> when needed. - <important> - There is no guarantee that the ebuild's dependencies are installed - when this phase is called. - </important> - <important> - As <c>pkg_pretend</c> is not called in the main phase function - sequence, environment saving is not guaranteed. - </important> - </p> - <p>Example:</p> - <codesample lang="ebuild"> -# Copyright 1999-2009 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 -# $Header: $ - -EAPI=4 -inherit linux-info -... - -CONFIG_CHECK="FUSE_FS" -ERROR_FUSE_FS="this is an unrealistic testcase..." - -pkg_pretend() { - if use kernel_linux ; then - if [[ -e "${ROOT}"/usr/src/linux/.config ]] ; then - if kernel_is lt 2 6 30 ; then - check_extra_config - fi - fi - fi + +<dl> + <dt>Update default implementation of <c>src_prepare</c></dt> + <dd> + <p> + This phase is no longer a no-op, it supports applying patches via the + <c>PATCHES</c> variable and applying user patches via <c>eapply_user</c>. + The default <c>src_prepare</c> looks like this: + </p> +<codesample lang="ebuild"> +src_prepare() { + if [[ $(declare -p PATCHES 2>/dev/null) == "declare -a"* ]]; then + [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}" + else + [[ -n ${PATCHES} ]] && eapply ${PATCHES} + fi + eapply_user } - </codesample> - </li> - <li> - <p><b>default src_install is no longer a no-op</b></p> - <p> - The default <c>src_install</c> function in EAPI=4: - </p> - <codesample lang="ebuild"> +</codesample> + </dd> + <dt>New <c>src_install</c> Phase Function</dt> + <dd> + <p> + This phase uses the new <c>einstalldocs</c> function for installation of + documentation. The default <c>src_install</c> looks like this: + </p> +<codesample lang="ebuild"> src_install() { - if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then - emake DESTDIR="${D}" install - fi - - if ! declare -p DOCS >/dev/null 2>&1 ; then - local d - for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \ - FAQ CREDITS CHANGELOG ; do - [[ -s "${d}" ]] && dodoc "${d}" - done - elif declare -p DOCS | grep -q "^declare -a " ; then - dodoc "${DOCS[@]}" - else - dodoc ${DOCS} - fi + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then + emake DESTDIR="${D}" install + fi + einstalldocs } - </codesample> - </li> - <li> - <p><b>pkg_info for non-installed packages</b></p> - <p> - The <c>pkg_info</c> function may also be called by the - package manager for non-installed packages. - Ebuild writers should note that dependencies may not be - available. - </p> - </li> -</ul> +</codesample> + </dd> +</dl> + </body> </subsection> <subsection> -<title>Variables</title> +<title>EAPI 6 helpers</title> <body> -<ul> - <li> - <p><b>REQUIRED_USE</b></p> - <p> - The <c>REQUIRED_USE</c> variable contains a list of assertions that - must be met by the configuration of USE flags to be valid for this - ebuild. In order to be matched, a USE flag in a terminal element - must be enabled (or disabled if it has an exclamation mark prefix). - </p> - <p> - Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> - style syntax. For example, to state that some combination is - forbidden, i.e. "if <c>foo</c> is set, <c>bar</c> must be unset": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="foo? ( !bar )" - </codesample> - <p> - To state "if <c>foo</c> is set, then at least one of <c>bar</c>, - <c>baz</c>, and <c>quux</c> must be activated": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="foo? ( || ( bar baz quux ) )" - </codesample> - <p> - To state "exactly one of <c>foo</c>, <c>bar</c>, or <c>baz</c> must - be set, but not several": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="^^ ( foo bar baz )" - </codesample> - <p> - Note that the last relationship is that of an Exclusive OR (XOR). - While an XOR could be formed from usual <c>DEPEND</c> syntax, a - specific <c>^^</c> operator has been added for this case. - </p> - <p> - Finally, to state "at least one of <c>foo</c>, <c>bar</c>, or - <c>baz</c> must be set": - </p> - <codesample lang="ebuild"> -REQUIRED_USE="|| ( foo bar baz )" - </codesample> - - <important> - See section - <uri link="::general-concepts/use-flags/#conflicting-use-flags" /> - for when (and when not) to use <c>REQUIRED_USE</c>. - </important> - </li> - <li> - <p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p> - <p> - The <c>REPLACING_VERSIONS</c> variable contains a - whitespace-separated list of all versions (<c>PVR</c>) of this - package that are being replaced (uninstalled or overwritten) as a - result of this install. It is a list, not a single optional value, - to handle pathological cases such as installing <c>foo-2:2</c> to - replace <c>foo-2:1</c> and <c>foo-3:2</c>. - </p> - <p> - <c>REPLACING_VERSIONS</c> is valid in <c>pkg_preinst</c> and - <c>pkg_postinst</c>. In addition, it may be available in - <c>pkg_pretend</c> and <c>pkg_setup</c>, although you should take - care to handle binary package creation and installation correctly - when using it in these phases. - </p> - <p> - The <c>REPLACED_BY_VERSION</c> variable contains the single version - (<c>PVR</c>) of this package that is replacing us, if we are being - uninstalled as part of an install, or an empty string otherwise. - It is valid in <c>pkg_prerm</c> and <c>pkg_postrm</c>. - </p> - </li> - <li> - <p><b>MERGE_TYPE</b></p> - <p> - The <c>MERGE_TYPE</c> variable contains the type of package that - is being merged. Possible values are: - <dl> - <dt><c>source</c></dt> - <dd><p> - if building and installing a package from source, - </p></dd> - <dt><c>binary</c></dt> - <dd><p> - if installing a binary package, - </p></dd> - <dt><c>buildonly</c></dt> - <dd><p> - if building a binary package without installing it. - </p></dd> - </dl> - </p> - </li> - <li> - <p><b>DOCS</b></p> - <p> - The <c>DOCS</c> variable is an array or whitespace-separated list - of documentation files for the default <c>src_install</c> function - to install using <c>dodoc</c>. If undefined, a reasonable default - list is used. See the default <c>src_install</c> function above. - </p> - </li> - <li> - <p><b>AA and KV variables are gone</b></p> - <p> - The <c>AA</c> and <c>KV</c> variables are no longer set in EAPI=4. - </p> - </li> - <li> - <p><b>no more RDEPEND="${DEPEND}"</b></p> - <p> - When <c>RDEPEND</c> is unset, there will no longer be an automatic - assignment of <c>RDEPEND="${DEPEND}"</c>. - </p> - </li> -</ul> -</body> -</subsection> + +<dl> + <dt><c>einstall</c> banned</dt> + <dd> + The <c>einstall</c> helper has been banned with <c>EAPI=6</c>. + </dd> + <dt><c>dohtml</c> deprecated</dt> + <dd> + The <c>dohtml</c> helper has been deprecated with <c>EAPI=6</c>. + </dd> + <dt><c>nonfatal die</c></dt> + <dd> + When <c>die</c> or <c>assert</c> are called under the <c>nonfatal</c> + command and with the <c>-n</c> option, they will not abort the build + process but return with an error. + </dd> + <dt><c>eapply</c> support</dt> + <dd> + The <c>eapply</c> command is a simplified substitute for <c>epatch</c> + (from <c>eutils.eclass</c>), implemented in the package manager. + The patches from its file or directory arguments are applied using patch + <c>-p1</c>, but it accepts <c>patch(1)</c> options from GNU patch to + override default behavior. + </dd> + <dt><c>eapply_user</c> support</dt> + <dd> + <p> + The <c>eapply_user</c> command permits the package manager to apply + user-provided patches. It must be called from every <c>src_prepare</c> + function. + </p> + <note> + <c>eapply_user</c> doesn't need to be called explicitly when default + <c>src_prepare</c> is called. + </note> + </dd> + <dt><c>econf</c> adds <c>--docdir</c> and <c>--htmldir</c></dt> + <dd> + Options <c>--docdir</c> and <c>--htmldir</c> are passed to + <c>configure</c>, in addition to the existing options. + </dd> + <dt><c>in_iuse</c> support</dt> + <dd> + The <c>in_iuse</c> function returns <c>true</c> if the given parameter is + available in the ebuilds <c>USE</c>. + </dd> + <dt><c>unpack</c> changes</dt> + <dd> + <ul> + <li> + <c>unpack</c> supports relative paths without leading <c>./</c> + (<c>unpack foo/bar.tar.gz</c> is valid as relative path). + </li> + <li><c>unpack</c> supports <c>.txz</c> (xz compressed tarball).</li> + <li><c>unpack</c> matches filename extensions case-insensitively.</li> + </ul> + </dd> + <dt><c>einstalldocs</c> support</dt> + <dd> + The <c>einstalldocs</c> function will install the files specified by the + <c>DOCS</c> variable (or a default set of files if <c>DOCS</c> is unset) + and by the <c>HTML_DOCS</c> variable. + </dd> + <dt><c>get_libdir</c> support</dt> + <dd> + The <c>get_libdir</c> command outputs the <c>lib*</c> directory basename + suitable for the current ABI. + </dd> +</dl> </body> +</subsection> </section> <section> -<title>EAPI=5</title> +<title>EAPI 7</title> + +<subsection> +<title>EAPI 7 terminology</title> <body> +<p> +Documents may use the following terms to better describe dependency and +installation targets. +</p> + +<dl> + <dt><c>CHOST</c></dt> + <dd> + The system that will be running the installed package. + </dd> + <dt><c>CBUILD</c></dt> + <dd> + The system used to build packages. When not cross-compiling, + CBUILD == CHOST. + </dd> + <dt><c>CTARGET</c></dt> + <dd> + Used in certain cross-compilations, often empty value. + </dd> +</dl> + +</body> +</subsection> + <subsection> -<title>Metadata</title> +<title>EAPI 7 variables</title> <body> -<ul> - <li> - <p><b>REQUIRED_USE supports new at-most-one-of operator</b></p> - <p> - The new <b>at-most-one-of</b> operator consists of the string <c>'??'</c>, and is satisfied if zero or one (but no more) of its child elements is matched. - </p> - </li> - <li> - <p><b>SLOT supports optional "sub-slot" part</b></p> - <p> - The <c>SLOT</c> variable may contain an optional <b>sub-slot</b> part that follows the regular slot and is delimited by a <c>/</c> character. The sub-slot must be a valid slot name. The sub-slot is used to represent cases in which an upgrade to a new version of a package with a different sub-slot may require dependent packages to be rebuilt. When the sub-slot part is omitted from the SLOT definition, the package is considered to have an implicit sub-slot which is equal to the regular slot. - </p> - </li> - <li> - <p><b>Slot operators and sub-slots in dependencies</b></p> - <p> - A slot dependency may contain an optional sub-slot part that follows the regular slot and is delimited by a <c>/</c> character. This can be useful for packages installing pre-built binaries that require a library with a specific soname version which corresponds to the sub-slot. For example: - </p> - <codesample lang="ebuild"> -RDEPEND="dev-libs/foo:0/3" - </codesample> - <p> - Dependency atoms can use <b>slot operators</b> to clarify what should happen if the slot and/or sub-slot of a runtime dependency changes: - </p> - <ul> - <li> - <c>:*</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will not break if the package matching the dependency is replaced by a different matching package with a different slot and/or sub-slot. - </li> - <li> - <c>:=</c> Indicates that any slot value is acceptable. In addition, for runtime dependencies, indicates that the package specifying the dependency will break unless there is available a package matching the dependency and whose slot and sub-slot are equal to the slot and sub-slot of the best installed version that had matched this dependency at the time when the package specifying this dependency had been installed. - </li> - <li> - <c>:slot=</c> Indicates that only a specific slot value is acceptable, and otherwise behaves identically to the <c>:=</c> operator. - <note> - use <c>:slot/subslot</c> without a <c>=</c> to depend on a specific slot and sub-slot pair; it's a syntax error to use <c>:slot/subslot=</c> in an ebuild. - </note> - </li> - </ul> - <p> - The <c>:slot</c> dependency syntax continues to behave like in EAPI=4 or earlier, i.e. it indicates that only the specific slot value is acceptable, but the package will not break when the version matching the runtime dependency is replaced by a version with a different sub-slot. - </p> - <p> - For example: - </p> - <codesample lang="ebuild"> -RDEPEND="dev-libs/foo:2= - >=dev-libs/bar-0.9:= - media-gfx/baz:* - x11-misc/wombat:0" - </codesample> - <p> - means that the package should be rebuilt when <c>foo:2</c> or <c>>=bar-0.9</c> are upgraded to versions with different subslots, but that changes in subslots of <c>baz</c> or <c>wombat:0</c> should be ignored. - </p> - </li> -</ul> + +<dl> + <dt><c>PORTDIR</c> and <c>ECLASSDIR</c> are removed</dt> + <dd> + <c>PORTDIR</c> and <c>ECLASSDIR</c> are no longer defined and cannot be + used in ebuilds to access these directories. + </dd> + <dt><c>DESTTREE</c> and <c>INSDESTTREE</c> are removed</dt> + <dd> + The unintended exported variables <c>PORTDIR</c> and <c>ECLASSDIR</c> + cannot be used in ebuilds to manipulate installation paths. Use <c>into</c> + or <c>insinto</c>, respectively, instead. + </dd> + <dt><c>D</c>, <c>ED</c>, <c>ROOT</c>, and <c>EROOT</c> modified</dt> + <dd> + These variables no longer contain a trailing slash with <c>EAPI=7</c>. + </dd> + <dt><c>BDEPEND</c> added</dt> + <dd> + Previously, all build-time tools and libraries went into the <c>DEPEND</c>. + Now, built-time dependencies are split into <c>DEPEND</c> and + <c>BDEPEND</c>. The difference is simply that <c>BDEPEND</c> are + dependencies to be executed on the CBUILD. <c>DEPEND</c> remains for other + dependencies, such as libraries, for the CHOST. This improves the + cross-compilation support. + </dd> + <dt><c>BROOT</c> added</dt> + <dd> + <c>BROOT</c> is the absolute path to the root directory, including any + prefix, containing build dependencies satisfied by BDEPEND, typically + executable build tools. + </dd> + <dt><c>SYSROOT</c> and <c>ESYSROOT</c> added</dt> + <dd> + <c>SYSROOT</c> is the location of where dependencies in <c>DEPEND</c> are + installed. <c>ESYSROOT</c> is <c>SYSROOT</c> with <c>EPREFIX</c> appended. + </dd> + <dt><c>ENV_UNSET</c> added</dt> + <dd> + A whitespace delimited list of variables to be removed from the build + environment. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Profiles</title> +<title>EAPI 7 metadata</title> <body> -<ul> - <li> - <p><b>Profile stable USE forcing and masking</b></p> - <p> - In profile directories with an EAPI supporting stable masking, new USE configuration files are supported: <c>use.stable.mask</c>, <c>use.stable.force</c>, <c>package.use.stable.mask</c> and <c>package.use.stable.force</c>. These files behave similarly to previously supported USE configuration files, except that they only influence packages that are merged due to a stable keyword. - </p> - </li> -</ul> + +<dl> + <dt>Empty groupings are banned</dt> + <dd> + Groupings which are empty, such as <c>DEPEND="|| ( ${empty_var} )"</c> + will now generate an error. Furthermore, conditions within groupings are + more strictly enforced. For example, <c>REQUIRED_USE="|| ( foo? ( bar ) + baz? ( zoinks )"</c> would previously work with <c>USE="-foo -baz"</c> + now requires either <c>USE="foo bar"</c> or <c>USE="baz zoinks"</c>. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Helpers</title> +<title>EAPI 7 profiles</title> <body> -<ul> - <li> - <p><b>econf adds --disable-silent-rules</b></p> - <p> - This option will automatically be passed if <c>--disable-silent-rules</c> occurs in the output of <c>configure --help</c>. - </p> - </li> - <li> - <p><b>new* commands can read from standard input</b></p> - <p> - Standard input is read when the first parameter is <c>-</c> (a hyphen). - </p> - </li> - <li> - <p><b>New option --host-root for {has,best}_version</b></p> - <p> - This option <c>--host-root</c> will cause the query to apply to the host root instead of ROOT. - </p> - </li> - <li> - <p><b>New doheader helper function</b></p> - <p> - Installs the given header files into <c>/usr/include/</c>, by default with file mode <c>0644</c>. This can be overridden by setting <c>INSOPTIONS</c> with the <c>insopts</c> function. - </p> - </li> - <li> - <p><b>New usex helper function</b></p> - <p> - <!-- We probably need an example here --> - <pre> -USAGE: usex 〈USE flag〉 [true output] [false output] [true suffix] [false suffix] -DESCRIPTION: -If USE flag is set, echo [true output][true suffix] (defaults to "yes"), - otherwise echo [false output][false suffix] (defaults to "no"). - </pre> - </p> - </li> -</ul> + +<dl> + <dt><c>package.provided</c> banned</dt> + <dd> + Profiles may no longer contain a <c>package.provided</c> file with + <c>EAPI=7</c>. + </dd> +</dl> + </body> </subsection> <subsection> -<title>Phases</title> +<title>EAPI 7 helpers</title> <body> -<ul> - <li> - <p><b>src_test supports parallel tests</b></p> - <p> - Unlike older EAPIs, the default <c>src_test</c> implementation will not pass the -j1 option to emake. - </p> - </li> -</ul> + +<dl> + <dt><c>dohtml</c> banned</dt> + <dd> + The <c>dohtml</c> helper has been banned with <c>EAPI=7</c>. + </dd> + <dt><c>dolib</c> and <c>libopts</c> banned</dt> + <dd> + The <c>dolib</c> helper and the associated <c>libopts</c> have been banned + with <c>EAPI=7</c>. + </dd> + <dt><c>has_version</c> and <c>best_version</c> changes</dt> + <dd> + <p> + <c>has_version</c> and <c>best_version</c> now support an optional switch + to determine which type of dependencies to check. + </p> + <ul> + <li><c>-r</c> (the default) will check runtime dependencies (RDEPEND)</li> + <li><c>-d</c> will check CHOST build-time dependencies (DEPEND)</li> + <li><c>-b</c> will check CBUILD build-time dependencies (BDEPEND)</li> + </ul> + </dd> + <dt>Version manipulation and comparison commands</dt> + <dd> + <p> + EAPI=7 introduced three commands for common version number operations. + </p> + <ul> + <li><c>ver_cut</c> obtains substrings of a version string</li> + <li><c>ver_rs</c> replaces separators in a version string</li> + <li><c>ver_test</c> compares two versions</li> + </ul> + <p> + See <uri link="::ebuild-writing/variables/#Version and name formatting issues"/> + for examples of common uses or + <uri link="https://dev.gentoo.org/~mgorny/articles/the-ultimate-guide-to-eapi-7.html#version-manipulation-and-comparison-commands"> + an in-depth look</uri> + </p> + </dd> + <dt>New function <c>eqawarn</c></dt> + <dd> + The <c>eqawarn</c> helper has been added with <c>EAPI=7</c>. This function + is to alert developers to a deprecated feature. Previously, this was + contained in <c>eutils</c> eclass which is no longer necessary. + </dd> + <dt>New function <c>dostrip</c></dt> + <dd> + The <c>dostrip</c> helper has been added with <c>EAPI=7</c>. This function + controls whether or not to strip a binary. <c>dostrip -x [file]</c> will + exclude a binary from being stripped. Conversely, when combined with + RESTRICT=strip, <c>dostrip [file]</c> selects a binary file to be stripped. + </dd> + <dt><c>die</c> and <c>assert</c> changes</dt> + <dd> + These commands are now safe to use in a subshell and act as if they were + called in the main process. + </dd> + <dt><c>nonfatal</c> changes</dt> + <dd> + The <c>nonfatal</c> command now works for shell functions and subprocesses. + </dd> + <dt><c>domo</c> behaviour changed</dt> + <dd> + <c>domo</c> (for localizations) now ignores the <c>into</c> directives. + This follows similar commands like <c>doinfo</c> and <c>doman</c>. + </dd> + <dt><c>econf</c> changes</dt> + <dd> + The cross-compilation options <c>--build</c> and <c>--target</c> options + to specify <c>CBUILD</c> and <c>CTARGET</c> respectively have been added + and are retro-active to all EAPIs. In addition, if the build supports + <c>--with-sysroot</c>, the correct value will be passed such that normal + and cross-compilations succeed. + </dd> +</dl> + </body> </subsection> +</section> + +<section> +<title>EAPI 8</title> +<body> + +<note> +This section is based on +<uri link="https://mgorny.pl/articles/the-ultimate-guide-to-eapi-8.html"> +The ultimate guide to EAPI 8</uri> by Michał Górny. +</note> + +</body> <subsection> -<title>Variables</title> +<title>EAPI 8 tree layout</title> <body> -<ul> - <li> - <p><b>EBUILD_PHASE_FUNC</b></p> - <p> - During execution of an ebuild phase function (such as <c>pkg_setup</c> or <c>src_unpack</c>), - the <c>EBUILD_PHASE_FUNC</c> variable will contain the name of the phase function that is currently executing. - </p> - </li> -</ul> + +<dl> + <dt>Less strict naming rules for updates directory</dt> + <dd> + <p> + Up to EAPI 7, the files in the <c>profiles/updates</c> directory had to + follow strict naming by quarters like <c>2Q-2021</c>, indicating the + quarter and the year when they were added. Such a choice of name had the + side effect that lexical sorting of filenames was unsuitable. + </p> + + <p> + In EAPI 8, the naming requirement is removed. Eventually, this will allow + switching to a more convenient scheme sorted by year. Different lengths + of time periods will also be possible. + </p> + + <p> + Note that this change actually requires changing the repository EAPI + (found in <c>profiles/eapi</c>), so it will not affect Gentoo for at least + the next two years. + </p> + </dd> +</dl> + </body> </subsection> +<subsection> +<title>EAPI 8 ebuild format</title> +<body> + +<dl> + <dt>Bash version is now 5.0</dt> + <dd> + <p> + The Bash version used for ebuilds is changed from 4.2 to 5.0. This means + not only that ebuilds are now permitted to use features provided by the new + Bash version but also the <c>BASH_COMPAT</c> value used for the ebuild + environment is updated, switching the shell behaviour. + </p> + + <p> + The only really relevant difference in behaviour is: + </p> + + <ul> + <li> + <p> + Quotes are now removed from the RHS argument of a + <c>"${var/.../"..."}"</c> substitution: + </p> + +<pre> +var=foo +echo "${var/foo/"bar"}" +</pre> + + <p> + The above snippet yields <c>"bar"</c> in Bash 4.2 but just <c>bar</c> + in 4.3+. + </p> + </li> + </ul> + + <p> + Potentially interesting new features include: + </p> + + <ul> + <li> + <p> + Negative subscripts can now be used to set and unset array elements + (Bash 4.3+): + </p> + +<pre> +$ foo=( 1 2 3 ) +$ foo[-1]=4 +$ unset 'foo[-2]' +$ declare -p foo +declare -a foo=([0]="1" [2]="4") +</pre> + + </li> + <li> + <p> + Nameref variables are introduced that work as references to other + variables (4.3+): + </p> + +<pre> +$ foo=( 1 2 3 ) +$ declare -n bar=foo +$ echo "${bar[@]}" +1 2 3 +$ bar[0]=4 +$ echo "${foo[@]}" +4 2 3 +$ declare -n baz=foo[1] +$ echo "${baz}" +2 +$ baz=100 +$ echo "${bar[@]}" +4 100 3 +</pre> + + </li> + <li> + <p> + The <c>[[ -v ... ]]</c> test operator can be used with array indices + to test for array elements being set (4.3+). The two following lines + are now equivalent: + </p> + +<pre> +[[ -n ${foo[3]+1} ]] +[[ -v foo[3] ]] +</pre> + </li> + <li> + <p> + <c>mapfile</c> (AKA <c>readarray</c>) now accepts a delimiter via + <c>-d</c>, with a <c>-t</c> option to strip it from read data + (Bash 4.4+). The two following solutions to grab output from + <c>find(1)</c> are now equivalent: + </p> + +<pre> +# old solution +local x files=() +while read -d '' -r x; do + files+=( "${x}" ) +done < <(find -print0) + +# new solution +local files=() +mapfile -d '' -t files < <(find -print0) +</pre> + + </li> + <li> + <p> + A new set of transformations is available via <c>${foo@...}</c> + parameter expansion (4.4+), e.g. to print a value with necessary + quoting: + </p> + +<pre> +$ var="foo 'bar' baz" +$ echo "${var@Q}" +'foo '\''bar'\'' baz' +</pre> + + <p> + For more details, see: <c>info bash</c> or the + <uri link="https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html"> + Bash reference manual</uri>. + </p> + </li> + <li> + <p> + <c>local -</c> can be used to limit single-letter (mangled via + <c>set</c>) shell option changes to the scope of the function, and + restore them upon returning from it (4.4+). The following two functions + are now equivalent: + </p> + +<pre> +# old solution +func() { + local prev_shopt=$(shopt -p -o noglob) + set -o noglob + ${prev_shopt} +} + +# new solution +func() { + local - + set -o noglob +} +</pre> + + <p> + The complete information on all changes and new features can be found + in the + <uri link="https://git.savannah.gnu.org/cgit/bash.git/tree/NEWS?h=bash-5.0"> + Bash 5.0 (and earlier) release notes</uri>. + </p> + </li> + </ul> + </dd> +</dl> </body> -</section> +</subsection> +<subsection> +<title>EAPI 8 variables</title> +<body> + +<dl> + <dt>Selective fetch/mirror restriction</dt> + <dd> + <p> + Before EAPI 8, fetch and mirror restrictions applied globally. That is, + if you needed to apply the respective restriction to at least one distfile, + you had to apply it to them all. However, sometimes packages used a + combination of proprietary and free distfiles, the latter including e.g. + third party patches, artwork. Until now, they had to be mirror-restricted + completely. + </p> + + <p> + EAPI 8 allows undoing fetch and mirror restriction for individual files. + To use this, set <c>RESTRICT</c> as before, then use the special + <c>fetch+</c> prefix to specify URLs that can be fetched from, or the + <c>mirror+</c> prefix to reenable mirroring of individual files. + </p> + + <p> + Similarly to how the <c>fetch</c> restriction implies a <c>mirror</c> + restriction, the <c>mirror</c> override implies a <c>fetch</c> override. + </p> + +<codesample lang="ebuild"> +EAPI=8 + +SRC_URI=" + ${P}.tgz + fetch+https://example.com/${P}-patch-1.tgz + mirror+https://example.com/${P}-fanstuff.tgz" + +RESTRICT="fetch" +</codesample> + + <p> + The following table summarises the new behaviour: + </p> + + <table> + <tr> + <th><c>RESTRICT</c></th> + <th>URI prefix</th> + <th>Fetching</th> + <th>Mirroring</th> + </tr> + <tr> + <ti>(none)</ti> + <ti>(any)</ti> + <ti>allowed</ti> + <ti>allowed</ti> + </tr> + <tr> + <ti rowspan="2">mirror</ti> + <ti>(none) / fetch+</ti> + <ti>allowed</ti> + <ti>prohibited</ti> + </tr> + <tr> + <ti>mirror+</ti> + <ti>allowed</ti> + <ti>allowed</ti> + </tr> + <tr> + <ti rowspan="3">fetch</ti> + <ti>(none)</ti> + <ti>prohibited</ti> + <ti>prohibited</ti> + </tr> + <tr> + <ti>fetch+</ti> + <ti>allowed</ti> + <ti>prohibited</ti> + </tr> + <tr> + <ti>mirror+</ti> + <ti>allowed</ti> + <ti>allowed</ti> + </tr> + </table> + </dd> + + <dt>Install-time dependencies (<c>IDEPEND</c>)</dt> + <dd> + <p> + The primary use for install-time dependencies is to specify dependencies + that are needed during the <c>pkg_postinst</c> phase and that can be + unmerged afterwards. That's pretty much the same as <c>RDEPEND</c>, except + for the unmerging part <d/> and uninstalling a few tools did not seem a + goal justifying another dependency type. + </p> + + <p> + With cross-compilation support in EAPI 7, a new dependency type focused + on the build host (<c>CBUILD</c>) tools was added <d/> <c>BDEPEND</c>. + Unfortunately, this had missed the important use case of running + executables installed to the target system when cross-compiling. + <c>RDEPEND</c> was no longer a suitable method of pulling in tools for + <c>pkg_postinst</c>; and since <c>BDEPEND</c> is not used when installing + from a binary package, something new was needed. + </p> + + <p> + This is where <c>IDEPEND</c> comes in. It is roughly to <c>RDEPEND</c> what + <c>BDEPEND</c> is to <c>DEPEND</c>. Similarly to <c>BDEPEND</c>, + it specifies packages that must be built for the <c>CBUILD</c> triplet + and installed into <c>BROOT</c> (and therefore queried using + <c>has_version -b</c>). However, similarly to <c>RDEPEND</c>, it is used + when the package is being merged rather than built from source. + It is guaranteed to be satisfied throughout <c>pkg_preinst</c> and + <c>pkg_postinst</c>, and it can be uninstalled afterwards. + </p> + +<codesample lang="ebuild"> +EAPI=8 + +inherit xdg-utils + +IDEPEND="dev-util/desktop-file-utils" + +pkg_postinst() { + xdg_desktop_database_update +} + +pkg_postrm() { + xdg_desktop_database_update +} +</codesample> + + <p> + In the example provided above, the ebuild needs to be update the icon cache + upon being installed or uninstalled. By placing the respective tool in + <c>IDEPEND</c>, the ebuild requests it to be available at the time of + <c>pkg_postinst</c>. When cross-compiling, the tool will be built for + <c>CBUILD</c> and therefore directly executable by the ebuild. + </p> + + <p> + The dependency types table for EAPI 8 is presented below. + </p> + + <table> + <tr> + <th>Dependency type</th> + <th>BDEPEND</th> + <th>IDEPEND</th> + <th>DEPEND</th> + <th>RDEPEND</th> + <th>PDEPEND</th> + </tr> + <tr> + <th>Present at</th> + <ti>build</ti> + <ti>install</ti> + <ti>build</ti> + <ti>install</ti> + <ti>n/a</ti> + </tr> + <tr> + <th>Binary compatible with</th> + <ti colspan="2">CBUILD</ti> + <ti colspan="3">CHOST</ti> + </tr> + <tr> + <th>Base unprefixed path</th> + <ti colspan="2"><c>/</c></ti> + <ti>SYSROOT</ti> + <ti colspan="2">ROOT</ti> + </tr> + <tr> + <th>Relevant offset-prefix</th> + <ti colspan="2">BROOT</ti> + <ti>EPREFIX (unless SYSROOT != ROOT)</ti> + <ti colspan="2">EPREFIX</ti> + </tr> + <tr> + <th>Path combined with prefix</th> + <ti colspan="2">BROOT</ti> + <ti>ESYSROOT</ti> + <ti colspan="2">EROOT</ti> + </tr> + <tr> + <th>PM query command option</th> + <ti colspan="2"><c>-b</c></ti> + <ti><c>-d</c></ti> + <ti colspan="2"><c>-r</c></ti> + </tr> + </table> + </dd> + + <dt> + <c>PROPERTIES</c> and <c>RESTRICT</c> are now accumulated across eclasses + </dt> + <dd> + <p> + Up to EAPI 7, <c>PROPERTIES</c> and <c>RESTRICT</c> were treated like + regular Bash variables when sourcing eclasses. This meant that if an eclass + or an ebuild wanted to modify them, they had to explicitly append to them, + e.g. via <c>+=</c>. This was inconsistent with how some other variables + (but not all) were handled, and confusing to developers. For example, + consider the following snippet: + </p> + +<codesample lang="ebuild"> +EAPI=7 + +inherit git-r3 + +PROPERTIES+=" live" +</codesample> + + <p> + Note how you needed to append to <c>PROPERTIES</c> set by git-r3 eclass, + otherwise the ebuild would have overwritten it. In EAPI 8, you can finally + do the following instead: + </p> + +<codesample lang="ebuild"> +EAPI=8 + +inherit git-r3 + +PROPERTIES="live" +</codesample> + + <p> + Now the complete list of metadata variables accumulated across eclasses + and ebuilds includes: <c>IUSE</c>, <c>REQUIRED_USE</c>, <c>*DEPEND</c>, + <c>PROPERTIES</c>, <c>RESTRICT</c>. Variables that are not treated this way + are: <c>EAPI</c>, <c>HOMEPAGE</c>, <c>SRC_URI</c>, <c>LICENSE</c>, + <c>KEYWORDS</c>. <c>EAPI</c> and <c>KEYWORDS</c> are not supposed to be set + in eclasses; as for the others, there appears to be a valid use case for + eclasses providing default values and the ebuilds being able to override + them. + </p> + </dd> +</dl> + +</body> +</subsection> +<subsection> +<title>EAPI 8 phase functions</title> +<body> + +<dl> + <dt><c>pkg_*</c> phases now run in a dedicated empty directory</dt> + <dd> + <p> + Before EAPI 8, the initial working directory was specified for <c>src_*</c> + phases only. For other phases (i.e. <c>pkg_*</c> phases), ebuilds were not + supposed to assume any particular directory. In EAPI 8, these phases are + guaranteed to be started in a dedicated empty directory. + </p> + + <p> + The idea of using an empty directory is pretty simple <d/> if there are no + files in it, the risk of unexpected and hard to predict interactions of + tools with their current working directory is minimized. + </p> + </dd> + + <dt> + <c>PATCHES</c> no longer permits options + </dt> + <dd> + <p> + The <c>eapply</c> invocation in the default <c>src_prepare</c> + implementation has been changed to: + </p> + +<codesample lang="ebuild"> +eapply -- "${PATCHES[@]}" +</codesample> + + <p> + This ensures that all items in the <c>PATCHES</c> variable are treated + as path names. As a side effect, it is no longer possible to specify + <c>patch</c> options via the <c>PATCHES</c> variable. Such hacks were never + used in the Gentoo repository but they have been spotted in + user-contributed ebuilds. The following will no longer work: + </p> + +<codesample lang="ebuild"> +PATCHES=( -p0 "${FILESDIR}"/${P}-foo.patch ) +</codesample> + + <p> + Instead, you will need to invoke <c>eapply</c> explicitly, see the example + below. Alternatively, rebase the patch level. + </p> + +<codesample lang="ebuild"> +src_prepare() { + eapply -p0 "${FILESDIR}"/${P}-foo.patch + eapply_user +} +</codesample> + + </dd> +</dl> </body> +</subsection> +<subsection> +<title>EAPI 8 commands</title> +<body> + +<dl> + <dt>New econf-passed options</dt> + <dd> + <p> + The <c>econf</c> helper has been modified to pass two more options to + the configure script if the <c>--help</c> text indicates that they are + supported. These are: + </p> + + <ul> + <li><c>--datarootdir="${EPREFIX}"/usr/share</c></li> + <li><c>--disable-static</c></li> + </ul> + + <p> + The former option defines the base directory that is used to determine + locations for system/desktop-specific data files, e.g. .desktop files and + various kinds of documentation. This is necessary for ebuilds that override + <c>--prefix</c>, as the default path is relative to it. + </p> + + <p> + The latter option disables building static libraries by default. This is + part of the ongoing effort to disable unconditional install of static + libraries + (<uri link="https://projects.gentoo.org/qa/policy-guide/installed-files.html#pg0302"> + Gentoo Policy Guide, Installation of static libraries</uri>). + </p> + </dd> + + <dt><c>dosym -r</c> to create relative symlinks</dt> + <dd> + <p> + Relative symlink targets tend to be more reliable. Consider the two + following examples: + </p> + +<codesample lang="ebuild"> +dosym "${EPREFIX}"/usr/lib/frobnicate/frobnicate /usr/bin/frobnicate +dosym ../lib/frobnicate/frobnicate /usr/bin/frobnicate +</codesample> + + <p> + The first line creates a symlink using an absolute path. The problem with + that is if you mount your Gentoo system in a subdirectory of your root + filesystem (e.g. for recovery), the symlink will point at the wrong + location. Using relative symlinks (as demonstrated on the second line) + guarantees that the symlink will work independently of where the filesystem + is mounted. + </p> + + <p> + There is also fact that you need to explicitly prepend <c>${EPREFIX}</c> + to the absolute paths passed as the first argument of <c>dosym</c>. Using + a relative target avoids the problem altogether and makes it less likely to + forget about the prefix. + </p> + + <p> + However, in some instances, determining the relative path could be hard or + inconvenient. This is especially the case if one (or both) of the paths + comes from an external tool. To make it easier, EAPI 8 adds a new <c>-r</c> + option that makes <c>dosym</c> create a relative symlink to the specified + path (similarly to <c>ln -r</c>): + </p> + +<codesample lang="ebuild"> +dosym -r /usr/lib/frobnicate/frobnicate /usr/bin/frobnicate +</codesample> + + <p> + Note that in this case, you do not pass <c>${EPREFIX}</c>. The helper + determines the <e>logical</e> relative path to the first argument and + creates the appropriate relative symlink. It is very important here to + understand that this function does not handle physical paths, i.e. it will + work only if there are no directory symlinks along the way that would + result in <c>..</c> resolving to a different path. For example, the + following will not work: + </p> + +<codesample lang="ebuild"> +dosym bar/foo /usr/lib/foo +dosym -r /usr/lib/zomg /usr/lib/foo/zomg +</codesample> + + <p> + The logical path from <c>/usr/lib/foo/zomg</c> to <c>/usr/lib/zomg</c> is + <c>../zomg</c>. However, since <c>/usr/lib/foo</c> is actually a symlink to + <c>/usr/lib/bar/foo</c>, <c>/usr/lib/foo/..</c> resolves to + <c>/usr/lib/bar</c>. If you need to account for such directory symlinks, + you need to specify the correct path explicitly: + </p> + +<codesample lang="ebuild"> +dosym bar/foo /usr/lib/foo +dosym ../../zomg /usr/lib/foo/zomg +</codesample> + + </dd> + + <dt> + <c>insopts</c> and <c>exeopts</c> now apply to <c>doins</c> + and <c>doexe</c> only + </dt> + <dd> + <p> + In previous EAPIs, there was an inconsistency in how <c>insopts</c> and + <c>exeopts</c> applied to various helpers. In particular, the majority of + helpers (e.g. <c>dobin</c>, <c>dodoc</c> and so on) ignored the options + specified via these helpers but a few did not. + </p> + + <p> + EAPI 8 changes the behaviour of the following helpers that used to respect + <c>insopts</c> or <c>exeopts</c>: + </p> + + <ul> + <li><c>doconfd</c></li> + <li><c>doenvd</c></li> + <li><c>doheader</c></li> + <li><c>doinitd</c></li> + </ul> + + <p> + In EAPI 8, they always use the default options. As a result, <c>insopts</c> + now only affects <c>doins</c>/<c>newins</c>, and <c>exeopts</c> only + affects <c>doexe</c>/<c>newexe</c>. Furthermore, <c>diropts</c> does not + affect the directories implicitly created by these helpers. + </p> + </dd> + + <dt><c>usev</c> now accepts a second argument</dt> + <dd> + <p> + The <c>usev</c> helper was introduced to provide the historical Portage + behaviour of outputting the USE flag name on match. In EAPI 8, it has been + extended, in order to provide an alternative to three-argument <c>usex</c> + with an empty third argument (the two-argument <c>usex</c> variant uses a + default of <c>no</c> for the false branch). + </p> + + <p> + In other words, the following two calls are now equivalent: + </p> + +<codesample lang="ebuild"> +$(usex foo --enable-foo '') +$(usev foo --enable-foo) +</codesample> + + <p> + This is particularly useful with custom build systems that accept + individual <c>--enable</c> or <c>--disable</c> options but not their + counterparts. + </p> + + <p> + As a result, <c>usev</c> and <c>usex</c> can now be used to achieve all the + common (and less common) output needs as summarized in the following table. + </p> + + <table> + <tr> + <th>Variant</th> + <th>True</th> + <th>False</th> + </tr> + <tr> + <ti>usev <e>flag</e></ti> + <ti><e>flag</e></ti> + <ti></ti> + </tr> + <tr> + <ti>usev <e>flag</e> <e>true</e></ti> + <ti><e>true</e></ti> + <ti></ti> + </tr> + <tr> + <ti>usex <e>flag</e></ti> + <ti><c>yes</c></ti> + <ti><c>no</c></ti> + </tr> + <tr> + <ti>usex <e>flag</e> <e>true</e></ti> + <ti><e>true</e></ti> + <ti><c>no</c></ti> + </tr> + <tr> + <ti>usex <e>flag</e> <e>true</e> <e>false</e></ti> + <ti><e>true</e></ti> + <ti><e>false</e></ti> + </tr> + </table> + </dd> + + <dt><c>hasq</c>, <c>hasv</c> and <c>useq</c> functions have been banned</dt> + <dd> + <p> + In its early days, the <c>use</c> helper would print the USE flag name + if it matched, in addition to its boolean exit status. Later, a quiet + <c>useq</c> and a verbose <c>usev</c> helper were added, and <c>use</c> was + made quiet by default. The same changes were applied to <c>has</c>. + </p> + + <p> + Fast forward to EAPI 7, there are still three variants of <c>use</c> + and three variants of <c>has</c>. The base variant that is quiet, the + <c>useq</c>/<c>hasq</c> variant that is equivalent to the base variant, + and the verbose <c>usev</c>/<c>hasv</c> variant. + </p> + + <p> + Obviously, adding a second argument to <c>hasv</c> was not possible, so its + behaviour would have become inconsistent with <c>usev</c> in EAPI 8. Since + <c>hasv</c> was not used in the Gentoo repository, it has been removed, + along with <c>hasq</c> and <c>useq</c> which were considered deprecated + since 2011. + </p> + </dd> + + <dt>unpack removes support for 7-Zip, LHA and RAR formats</dt> + <dd> + <p> + Support for the least commonly used archive formats from <c>unpack</c> has + been removed: + </p> + + <ul> + <li>7-Zip (.7z)</li> + <li>LHA (.lha, .lzh)</li> + <li>RAR (.rar)</li> + </ul> + + <p> + Packages using these format for distfiles must now unpack them manually. + Using <c>unpacker.eclass</c> is recommended for this. + </p> + </dd> +</dl> + +</body> +</subsection> +</section> </chapter> </guide> diff --git a/ebuild-writing/ebuild-maintenance/text.xml b/ebuild-writing/ebuild-maintenance/text.xml deleted file mode 100644 index 4fa3a8b..0000000 --- a/ebuild-writing/ebuild-maintenance/text.xml +++ /dev/null @@ -1,487 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/ebuild-maintenance/"> -<chapter> -<title>Ebuild Maintenance</title> - -<body> -<p> -This guide aims to explain common everyday ebuild maintenance -routines, as well as other rarer maintenance routines which -developers may not be familiar with. -</p> - -<section> -<title>Adding a new ebuild</title> -<body> - -<subsection> -<title>What (not) to put in the Portage tree</title> -<body> - -<p> -Before writing a new ebuild, check -<uri link="https://bugs.gentoo.org/">bugs.gentoo.org</uri> -to see if an ebuild has already been written for the package, but has not yet -been added to the Portage tree. Go to <uri -link="https://bugs.gentoo.org/">bugs.gentoo.org</uri>, choose query and select -Advanced Search; as product select <e>Gentoo Linux</e>, as component select -<e>ebuilds</e>. In the search field put the name of the ebuild and as status -select NEW, ASSIGNED, REOPENED and RESOLVED (RESOLVED is important), then -submit the query. For you lazy people, click <uri -link="https://bugs.gentoo.org/query.cgi?product=Gentoo%20Linux&component=Ebuilds&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&bug_status=RESOLVED">here</uri>. -</p> - -<p> -In general, the Portage tree should only be used for storing -<path>.ebuild</path> files, as well as any relatively small companion -files, such as patches or sample configuration files. These types of -files should be placed in the <path>/usr/portage/mycat/mypkg/files</path> -directory to keep the main <path>mycat/mypkg</path> directory uncluttered. -Exceptions to this rule are for larger patch files (we recommend this for patches -above 20KB) which should be distributed as tarballs via the -<uri link="::general-concepts/mirrors/#suitable-download-hosts">Gentoo mirror system</uri> -so that people do not waste excessive amounts of bandwidth and hard drive -space. Also, you should not add binary (non-ASCII) files to the -Portage CVS tree. If you need to do this in another CVS tree, for -example, if you need to add a small PNG graphic for whatever reason, -be sure to add it to CVS by using the <c>-kb</c> option, like so: -</p> - -<pre caption="Adding binary files to CVS"> -# <i>cvs add -kb myphoto.png</i> -</pre> - -<p> -The <c>-kb</c> option tells CVS that <path>myphoto.png</path> is a binary -file and should be treated specially. For example, merging the -differences between two different versions of this file should not be -allowed to happen, for obvious reasons. Also, speaking of merging -changes, any patches you add to Portage should generally <e>not</e> be -compressed. This will allow CVS to merge changes and correctly inform -developers of conflicts. -</p> - -<p> -Remember, the packages that you commit must be <e>ready</e> <e>out of the -box</e> for end users when committed as stable. Make sure that you have a good -set of default settings that will satisfy the majority of systems and -users that will use your package. If your package is broken, and you are -not sure how to get it to work, check some other distributions that have -done their own versions of the package. You can check -<uri link="http://cvs.mandriva.com/cgi-bin/viewvc.cgi/SPECS/">Mandriva</uri> -or <uri link="http://www.debian.org/distrib/packages">Debian</uri> or -<uri link="http://cvs.fedora.redhat.com/">Fedora</uri> for some -examples. -</p> - -<p> -When committing to CVS, all developers should use <c>repoman commit</c> -instead of <c>cvs commit</c> to submit their ebuilds. Before committing, -please run <c>repoman full</c> to make sure you didn't forget something. -</p> - -</body> -</subsection> - -<subsection> -<title>Initial Architecture Keywords</title> -<body> -<p> -When adding a new ebuild, you should only include <c>KEYWORDS</c> for -architectures on which you have actually tested the ebuild, confirming -that it works as it should and that <c>USE</c> flags are properly -honoured in the resulting package which would be installed. If -possible, you should give the actual library or application thorough -testing as well, since you would be responsible for any breakages for -your architecture(s). Minimal testing such as checking that the -application starts up without any errors should always be performed. -</p> - -<p> -If you are adding a user-submitted ebuild, do not assume that the -submitter has done testing on various architectures: often, <c>KEYWORDS</c> -are cloned across packages or generated from documentation in the -source packages, which does not signify that the package does indeed -work on those architectures. -</p> - -</body> -</subsection> - -<subsection> -<title>CVS Commit Policy</title> -<body> - -<ul> -<li>Always run <c>repoman scan</c> before you commit.</li> -<li>Please run <c>repoman full</c> before you commit.</li> -<li>Always test that <path>package.mask</path> is okay by doing -<c>emerge --pretend mypkg</c> before you commit and check -that it doesn't contain any conflicts.</li> -<li>Always update the <path>ChangeLog</path> before you commit.</li> -<li>Always commit the updated <path>package.mask</path> before -the updated package, in case conflicts occur while you commit -<path>package.mask</path>.</li> -<li>Always do atomic commits; if you commit a package with a new license, -or that is masked, then first commit the revised <path>package.mask</path> and/or license, -then commit the ebuild, <path>ChangeLog</path>, patches -and <uri link="::ebuild-writing/misc-files/metadata">metadata.xml</uri> all in <b>one</b> go -to avoid breaking users' installations.</li> -</ul> - -</body> -</subsection> - -<subsection> -<title>The files Directory</title> -<body> - -<p> -As noted earlier, under each package subdirectory is -a <path>files/</path> directory. Any patches, configuration files, or -other ancillary files your package might require should be added to -this directory; any files bigger than 20KB-or-so should go to the -mirrors to lower the amount of (unneeded) files our users have to -download. You may want to consider naming patches you create yourself -just to get your package to build with a version-specific name, such -as <path>mypkg-1.0-gentoo.diff</path>, or more -simply, <path>1.0-gentoo.diff</path>. Also note that the -<path>gentoo</path> extension informs people that this patch was created -by us, the Gentoo Linux developers, rather than having been grabbed from a -mailing list or somewhere else. Again, you should not compress these -patches because CVS does not play well with binary files. -</p> - -<p> -Consider prefixing or suffixing (such as <path>mypkg-1.0</path>) every file -you put into the <path>files/</path> directory, so that the files used for -each individual version on an ebuild are distinguishable from one another, and -so that the changes between different revisions are visible. This is generally -a really good idea :). You may want to use a different suffix if you wish to -convey more meaning with the patch name. -</p> - -<p> -If you have many files that should go into the <path>files/</path> directory, -consider creating subdirectories such as <path>files/1.0/</path> and putting the -relevant files in the appropriate subdirectory. If you use this method, -you do not need to add version information to the names of the files, -which is often more convenient. -</p> - -</body> -</subsection> - -</body> -</section> - -<section> -<title>Touching other developers ebuilds</title> -<body> -<p>Usually you don't just change other developers ebuilds without permission unless you know that developer does not mind or if you are part of the herd involved in maintenance (this information can typically be found in metadata.xml). Start with filing a bug or trying to catch them on IRC or via email. Sometimes you cannot reach them, or there is no response to your bug. It's a good idea to consult other developers on how to handle the situation, especially if it's a critical issue that needs to be handled ASAP. Otherwise a soft limit of 2 to 4 weeks depending on the severity of the bug is an acceptable time frame before you go ahead and fix it yourself.</p> -<important> Common sense dictates to us that toolchain/base-system/core packages and eclasses or anything else which is delicate (e.g. glibc) or widely used (e.g. gtk+) should usually be left to those maintainers. If in doubt, don't touch it.</important> -</body> -</section> - -<section> -<title>Stabilizing ebuilds</title> -<body> - -<p> -Only architecture maintainers for a given architecture should mark packages as -stable on that architecture. The maintainer of the package should always be -contacted just in case there are reasons not to do so. The exception to this -is if you are part of an architecture team, in which case you may mark the -package stable for that architecture. If you are not part of an architecture -team, you should consult the guidelines below; if the architecture you are -looking for is not listed then please consult the relevant lead. -</p> - -<p> -You should <e>never</e> stabilize packages on -architectures for which you cannot test and instead you should file a bug to -the relevant architecture team, such as <mail link="sparc@gentoo.org"> -sparc@gentoo.org</mail> asking them to stabilize the -ebuild. Alternatively, you may be able to find Gentoo developers on -IRC who could help you with your request. -</p> - -<p> -It is best to not use <mail link="arch-maintainers@gentoo.org"> -arch-maintainers@gentoo.org</mail>, adding architecture teams onto a -bug's CC list individually instead. That way teams can remove -themselves from the list when they are done, giving a clear indication -of which teams still have to stabilize a package. -</p> - -</body> -</section> - -<section> -<title>Stabilization rules</title> -<body> - -<p> -SPARC: You must have prior permission from the arch lead. Usually we expect -you to be on the sparc alias for QA reasons, although other arrangements -can be made if you will only be working with a small group of packages. -</p> - -<p> -ALPHA: Maintainers may keyword their own packages but are reminded to inform -the Alpha team if they can help out with testing and keywording packages so -the team can keep an eye out for possible keywording mistakes. -</p> - -<p> -Exotic architectures (like alpha, ia64, sparc, hppa, ppc*) are short on manpower, so it's best if you avoid opening stabilization bugs for them unless it is absolutely necessary (eg, a reverse dependency for your package). More about keywording policies can be found in the <uri link="::keywording">keywording</uri> section. -</p> -<p> -Some architectures (like m68k, mips, s390, sh) do not maintain a stable keyword. So there is no use in marking a package stable for one of these architectures. -</p> -</body> -</section> - -<section> -<title>Upgrading ebuilds</title> -<body> - -<p> -New ebuilds should rarely go in with "<c>arch</c>" keywords and even if they do -not, the package <e>must</e> be tested on any architectures listed in the -<c>KEYWORDS</c> variable of the new ebuild. -</p> - -<p> -Exceptions to the no "<c>arch</c>" rule are major bug fixes, or -security fixes. If the previous version of the ebuild -contains <c>KEYWORDS</c> which you cannot test for, you should -downgrade them: turn any "<c>arch</c>" keyword to "<c>~arch</c>". If you -think that your package may not work at all even on "<c>~arch</c>" -then it is best to leave the keyword out and request testing from the -relevant team: if you are to do this, you must file a bug to the team -in question. -</p> - -<p> -If a new version introduces new dependencies which are not available -on some architectures, then you should file a bug or ask on IRC before -you upgrade the package. If you really need to get the ebuild added in -a hurry, for example, for a security fix, then you should drop -any <c>KEYWORDS</c> which are causing problems and CC the relevant -architectures on the bug - you should file a new bug to the -architecture in question regarding this if no bug is already -available. -</p> - -<p> -If there are no new dependencies, do not remove keywords if your -commit fails with repoman - please try a full <c>cvs update</c> and if -you still have problems, then commit with <c>repoman -I</c> and file a -bug to the broken architecture, noting it in your CVS commit message. -</p> - -<warn> -When committing, make sure that you reference any bugs in the -ChangeLog as well as the CVS message. Failing to do so is considered -to be in very poor taste and may result in disciplinary action. -</warn> - -</body> -</section> - -<section> -<title>Moving ebuilds</title> -<body> - -<p> -Moving ebuilds is a two-step process: -</p> - -<p> -Firstly, you need to move the ebuild in CVS. To do this, you should -copy the ebuild to its new location and commit that as you would with -a <uri link="#adding-a-new-ebuild">new ebuild</uri>. -</p> - -<p> -After this, you should change any ebuilds which <c>DEPEND</c> on the -old ebuild to depend on the new one. After this, should add an entry to the -latest file in <path>profiles/updates/</path> in the Portage tree in the in -the following format: -</p> - -<pre caption="Adding an entry to updates"> -move net-misc/fwbuilder net-firewall/fwbuilder -</pre> - -<p> -This example would transparently move <path>net-misc/fwbuilder</path> to -<path>net-firewall/fwbuilder</path> if users have it installed. This -way, users would now automatically receive updates -for <path>net-firewall/fwbuilder</path> when they are available. -</p> - -<p> -Once this step is concluded, you are allowed to remove the old package. -Simply issue a <c>cvs remove -Rf $PN</c> in the package category and commit -the changes afterwards with a meaningful commit message. Don't forget to update -entries in files such as profiles/package.mask to reflect the new category. Finally -remember to change the title to open bugs related to this package if needed. -</p> - -<pre caption="Removing a package"> -net-misc # cvs rm -Rf fwbuilder -cvs remove: use `cvs commit' to remove these files permanently -net-misc # cvs ci -m "Moving net-misc/fwbuilder to net-firewall/fwbuilder." -</pre> - -<note> -CVS cannot destroy directories: it will simply not re-create them if -they are blank, providing you use CVS with the <c>-P</c> flag. -</note> - -</body> -</section> - -<section> -<title>Changing ebuild's SLOT</title> -<body> -<p> -The process for changing the ebuild's SLOT is very similar to the previous process. -Besides changing the SLOT in the ebuild file, you also need to create a new entry -in <path>profiles/updates/</path> in the Portage tree in the following format: -</p> - -<pre caption="Adding an entry to updates"> -slotmove app-text/gtkspell 0 2 -</pre> - -<p>Make sure that you have fixed all the reverse dependencies and that you have -updated every file in <path>profiles/</path> directory that happens to contain an -entry which may be affected by your change. -</p> - -</body> -</section> - -<section> -<title>Removing ebuilds</title> -<body> - -<p> -When removing an ebuild make sure that no dependencies in Portage are broken -due to the removal - additionally, your CVS commit message should explain -clearly why the ebuild is being removed from CVS. -</p> - -<p> -If you need to remove ebuilds, make sure you do not accidentally remove -the newest/only stable ebuild for any architecture. If you would like to -get a newer version marked stable, then please file a bug or ask on IRC. -</p> - -<p> -You should also not cause an unnecessary downgrade for any "<c>~arch</c>" -when removing ebuilds - instead, it is best to get the newest version -marked "<c>~arch</c>" first and then remove redundant versions of the ebuild. -</p> - -</body> -</section> - -<section> -<title>Removing a package</title> -<body> - -<p> -When removing packages follow these steps: -</p> - -<ol> - <li>Make sure that no dependencies in Portage are broken due to the removal</li> - <li>Send last rites to gentoo-dev-announce and gentoo-dev</li> - <li>Mask the package</li> - <li>Wait 30 days (or more)</li> - <li>Remove from CVS unless the reason for removal has been fixed</li> - <li>Remove package.mask entry</li> - <li>Close open bugs as WONTFIX</li> -</ol> - -<p> -In order to remove a package completely from CVS, delete any files from the -directory and commit this, CVS will take care of removing empty directories -itself. -</p> - -<pre caption="Removing a package from CVS"><comment>#</comment> <keyword>cd</keyword> app-admin -<comment>#</comment> <keyword>cvs</keyword> rm -Rf scotty -<comment>#</comment> <keyword>cvs</keyword> ci -m "app-admin/scotty removal (pending 21st July 2006), see #77501 for reference." scotty</pre> - -</body> -</section> - -<section> -<title>Conflicting files</title> -<body> - -<p> -When you encounter a package that is trying to install files that are -already provided by another package (detectable with -<c>FEATURES=collision-protect</c> for example) you have to fix this -situation before you can commit the ebuild or, if you encounter this -with an existing package, file a bug about that package (see below for -a few exceptions). The reason file conflicts are critical is because -if "foo" provides the file <path>/usr/bin/example</path> and "bar" is -going to overwrite it, and later "bar" is unmerged, Portage will remove -<path>/usr/bin/example</path> and it is therefore likely it will break -"foo". -</p> - -<p> -The most obvious fix is to add a blocking dependency to both packages -that want to install that file, so they can't be installed at the same -time. But unless there are also other reasons for those packages to -block each other you should avoid this if possible and rather fix the -package, which could include one or more of the following steps: -</p> - -<ul> - <li>Make "foo" (R)DEPEND on "bar" and not install the conflicting - file.</li> - <li>Remove conflicting files from "foo" in <c>src_install</c> - or <c>pkg_preinst</c>.</li> - <li>Move conflicting files into a new subpackage and make "foo" and - "bar" both (R)DEPEND on that package.</li> - <li>Change the location where "foo" or "bar" installs conflicting - files.</li> -</ul> - -<p> -In some cases conflicting files can't be really fixed or aren't -critical, currently known exceptions are Perl module manpages -(overwriting the ones from Perl itself) and <c>CONFIG_PROTECT</c>'ed -files (which should still be fixed, but aren't critical as Portage -won't overwrite them). -</p> - -</body> -</section> - -<section> -<title>Homepage unavailable</title> -<body> - -<p> -If the <c>HOMEPAGE</c> of your package seems to be unavailable or it -never existed at all, please set the HOMEPAGE variable in every ebuild -to <uri link="https://wiki.gentoo.org/wiki/No_homepage"> -https://wiki.gentoo.org/wiki/No_homepage</uri> -</p> - -</body> -</section> - -</body> -</chapter> -</guide> diff --git a/ebuild-writing/error-handling/text.xml b/ebuild-writing/error-handling/text.xml index 40b8b5b..28dca4e 100644 --- a/ebuild-writing/error-handling/text.xml +++ b/ebuild-writing/error-handling/text.xml @@ -1,10 +1,10 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/error-handling/"> <chapter> -<title>Error Handling</title> +<title>Error handling</title> <section> -<title>Importance of Error Handling</title> +<title>Importance of error handling</title> <body> <p> @@ -13,7 +13,7 @@ Decent error handling is important because: <ul> <li> - Errors must be detected <e>before</e> portage tries to install a broken or + Errors must be detected <e>before</e> Portage tries to install a broken or incomplete package onto the live filesystem. If build failures aren't caught, a working package could be unmerged and replaced with nothing. </li> @@ -32,7 +32,7 @@ Decent error handling is important because: </section> <section> -<title>The <c>die</c> Function</title> +<title>The <c>die</c> function</title> <body> <p> @@ -47,30 +47,29 @@ function can die in multiple places. </p> <p> -Some portage-provided functions will automatically die upon failure. Others will -not. It is for example safe to omit the <c>|| die</c> after a call to <c>epatch</c>, -but not <c>emake</c>. The reason is that external binaries are not able to call -die that is a bash function. You can see what commands are external binaries -with <c>ls /usr/lib*/portage/bin/ebuild-helpers</c>. In <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri> all ebuild-helpers automatically die upon failure. +Ebuild helpers automatically die on failure. Some eclass-provided functions +will automatically die upon failure, others will not. Developers should check +the <uri link="::eclass-reference/">eclass reference</uri> when in doubt. </p> <p> Sometimes displaying additional error information beforehand can be useful. Use -<c>eerror</c> to do this. See <uri link="::ebuild-writing/messages"/>. +<c>eerror</c> to do this. See <uri link="::ebuild-writing/messages/"/>. </p> -<p> -It's best to use <c>|| die</c> too often than too little. -</p> +<note> +You should use <c>die</c> on almost all external commands in ebuilds. +</note> + </body> </section> <section> -<title><c>die</c> and Subshells</title> +<title><c>die</c> and subshells</title> <body> <warning> -<c>die</c> <b>will not work in a subshell</b>. +<c>die</c> <b>will not work in a subshell unless you are using EAPI=7 and onwards</b>. </warning> <p> @@ -88,7 +87,7 @@ The correct way to rewrite this is to use an <c>if</c> block: <codesample lang="ebuild"> if [[ -f foorc ]] ; then - update_foorc || die "Couldn't update foorc!" + update_foorc || die "Couldn't update foorc!" fi </codesample> @@ -97,7 +96,7 @@ When using pipes, a subshell is introduced, so the following is unsafe: </p> <codesample lang="ebuild"> -cat list | while read file ; do epatch ${file} ; done +cat list | while read file ; do eapply ${file} ; done </codesample> <p> @@ -106,20 +105,20 @@ avoids this problem: </p> <codesample lang="ebuild"> -while read file ; do epatch ${file} ; done < list +while read file ; do eapply ${file} ; done < list </codesample> </body> </section> <section> -<title>The <c>assert</c> Function and <c>$PIPESTATUS</c></title> +<title>The <c>assert</c> function and <c>$PIPESTATUS</c></title> <body> <p> When using pipes, simple conditionals and tests upon <c>$?</c> will not correctly detect errors occurring in anything except the final command in the chain. To get -around this, <c>bash</c> provides the <c>$PIPESTATUS</c> variable, and portage +around this, <c>bash</c> provides the <c>$PIPESTATUS</c> variable, and Portage provides the <c>assert</c> function to check this variable. </p> @@ -136,5 +135,30 @@ time, <c>assert</c> is enough. </body> </section> +<section> +<title>The <c>nonfatal</c> command</title> +<body> + +<p> +If a non-zero exit status from an ebuild helper function is expected, you may +call it under the <c>nonfatal</c> function. Instead of dying on failure, +the command will then return non-zero exit status, as in the following example: +</p> + +<codesample lang="ebuild"> +src_test() { + if ! nonfatal emake check ; then + local a + eerror "Tests failed. Looking for files to add to your bug report..." + while IFS='' read -r -d $'\0' a ; do + eerror " ${a}" + done < <(find "${S}" -type f -name '*.log' -print0) + die "Make check failed" + fi +} +</codesample> + +</body> +</section> </chapter> </guide> diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml index de2380a..bca3dad 100644 --- a/ebuild-writing/file-format/text.xml +++ b/ebuild-writing/file-format/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/file-format/"> <chapter> -<title>Ebuild File Format</title> +<title>Ebuild file format</title> <body> <p> @@ -11,7 +11,7 @@ Files should be simple text files with a <c>.ebuild</c> extension. </body> <section> -<title>File Naming Rules</title> +<title>File naming rules</title> <body> <p> @@ -25,22 +25,29 @@ discouraged, but technically valid. </p> <note> -This is the same as <uri link="http://www.opengroup.org/onlinepubs/000095399/basedefs/xbd_chap03.html#tag_03_276"> -IEEE1003.1-2004-3.276</uri>, with the exception of the period character and with the -addition of the plus character to keep GTK+ and friends happy. +This is the same as +<uri link="https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282"> +IEEE Std 1003.1-2017, section 3.282 (Portable Filename Character Set)</uri>, +with the exception of the period character and with the addition of the plus +character to keep GTK+ and friends happy. </note> <p> +The name must not begin with a hyphen or a plus sign, and must not end +in a hyphen followed by anything that could be mistaken for a version. +</p> + +<p> The version section is more complicated. It consists of one or more numbers separated by full stop (or period, or dot, or decimal point) characters (eg <c>1.2.3</c>, <c>20050108</c>). The final number may have a single letter following it (e.g. <c>1.2b</c>). This letter should not be used to indicate 'beta' status <d/> -portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>. +Portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>. </p> <p> There can be a suffix to version indicating the kind of release. In the following table, -what portage considers to be the 'lowest' version comes first. +what Portage considers to be the 'lowest' version comes first. </p> <table> @@ -69,18 +76,19 @@ what portage considers to be the 'lowest' version comes first. <ti>Normal release</ti> </tr> <tr> - <ti>_p</ti> + <ti><c>_p</c></ti> <ti>Patch release</ti> </tr> </table> <p> -Any of these suffixes may be followed by a non-zero positive integer. +Any of these suffixes may be followed by an unsigned integer. </p> <p> These suffixes can be chained together and will be processed iteratively. To give some examples (the following list is from lowest version to highest): +</p> <ul> <li>foo-1.0.0_alpha_pre</li> @@ -88,19 +96,19 @@ give some examples (the following list is from lowest version to highest): <li>foo-1.0.0_beta_pre</li> <li>foo-1.0.0_beta_p1</li> </ul> -</p> <p> No integer part of the version may be longer than 18 digits. </p> <p> -Finally, version may have a Gentoo revision number in the form <c>-r1</c>. The initial -Gentoo version should have no revision suffix, the first revision should be -<c>-r1</c>, the second <c>-r2</c> and so on. See <uri link="::general-concepts/ebuild-revisions"/>. -Revision numbers are distinguished from patch releases by revision bumps being -changes by Gentoo developers, while patch releases are new releases by upstream (with the exception -of snapshots, see below). +Finally, version may have a Gentoo revision number in the form <c>-r1</c>. +The initial Gentoo version should have no revision suffix, the first revision +should be <c>-r1</c>, the second <c>-r2</c> and so on. +See <uri link="::general-concepts/ebuild-revisions/"/>. Revision numbers are +distinguished from patch releases by revision bumps being changes by Gentoo +developers, while patch releases are new releases by upstream (with the +exception of snapshots, see below). </p> <p> @@ -108,38 +116,96 @@ Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>. </p> <p> -When packaging a snapshot of a source repository, there are two commonly used formats. The first -treats the snapshot as a patch to the previous version, and so the ebuild version is in the format -$(last-released-version)_pYYYYMMDD. Alternatively, the snapshot may be treated as a pre-release to -an upcoming version, usually used when a release is anticipated but not out yet. The format for this -is $(upcoming-version)_preYYYYMMDD. +The <uri link ="::ebuild-writing/variables/#Version and name formatting issues"> +EAPI 7 version commands</uri> may be used to manipulate and extract +ebuild version components. +</p> + +<p> +The formal specification of version +<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-250003.2"> +format</uri> and the comparison +<uri link="https://projects.gentoo.org/pms/8/pms.html#x1-260003.3"> +algorithm</uri> can be found in PMS. </p> </body> + +<subsection> +<title>Snapshots and live ebuilds</title> +<body> + +<p> +When packaging a snapshot of a source repository, there are two commonly used +formats. The first treats the snapshot as a patch to the previous version, and +so the ebuild version is in the format $(last-released-version)_pYYYYMMDD. +Alternatively, the snapshot may be treated as a pre-release to an upcoming +version, usually used when a release is anticipated but not out yet. The format +for this is $(upcoming-version)_preYYYYMMDD. +</p> + +<p> +The policy for so-called <e>live</e> ebuilds +(see <uri link="::ebuild-writing/functions/src_unpack/#src_unpack actions"/>) +is to use <c>9999</c> as the version (or as the last version component). For +packages with more than 4 digits e.g. YYYYMMDD format, <c>99999999</c> is an +acceptable alternative. +</p> + +</body> +</subsection> + +<subsection> +<title>Binary packages</title> +<body> + +<p> +Gentoo usually builds its packages from source. Exceptionally, a binary package +can be provided instead (e.g., if upstream does not provide a source). +Such packages should still follow normal naming conventions and do not need any +special suffix. +</p> + +<p> +If a binary package is provided in addition to its open-source based +equivalent, the name of the former should be suffixed with <c>-bin</c> +if necessary for distinction. Examples are packages that are heavy on resources +like CPU time or memory when being built from source. +</p> + +</body> +</subsection> </section> <section> -<title>Ebuild Header</title> +<title>Ebuild header</title> <body> <p> -All ebuilds committed to the tree should have a three line header immediately at -the start indicating copyright. This must be an exact copy of the contents of -<c>$(portageq portdir)/header.txt</c>. Ensure that the <c>$Header: $</c> line is not -modified manually <d/> CVS will handle this line specially. +All ebuilds committed to the tree should have a two line header immediately at +the start indicating copyright, followed by an empty line. This must be an +exact copy of the contents of +<c><uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/header.txt"> +header.txt</uri></c> in the top directory of the Gentoo repository. </p> <codesample lang="ebuild"> -# Copyright 1999-2006 Gentoo Foundation +# Copyright 1999-2024 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ </codesample> +<note> +The header previously included a third line with a CVS <c>$Id$</c> +or <c>$Header$</c> keyword. That line was abolished after conversion +to Git by <uri link="https://bugs.gentoo.org/611234">decision of the Gentoo +Council on 28 February 2017</uri> and <e>must not</e> be added any more. +</note> + </body> </section> <section> -<title>Indenting and Whitespace</title> +<title>Indenting and whitespace</title> <body> <p> @@ -149,9 +215,9 @@ indenting, never inside strings. </p> <p> -Avoid trailing whitespace: repoman will warn you about this if your -ebuild contains trailing or leading whitespace (whitespace instead of -tabs for indentation) when you commit. +Avoid trailing whitespace: <c>pkgcheck</c> will warn you about this if your +ebuild contains trailing or leading whitespace (whitespace instead of tabs for +indentation) when you commit. </p> <p> @@ -164,12 +230,12 @@ positions wide, and multibyte characters are just one position wide. </section> <section> -<title>Character Set</title> +<title>Character set</title> <body> <p> -All ebuilds (and eclasses, metadata files and ChangeLogs) must use the -UTF-8 character set. See <uri -link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP 31</uri> +All ebuilds (and eclasses, metadata files, etc.) must use the +UTF-8 character set. +See <uri link="https://www.gentoo.org/glep/glep-0031.html">GLEP 31</uri> for details. </p> </body> diff --git a/ebuild-writing/functions/diagram.svg b/ebuild-writing/functions/diagram.svg index 34ae53b..9547fc7 100644 --- a/ebuild-writing/functions/diagram.svg +++ b/ebuild-writing/functions/diagram.svg @@ -1,318 +1,387 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!-- Created with Inkscape (http://www.inkscape.org/) --> <svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://creativecommons.org/ns#" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" version="1.0" width="1100" height="80" - viewBox="0 100 830 80" + viewBox="-130 100 1100 80" id="svg2503"> + <metadata + id="metadata55"> + <rdf:RDF> + <cc:Work + rdf:about=""> + <dc:format>image/svg+xml</dc:format> + <dc:type + rdf:resource="http://purl.org/dc/dcmitype/StillImage" /> + <dc:title></dc:title> + </cc:Work> + </rdf:RDF> + </metadata> <defs id="defs2577" /> <desc id="desc2505">Ebuild Function Order</desc> <rect - width="1100" - height="1000" - x="-135" - y="-10" + width="1101.323" + height="85.745827" + x="-129.33987" + y="96.698219" id="background" - style="fill:#eeeeee" /> - <line - style="stroke:#000000;stroke-width:2.19613099" - id="line2593" - y2="125" - x2="372.11496" - y1="125" - x1="323.88504" /> + style="fill:#eeeeee;stroke-width:0.293003" /> <rect width="80" height="30" - x="-115" - y="110" + x="-7.6246438" + y="115.12637" id="rect2508" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="-75.000008" - y="130" + x="32.375347" + y="135.12637" id="text2510" - style="text-anchor:middle">pkg_setup</text> - <g - transform="translate(-125,0)" - id="g2599"> - <line - id="line2512" - y2="125" - x2="130" - y1="125" - x1="90" - style="stroke:#000000;stroke-width:2" /> - <line - id="line2514" - y2="120" - x2="122" - y1="125" - x1="130" - style="stroke:#000000;stroke-width:2" /> - <line - id="line2516" - y2="130" - x2="122" - y1="125" - x1="130" - style="stroke:#000000;stroke-width:2" /> - </g> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_setup</text> <rect width="80" height="30" - x="4.9999924" - y="110" + x="109.90766" + y="115.12637" id="rect2518" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="44.999992" - y="130" + x="149.90767" + y="135.12637" id="text2520" - style="text-anchor:middle">src_unpack</text> - <line - x1="373" - y1="125" - x2="365" - y2="120" - id="line2524" - style="stroke:#000000;stroke-width:2" /> - <line - x1="373" - y1="125" - x2="365" - y2="130" - id="line2526" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_unpack</text> <rect width="80" height="30" - x="373" - y="110" + x="428.4689" + y="115.12637" id="rect2528" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="413" - y="130" + x="468.4689" + y="135.12637" id="text2530" - style="text-anchor:middle">src_compile</text> - <line - x1="453" - y1="125" - x2="493" - y2="125" - id="line2532" - style="stroke:#000000;stroke-width:2" /> - <line - x1="493" - y1="125" - x2="485" - y2="120" - id="line2534" - style="stroke:#000000;stroke-width:2" /> - <line - x1="493" - y1="125" - x2="485" - y2="130" - id="line2536" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_compile</text> <path - d="M 453,125 C 466.33333,125 473,129 473,137 C 473,145.66667 479.66667,150 493,150 L 573,150 C 586.33333,150 593,145.66667 593,137 C 593,129 599.66667,125 613,125" + d="m 509.22566,130.12637 c 11.55683,0 17.33525,4 17.33525,12 0,8.66667 5.77842,13 17.33525,13 h 69.34101 c 11.55683,0 17.33525,-4.33333 17.33525,-13 0,-8 5.77842,-12 17.33525,-12" id="path2538" - style="fill:none;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> <rect width="80" height="30" - x="493" - y="110" + x="538.37067" + y="115.12637" id="rect2540" - style="fill:#ccffcc;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccffcc;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="532.99994" - y="130" + x="578.37061" + y="135.12637" id="text2542" - style="text-anchor:middle">src_test</text> - <line - x1="572.99994" - y1="125" - x2="612.99994" - y2="125" - id="line2544" - style="stroke:#000000;stroke-width:2" /> - <line - x1="612.99994" - y1="125" - x2="604.99994" - y2="120" - id="line2546" - style="stroke:#000000;stroke-width:2" /> - <line - x1="612.99994" - y1="125" - x2="604.99994" - y2="130" - id="line2548" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_test</text> + <g + id="g915"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2544" + y2="130.12637" + x2="647.90759" + y1="130.12637" + x1="619.22565" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2546" + y2="125.12637" + x2="639.90759" + y1="130.12637" + x1="647.90759" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2548" + y2="135.12637" + x2="639.90759" + y1="130.12637" + x1="647.90759" /> + </g> <rect width="80" height="30" - x="612.99994" - y="110" + x="649.09814" + y="115.12637" id="rect2550" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="652.99994" - y="130" + x="687.09814" + y="135.12637" id="text2552" - style="text-anchor:middle">src_install</text> - <line - x1="692.99994" - y1="125" - x2="732.99994" - y2="125" - id="line2554" - style="stroke:#000000;stroke-width:2" /> - <line - x1="732.99994" - y1="125" - x2="724.99994" - y2="120" - id="line2556" - style="stroke:#000000;stroke-width:2" /> - <line - x1="732.99994" - y1="125" - x2="724.99994" - y2="130" - id="line2558" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_install</text> + <g + id="g920"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2554" + y2="130.12637" + x2="767.09814" + y1="130.12637" + x1="729.9978" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2556" + y2="125.12637" + x2="759.09814" + y1="130.12637" + x1="767.09814" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2558" + y2="135.12637" + x2="759.09814" + y1="130.12637" + x1="767.09814" /> + </g> <rect width="80" height="30" - x="732.99994" - y="110" + x="767.90759" + y="115.12637" id="rect2560" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="772.99994" - y="130" + x="807.90759" + y="135.12637" id="text2562" - style="text-anchor:middle">pkg_preinst</text> - <line - x1="812.99994" - y1="125" - x2="852.99994" - y2="125" - id="line2564" - style="stroke:#000000;stroke-width:2" /> - <line - x1="852.99994" - y1="125" - x2="844.99994" - y2="120" - id="line2566" - style="stroke:#000000;stroke-width:2" /> - <line - x1="852.99994" - y1="125" - x2="844.99994" - y2="130" - id="line2568" - style="stroke:#000000;stroke-width:2" /> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_preinst</text> + <g + id="g925"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line2564" + y2="130.12637" + x2="873.90759" + y1="130.12637" + x1="848.47461" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2566" + y2="125.12637" + x2="865.90759" + y1="130.12637" + x1="873.90759" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2568" + y2="135.12637" + x2="865.90759" + y1="130.12637" + x1="873.90759" /> + </g> <rect width="80" height="30" - x="852.99994" - y="110" + x="873.90759" + y="115.12637" id="rect2570" - style="fill:#ccccff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="892.99994" - y="130" + x="913.90759" + y="135.12637" id="text2572" - style="text-anchor:middle">pkg_postinst</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_postinst</text> <path - d="M -34.79404,125.20597 C -15.171638,125.20597 -5.3604277,130.80594 -5.3604277,142.00588 C -5.3604277,153.86465 4.4507723,159.79403 24.073182,159.79403 L 671.61258,159.79403 C 691.23498,159.79403 701.04619,153.86465 701.04619,142.00588 C 701.04619,130.80594 710.85739,125.20597 730.4798,125.20597" + d="m 71.583477,130.33234 c 17.871085,0 26.806636,5.59997 26.806636,16.79991 0,11.85877 8.935547,17.78815 26.806617,17.78815 h 589.74589 c 17.87109,0 26.80666,-5.92938 26.80666,-17.78815 0,-11.19994 8.93553,-16.79991 26.80662,-16.79991" id="path2574" - style="fill:none;stroke:#000000;stroke-width:2.41193652" /> + style="opacity:1;fill:none;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> <rect width="80" height="30" - x="245" - y="110" + x="322.2374" + y="115.12637" id="rect2583" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="286.13922" - y="129.99992" + x="363.37662" + y="135.12637" id="text2585" - style="text-anchor:middle">src_configure</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_configure</text> <rect width="80" height="30" - x="125" - y="110" + x="215.93536" + y="115.12637" id="rect2587" - style="fill:#ffffff;stroke:#000000;stroke-width:2" /> + style="opacity:1;fill:#ffffff;stroke:#000000;stroke-width:2;stop-opacity:1" /> <text - x="167.51736" - y="129.99992" + x="258.45276" + y="135.12637" id="text2589" - style="text-anchor:middle">src_prepare</text> + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">src_prepare</text> + <rect + style="opacity:1;fill:#ccccff;stroke:#000000;stroke-width:2;stop-opacity:1" + id="rect880" + y="115.0796" + x="-113.90761" + height="30" + width="80" /> + <text + x="-73.904678" + y="135.12637" + id="text890" + style="text-anchor:middle;opacity:1;stop-opacity:1;-inkscape-font-specification:'Open Sans';font-family:'Open Sans';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;">pkg_pretend</text> <g - transform="translate(-5.0000077,0)" - id="g2604"> + id="g910"> <line - x1="90" - y1="125" - x2="130" - y2="125" - id="line2606" - style="stroke:#000000;stroke-width:2" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2534" + y2="125.12637" + x2="529.90765" + y1="130.12637" + x1="537.90765" /> <line - x1="130" - y1="125" - x2="122" - y2="120" - id="line2608" - style="stroke:#000000;stroke-width:2" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2536" + y2="135.12637" + x2="529.90765" + y1="130.12637" + x1="537.90765" /> <line - x1="130" - y1="125" - x2="122" - y2="130" - id="line2610" - style="stroke:#000000;stroke-width:2" /> + x1="512.47461" + y1="130.12637" + x2="537.90759" + y2="130.12637" + id="line890" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + <line + x1="509.22568" + y1="130.12637" + x2="537.90759" + y2="130.12637" + id="line894" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> </g> <g - transform="translate(115,0)" - id="g2612"> + id="g904"> <line - style="stroke:#000000;stroke-width:2" - id="line2614" - y2="125" - x2="130" - y1="125" - x1="90" /> + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2524" + y2="125.12637" + x2="420.4689" + y1="130.12637" + x1="428.4689" /> <line - style="stroke:#000000;stroke-width:2" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line2526" + y2="135.12637" + x2="420.4689" + y1="130.12637" + x1="428.4689" /> + <line + x1="403.03592" + y1="130.12637" + x2="428.4689" + y2="130.12637" + id="line902" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + </g> + <g + id="g899"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" id="line2616" - y2="120" - x2="122" - y1="125" - x1="130" /> + y2="125.12637" + x2="314.2374" + y1="130.12637" + x1="322.2374" /> <line - style="stroke:#000000;stroke-width:2" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" id="line2618" - y2="130" - x2="122" - y1="125" - x1="130" /> + y2="135.12637" + x2="314.2374" + y1="130.12637" + x1="322.2374" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line904" + y2="130.12637" + x2="322.2374" + y1="130.12637" + x1="296.80441" /> + </g> + <g + id="g894"> + <line + x1="215.93535" + y1="130.12637" + x2="207.93535" + y2="125.12637" + id="line2608" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="215.93535" + y1="130.12637" + x2="207.93535" + y2="135.12637" + id="line2610" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="190.50237" + y1="130.12637" + x2="215.93535" + y2="130.12637" + id="line906" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> + </g> + <g + id="g884"> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line884" + y2="125.12637" + x2="-15.624653" + y1="130.12637" + x1="-7.6246533" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" + id="line886" + y2="135.12637" + x2="-15.624653" + y1="130.12637" + x1="-7.6246533" /> + <line + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" + id="line916" + y2="130.12637" + x2="-7.6246533" + y1="130.12637" + x1="-33.057636" /> + </g> + <g + id="g889"> + <line + id="line2514" + y2="125.12637" + x2="101.90767" + y1="130.12637" + x1="109.90767" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + id="line2516" + y2="135.12637" + x2="101.90767" + y1="130.12637" + x1="109.90767" + style="opacity:1;stroke:#000000;stroke-width:2;stop-opacity:1" /> + <line + x1="72.807327" + y1="130.12637" + x2="109.90767" + y2="130.12637" + id="line920" + style="opacity:1;stroke:#000000;stroke-width:2;stroke-miterlimit:4;stroke-dasharray:none;stop-opacity:1" /> </g> </svg> diff --git a/ebuild-writing/functions/pkg_config/text.xml b/ebuild-writing/functions/pkg_config/text.xml index 422089f..6446777 100644 --- a/ebuild-writing/functions/pkg_config/text.xml +++ b/ebuild-writing/functions/pkg_config/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_config/"> <chapter> <title>pkg_config</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_config</c></title> <body> <codesample lang="ebuild"> -pkg_config() -{ - eerror "This ebuild does not have a config function." +pkg_config() { + eerror "This ebuild does not have a config function." } </codesample> </body> @@ -49,18 +48,18 @@ Taken from the <c>mysql</c> ebuilds. Note the use of <c>${ROOT}</c>. <codesample lang="ebuild"> pkg_config() { - if [ ! -d "${ROOT}"/var/lib/mysql/mysql ] ; then - einfo "Press ENTER to create the mysql database and set proper" - einfo "permissions on it, or Control-C to abort now..." - read - "${ROOT}"/usr/bin/mysql_install_db - else - einfo "Hmm, it appears as though you already have the mysql" - einfo "database in place. If you are having problems trying" - einfo "to start mysqld, perhaps you need to manually run" - einfo "/usr/bin/mysql_install_db and/or check your config" - einfo "file(s) and/or database(s) and/or logfile(s)." - fi + if [[ ! -d ${ROOT}/var/lib/mysql/mysql ]] ; then + einfo "Press ENTER to create the mysql database and set proper" + einfo "permissions on it, or Control-C to abort now..." + read + "${ROOT}"/usr/bin/mysql_install_db + else + einfo "Hmm, it appears as though you already have the mysql" + einfo "database in place. If you are having problems trying" + einfo "to start mysqld, perhaps you need to manually run" + einfo "/usr/bin/mysql_install_db and/or check your config" + einfo "file(s) and/or database(s) and/or logfile(s)." + fi } </codesample> </body> diff --git a/ebuild-writing/functions/pkg_info/text.xml b/ebuild-writing/functions/pkg_info/text.xml index 44f3c77..2e6607b 100644 --- a/ebuild-writing/functions/pkg_info/text.xml +++ b/ebuild-writing/functions/pkg_info/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_info/"> <chapter> <title>pkg_info</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_info</c></title> <body> <codesample lang="ebuild"> -pkg_info() -{ - return +pkg_info() { + return } </codesample> </body> @@ -54,15 +53,19 @@ pkg_info() { <section> <title>Notes on <c>pkg_info</c></title> <body> + +<p> +This phase will be called when a package manager displays information about +a package. +</p> + <p> -this phase will be called when a package manager displays -information about a package. -within EAPI=4, this phase can also be called for non-installed -packages. +The <c>pkg_info</c> function may also be called by the package manager for +non-installed packages. Ebuild writers should note that dependencies may not be +available. </p> + </body> </section> - </chapter> </guide> - diff --git a/ebuild-writing/functions/pkg_nofetch/text.xml b/ebuild-writing/functions/pkg_nofetch/text.xml index f360607..292c447 100644 --- a/ebuild-writing/functions/pkg_nofetch/text.xml +++ b/ebuild-writing/functions/pkg_nofetch/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_nofetch/"> <chapter> <title>pkg_nofetch</title> @@ -32,15 +32,14 @@ <title>Default <c>pkg_nofetch</c></title> <body> <codesample lang="ebuild"> -pkg_nofetch() -{ - [ -z "${SRC_URI}" ] && return +pkg_nofetch() { + [[ -z ${A} ]] && return - echo "!!! The following are listed in SRC_URI for ${PN}:" - for MYFILE in `echo ${SRC_URI}`; do - echo "!!! $MYFILE" - done - return + elog "The following files cannot be fetched for ${PN}:" + local x + for x in ${A}; do + elog " ${x}" + done } </codesample> </body> @@ -51,12 +50,16 @@ pkg_nofetch() <body> <codesample lang="ebuild"> pkg_nofetch() { - einfo "Please download" - einfo " - ${P}-main.tar.bz2" - einfo " - ${P}-extras.tar.bz2" - einfo "from ${HOMEPAGE} and place them in ${DISTDIR}" + einfo "Please download" + einfo " - ${P}-main.tar.bz2" + einfo " - ${P}-extras.tar.bz2" + einfo "from ${HOMEPAGE} and place them in your DISTDIR directory." } </codesample> +<note> +The <c>DISTDIR</c> variable is not valid in <c>pkg_*</c> phases, so it must not +be referenced. +</note> </body> </section> @@ -64,8 +67,8 @@ pkg_nofetch() { <title>Notes on <c>pkg_nofetch</c></title> <body> <p> -This function is only triggered for packages which -have <c>RESTRICT="fetch"</c> (see <uri link="::general-concepts/mirrors#Restricting Automatic Mirroring"/>) +This function is only triggered for packages which have <c>RESTRICT="fetch"</c> +(see <uri link="::general-concepts/mirrors/#Restricting automatic mirroring"/>) set, and only if one or more components listed in <c>SRC_URI</c> are not already available in the <c>distfiles</c> directory. </p> diff --git a/ebuild-writing/functions/pkg_postinst/text.xml b/ebuild-writing/functions/pkg_postinst/text.xml index 8b86c4c..7a160a5 100644 --- a/ebuild-writing/functions/pkg_postinst/text.xml +++ b/ebuild-writing/functions/pkg_postinst/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_postinst/"> <chapter> <title>pkg_postinst</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_postinst</c></title> <body> <codesample lang="ebuild"> -pkg_postinst() -{ - return +pkg_postinst() { + return } </codesample> </body> @@ -45,21 +44,21 @@ pkg_postinst() <body> <codesample lang="ebuild"> pkg_postinst() { - if $OLD_FLUXBOX_VERSION ; then - ewarn "You must restart fluxbox before using the [include] /directory/" - ewarn "feature if you are upgrading from an older fluxbox!" - ewarn " " - fi - elog "If you experience font problems, or if fluxbox takes a very" - elog "long time to start up, please try the 'disablexmb' USE flag." - elog "If that fails, please report bugs upstream." + if ${OLD_FLUXBOX_VERSION} ; then + ewarn "You must restart fluxbox before using the [include] /directory/" + ewarn "feature if you are upgrading from an older fluxbox!" + ewarn " " + fi + elog "If you experience font problems, or if fluxbox takes a very" + elog "long time to start up, please try the 'disablexmb' USE flag." + elog "If that fails, please report bugs upstream." } </codesample> </body> </section> <section> -<title>Common <c>pkg_postinst</c> Tasks</title> +<title>Common <c>pkg_postinst</c> tasks</title> <body> <p> The most common use for <c>pkg_postinst</c> is to display post-install diff --git a/ebuild-writing/functions/pkg_postrm/text.xml b/ebuild-writing/functions/pkg_postrm/text.xml index fa2a21d..6607b37 100644 --- a/ebuild-writing/functions/pkg_postrm/text.xml +++ b/ebuild-writing/functions/pkg_postrm/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_postrm/"> <chapter> <title>pkg_postrm</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> -pkg_postrm() -{ - return +pkg_postrm() { + return } </codesample> </body> @@ -44,15 +43,18 @@ pkg_postrm() <title>Sample <c>pkg_postrm</c></title> <body> <codesample lang="ebuild"> +inherit xdg-utils + pkg_postrm() { - fdo-mime_mime_database_update + xdg_desktop_database_update + xdg_mimeinfo_database_update } </codesample> </body> </section> <section> -<title>Common <c>pkg_postrm</c> Tasks</title> +<title>Common <c>pkg_postrm</c> tasks</title> <body> <p> <c>pkg_postrm</c> is is used to update symlinks, cache files and other diff --git a/ebuild-writing/functions/pkg_preinst/text.xml b/ebuild-writing/functions/pkg_preinst/text.xml index 9cdeb4a..cb3a9ab 100644 --- a/ebuild-writing/functions/pkg_preinst/text.xml +++ b/ebuild-writing/functions/pkg_preinst/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_preinst/"> <chapter> <title>pkg_preinst</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_preinst</c></title> <body> <codesample lang="ebuild"> -pkg_preinst() -{ - return +pkg_preinst() { + return } </codesample> </body> @@ -45,15 +44,15 @@ pkg_preinst() <body> <codesample lang="ebuild"> pkg_preinst() { - enewgroup foo - enewuser foo -1 /bin/false /dev/null foo + enewgroup foo + enewuser foo -1 /bin/false /dev/null foo } </codesample> </body> </section> <section> -<title>Common <c>pkg_preinst</c> Tasks</title> +<title>Common <c>pkg_preinst</c> tasks</title> <body> <p> There are a few things that are often done in <c>pkg_preinst</c>: @@ -63,7 +62,7 @@ There are a few things that are often done in <c>pkg_preinst</c>: <li> Adding users and groups. However, since <c>pkg_preinst</c> may be called after <c>src_compile</c>, <c>pkg_setup</c> is the more suitable location for - user creation <d/> see <uri link="::ebuild-writing/users-and-groups"/>. + user creation <d/> see <uri link="::ebuild-writing/users-and-groups/"/>. </li> <li> Modifying the install image for a particular system. This function @@ -72,9 +71,9 @@ There are a few things that are often done in <c>pkg_preinst</c>: configuration file updating <d/> a <c>pkg_preinst</c> could check a configuration file in <c>${ROOT}/etc/</c> and create a smart updated version in <c>${D}/etc/</c> (see - <uri link="::general-concepts/install-destinations"/>) rather than + <uri link="::general-concepts/install-destinations/"/>) rather than always trying to install the default configuration file (remember - <uri link="::general-concepts/config-protect"/>). + <uri link="::general-concepts/config-protect/"/>). </li> </ul> </body> diff --git a/ebuild-writing/functions/pkg_prerm/text.xml b/ebuild-writing/functions/pkg_prerm/text.xml index d9f8a6f..9ce88f4 100644 --- a/ebuild-writing/functions/pkg_prerm/text.xml +++ b/ebuild-writing/functions/pkg_prerm/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_prerm/"> <chapter> <title>pkg_prerm</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_prerm</c></title> <body> <codesample lang="ebuild"> -pkg_prerm() -{ - return +pkg_prerm() { + return } </codesample> </body> @@ -45,15 +44,15 @@ pkg_prerm() <body> <codesample lang="ebuild"> pkg_prerm() { - # clean up temp files - [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" + # clean up temp files + [[ -d "${ROOT}/var/tmp/foo" ]] && rm -rf "${ROOT}/var/tmp/foo" } </codesample> </body> </section> <section> -<title>Common <c>pkg_prerm</c> Tasks</title> +<title>Common <c>pkg_prerm</c> tasks</title> <body> <p> <c>pkg_prerm</c> is used to clean up any files that would otherwise prevent diff --git a/ebuild-writing/functions/pkg_pretend/text.xml b/ebuild-writing/functions/pkg_pretend/text.xml index 0279145..a838757 100644 --- a/ebuild-writing/functions/pkg_pretend/text.xml +++ b/ebuild-writing/functions/pkg_pretend/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_pretend/"> <chapter> <title>pkg_pretend</title> @@ -23,11 +23,11 @@ </tr> <tr> <th>Called for</th> - <ti>ebuild</ti> + <ti>ebuild, binary</ti> </tr> <tr> <th>EAPI</th> - <ti>3</ti> + <ti>4</ti> </tr> </table> </body> @@ -36,9 +36,8 @@ <title>Default <c>pkg_pretend</c></title> <body> <codesample lang="ebuild"> -pkg_pretend() -{ - return +pkg_pretend() { + return } </codesample> </body> @@ -67,12 +66,13 @@ pkg_pretend() { <title>Notes on <c>pkg_pretend</c></title> <body> <p> -the <c>pkg_pretend</c> phase can be used to do sanity checks +The <c>pkg_pretend</c> phase can be used to do sanity checks before the main phase function sequence is run (meaning this phase is executed after the package manager has calculated the dependencies and before installing them). This phase typically checks for a kernel configuration and may <c>eerror</c> and <c>die</c> when needed. +</p> <important> There is no guarantee that the ebuild's dependencies are installed when this phase is called. @@ -81,7 +81,6 @@ This phase typically checks for a kernel configuration and may As <c>pkg_pretend</c> is not called in the main phase function sequence, environment saving is not guaranteed. </important> -</p> </body> </section> diff --git a/ebuild-writing/functions/pkg_setup/text.xml b/ebuild-writing/functions/pkg_setup/text.xml index a7fe9d2..90f89cf 100644 --- a/ebuild-writing/functions/pkg_setup/text.xml +++ b/ebuild-writing/functions/pkg_setup/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/pkg_setup/"> <chapter> <title>pkg_setup</title> @@ -32,9 +32,8 @@ <title>Default <c>pkg_setup</c></title> <body> <codesample lang="ebuild"> -pkg_setup() -{ - return +pkg_setup() { + return } </codesample> </body> @@ -45,19 +44,19 @@ pkg_setup() <body> <codesample lang="ebuild"> pkg_setup() { - # We need to know which GUI we're building in several - # different places, so work it out here. - if use gtk ; then - if use gtk2 ; then - export mypkg_gui="gtk2" - else - export mypkg_gui="gtk1" - fi - elif use motif then - export mypkg_gui="motif" - else - export mypkg_gui="athena" - fi + # We need to know which GUI we're building in several + # different places, so work it out here. + if use gtk ; then + if use gtk2 ; then + export mypkg_gui="gtk2" + else + export mypkg_gui="gtk1" + fi + elif use motif then + export mypkg_gui="motif" + else + export mypkg_gui="athena" + fi } </codesample> </body> diff --git a/ebuild-writing/functions/src_compile/build-environment/text.xml b/ebuild-writing/functions/src_compile/build-environment/text.xml index 8c16587..de9bea7 100644 --- a/ebuild-writing/functions/src_compile/build-environment/text.xml +++ b/ebuild-writing/functions/src_compile/build-environment/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/build-environment/"> <chapter> -<title>Configuring Build Environment</title> +<title>Configuring build environment</title> <body> <p> @@ -17,13 +17,13 @@ Except where otherwise specified, any function which operates on </note> <p> -Ebuilds must not simply ignore user CFLAGS, CXXFLAGS or LDFLAGS<d/> see -<uri link="::general-concepts/user-environment#Not Filtering Variables"/>. +Ebuilds must not simply ignore user CFLAGS, CXXFLAGS or LDFLAGS <d/> see +<uri link="::general-concepts/user-environment/#Not filtering variables"/>. </p> </body> <section> -<title>Guidelines for Flag Filtering</title> +<title>Guidelines for flag filtering</title> <body> <p> @@ -59,7 +59,7 @@ line in the correct place. </section> <section> -<title>Simple Flag Stripping</title> +<title>Simple flag stripping</title> <body> <p> @@ -69,9 +69,9 @@ remove. </p> <codesample lang="ebuild"> - # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a - # rather icky asm function - use sparc && filter-flags -fomit-frame-pointer + # -fomit-frame-pointer leads to nasty broken code on sparc thanks to a + # rather icky asm function + use sparc && filter-flags -fomit-frame-pointer </codesample> <p> @@ -86,15 +86,15 @@ conservative set of flags. </p> <codesample lang="ebuild"> - # Our app hates screwy flags - strip-flags + # Our app hates screwy flags + strip-flags </codesample> </body> </section> <section> -<title>Flag Replacement</title> +<title>Flag replacement</title> <body> <p> @@ -104,8 +104,8 @@ is most commonly used to replace <c>-Os</c> with <c>-O2</c> </p> <codesample lang="ebuild"> - # Seems to have issues with -Os, switch to -O2 - replace-flags -Os -O2 + # Seems to have issues with -Os, switch to -O2 + replace-flags -Os -O2 </codesample> <p> @@ -116,15 +116,15 @@ the flags to be replaced. </p> <codesample lang="ebuild"> - # Can't use ultrasparc or ultrasparc3 code, drop to v9 - replace-cpu-flags ultrasparc ultrasparc3 v9 + # Can't use ultrasparc or ultrasparc3 code, drop to v9 + replace-cpu-flags ultrasparc ultrasparc3 v9 </codesample> </body> </section> <section> -<title>Adding Additional Flags</title> +<title>Adding additional flags</title> <body> <p> Sometimes it is necessary to add in additional <c>CFLAGS</c> @@ -133,15 +133,15 @@ functions can be used here. </p> <codesample lang="ebuild"> - # If we're using selinux, we need to add a -D - use selinux && append-flags "-DWITH_SELINUX" + # If we're using selinux, we need to add a -D + use selinux && append-flags "-DWITH_SELINUX" - # Secure linking needed, since we're setuid root - append-ldflags -Wl,-z,now + # Secure linking needed, since we're setuid root + append-ldflags -Wl,-z,now </codesample> <p> -See <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic.eclass</uri> for a full reference. +See <uri link="::eclass-reference/flag-o-matic.eclass/"/> for a full reference. </p> </body> </section> diff --git a/ebuild-writing/functions/src_compile/building/text.xml b/ebuild-writing/functions/src_compile/building/text.xml index bed3dd7..96aeef8 100644 --- a/ebuild-writing/functions/src_compile/building/text.xml +++ b/ebuild-writing/functions/src_compile/building/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/building/"> <chapter> -<title>Building a Package</title> +<title>Building a package</title> <body> <p> @@ -20,22 +20,32 @@ cleanly, it should be patched. <p> If patching <e>really</e> isn't an option, <c>emake -j1</c> should be -used. However, when doing this please remember that you are seriously +used. However, when doing this, please remember that you are seriously hurting build times for many non-x86 users in particular. Forcing -a <c>-j1</c> can increase build times from a few minutes to an hour on +<c>-j1</c> can increase build times from a few minutes to an hour on some MIPS and SPARC systems. </p> </body> <section> -<title>Fixing Compiler Usage</title> +<title>Fixing compiler usage</title> <body> <p> Sometimes a package will try to use a bizarre compiler, or will need to be told which compiler to use. In these situations, the <c>tc-getCC()</c> function from -<uri link="::eclass-reference/toolchain-funcs.eclass/">toolchain-funcs.eclass</uri> should be used. Other similar functions are available -<d/> these are documented in <c>man toolchain-funcs.eclass</c>. +<uri link="::eclass-reference/toolchain-funcs.eclass/"/> should be used. +Other similar functions are available <d/> these are documented in +<c>man toolchain-funcs.eclass</c>. +</p> + +<p> +Note that packages should always respect the user's <c>CC</c> preference +and must not rely on convenience symlinks such as <c>/usr/bin/cc</c> +or <c>/usr/bin/gcc</c>. A tracker <uri link="https://bugs.gentoo.org/243502"> +bug</uri> exists to document such issues. Additional documentation exists on the +<uri link="https://wiki.gentoo.org/wiki/Project:Toolchain/use_native_symlinks"> +wiki</uri>. </p> <note> @@ -46,27 +56,39 @@ It is <e>not</e> correct to use the <c>${CC}</c> variable for this purpose. Sometimes a package will not use the user's <c>${CFLAGS}</c> or <c>${LDFLAGS}</c>. This must be worked around, as sometimes these variables are used for specifying critical ABI options. In these cases, the build scripts should be modified (for -example, with <c>sed</c>) to use <c>${CFLAGS}</c> or <c>${LDFLAGS}</c> correctly. +example, with <c>sed</c> or via a patch) to use <c>${CFLAGS}</c> or +<c>${LDFLAGS}</c> correctly. </p> <codesample lang="ebuild"> inherit flag-o-matic toolchain-funcs +src_prepare() { + default + + # We have a weird Makefile to work with which ignores our + # compiler preferences. yay! + # Note the single quotes (hence the delimiter is not an issue) + sed -i -e 's:cc -O2:$(CC) $(CPPFLAGS) $(CFLAGS) $(LDFLAGS):' Makefile \ + || die "sed fix failed. Uh-oh..." +} + src_compile() { - # -Os not happy - replace-flags -Os -O2 - - # We have a weird build.sh to work with which ignores our - # compiler preferences. yay! - sed -i -e "s:cc -O2:$(tc-getCC) ${CFLAGS} ${LDFLAGS}:" build.sh \ - || die "sed fix failed. Uh-oh..." - ./build.sh || die "Build failed!" + # -Os not happy + replace-flags -Os -O2 + + emake CC="$(tc-getCC)" \ + CPPFLAGS="${CPPFLAGS}" \ + CFLAGS="${CFLAGS}" \ + LDFLAGS="${LDFLAGS}" } </codesample> <note> -When using <c>sed</c> with <c>CFLAGS</c> or <c>LDFLAGS</c>, it is not safe to use -a comma or a slash as a delimiter. The recommended character is a colon. +Try to not substitute the value with <c>sed</c> directly, but instead make the +build script use the variables. The variables may contain characters such as a +slash, a comma, or a colon, which are often used with <c>sed</c>, and this +would break its syntax. </note> <p> diff --git a/ebuild-writing/functions/src_compile/no-build-system/text.xml b/ebuild-writing/functions/src_compile/no-build-system/text.xml index 99b873a..b5d6191 100644 --- a/ebuild-writing/functions/src_compile/no-build-system/text.xml +++ b/ebuild-writing/functions/src_compile/no-build-system/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/no-build-system/"> <chapter> -<title>No Build System</title> +<title>No build system</title> <body> <p> @@ -14,7 +14,7 @@ Here's an example, from <c>app-misc/hilite</c>: <codesample lang="ebuild"> src_compile() { - $(tc-getCC) ${LDFLAGS} ${CFLAGS} -o ${PN} ${P}.c || die + $(tc-getCC) ${CFLAGS} ${CPPFLAGS} ${LDFLAGS} -o ${PN} ${P}.c || die } </codesample> @@ -25,29 +25,29 @@ broken build system that doesn't actually work: <codesample lang="ebuild"> src_compile() { - local x - for x in asclock parser symbols config - do - $(tc-getCC) \ - ${CPPFLAGS} ${CFLAGS} ${ASFLAGS} \ - -I/usr/include \ - -Dlinux \ - -D_POSIX_C_SOURCE=199309L \ - -D_POSIX_SOURCE \ - -D_XOPEN_SOURCE \ - -D_BSD_SOURCE \ - -D_SVID_SOURCE \ - -DFUNCPROTO=15 \ - -DNARROWPROTO \ - -c -o ${x}.o ${x}.c || die "compile asclock failed" - done - $(tc-getCC) \ - ${LDFLAGS} \ - -o asclock \ - asclock.o parser.o symbols.o config.o \ - -L/usr/lib \ - -L/usr/lib/X11 \ - -lXpm -lXext -lX11 || die "link asclock failed" + local x + for x in asclock parser symbols config + do + $(tc-getCC) \ + ${CPPFLAGS} ${CFLAGS} ${ASFLAGS} \ + -I"${EPREFIX}"/usr/include \ + -Dlinux \ + -D_POSIX_C_SOURCE=199309L \ + -D_POSIX_SOURCE \ + -D_XOPEN_SOURCE \ + -D_BSD_SOURCE \ + -D_SVID_SOURCE \ + -DFUNCPROTO=15 \ + -DNARROWPROTO \ + -c -o ${x}.o ${x}.c || die "compile asclock failed" + done + $(tc-getCC) \ + ${LDFLAGS} \ + -o asclock \ + asclock.o parser.o symbols.o config.o \ + -L"${EPREFIX}"/usr/lib \ + -L"${EPREFIX}"/usr/lib/X11 \ + -lXpm -lXext -lX11 || die "link asclock failed" } </codesample> diff --git a/ebuild-writing/functions/src_compile/text.xml b/ebuild-writing/functions/src_compile/text.xml index 89350cb..a74bbc2 100644 --- a/ebuild-writing/functions/src_compile/text.xml +++ b/ebuild-writing/functions/src_compile/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_compile/"> <chapter> <title>src_compile</title> @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Configure and build the package.<important>the configure parts of <c>src_compile</c> have been splitted out in EAPI=2 to <c>src_configure</c>. see <uri link="::ebuild-writing/functions/src_configure"/></important></ti> + <ti>Build the package.</ti> </tr> <tr> <th>Sandbox</th> @@ -30,75 +30,49 @@ <section> <title>Default <c>src_compile</c></title> + <body> -<subsection> -<title>with EAPI=0,1</title> -<body> -<codesample lang="ebuild"> -src_compile() { - if [ -x ./configure ]; then - econf - fi - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then - emake || die "emake failed" - fi -} -</codesample> -</body> -</subsection> -<subsection> -<title>with EAPI=2</title> -<body> +<ul> + <li> <codesample lang="ebuild"> src_compile() { - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then - emake || die "emake failed" - fi + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]]; then + emake || die "emake failed" + fi } </codesample> -</body> -</subsection> + </li> +</ul> </body> </section> <section> <title>Sample <c>src_compile</c></title> <body> -<subsection> -<title>with EAPI=0</title> -<body> + +<ul> + <li> <codesample lang="ebuild"> src_compile() { - use sparc && filter-flags -fomit-frame-pointer - append-ldflags -Wl,-z,now - - econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now - emake || die "Make failed!" + emake } </codesample> -<note> -You also need to inherit the <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> eclass in order to use the <c>append-ldflags</c> function. -</note> -</body> -</subsection> -<subsection> -<title>with EAPI=2</title> -<body> -<p> -porting the above example to EAPI=2, you won't need to define an extra -<c>src_compile</c>, as it only calls <c>emake</c> (which is the default -<c>src_compile</c> function). -</p> -</body> -</subsection> + <note> + You also need to inherit the + <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> + eclass in order to use the <c>append-ldflags</c> function. + </note> + </li> +</ul> + </body> </section> <section> -<title><c>src_compile</c> Processes</title> +<title><c>src_compile</c> processes</title> <body> <p> The following subsections cover different topics which often occur when writing @@ -112,7 +86,6 @@ The following subsections cover different topics which often occur when writing </chapter> <include href="build-environment/"/> -<!--<include href="configuring/"/>--> <include href="building/"/> <include href="no-build-system/"/> </guide> diff --git a/ebuild-writing/functions/src_configure/configuring/text.xml b/ebuild-writing/functions/src_configure/configuring/text.xml index 677334e..f7b3076 100644 --- a/ebuild-writing/functions/src_configure/configuring/text.xml +++ b/ebuild-writing/functions/src_configure/configuring/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_configure/configuring/"> <chapter> -<title>Configuring a Package</title> +<title>Configuring a package</title> <body> <p> @@ -30,18 +30,18 @@ where appropriate, be used to generate these switches. <codesample lang="ebuild"> src_configure() { - # We have optional perl, python and ruby support - econf \ - $(use_enable perl ) \ - $(use_enable python ) \ - $(use_enable ruby ) + # We have optional perl, python and ruby support + econf \ + $(use_enable perl) \ + $(use_enable python) \ + $(use_enable ruby) } src_configure() { - # Our package optional IPv6 support which uses --with rather than - # --enable / --disable + # Our package optional IPv6 support which uses --with rather than + # --enable / --disable - econf $(use_with ipv6 ) + econf $(use_with ipv6) } </codesample> @@ -54,17 +54,17 @@ argument forms: <codesample lang="ebuild"> src_configure() { - # Our package has optional perl, python and ruby support - econf \ - $(use_enable perl perlinterp ) \ - $(use_enable python pythoninterp ) \ - $(use_enable ruby rubyinterp ) + # Our package has optional perl, python and ruby support + econf \ + $(use_enable perl perlinterp) \ + $(use_enable python pythoninterp) \ + $(use_enable ruby rubyinterp) - # ... + # ... } -src_compile() { - econf $(use_with X x11 ) +src_configure() { + econf $(use_with X x11) } </codesample> @@ -74,5 +74,56 @@ form can be used. </p> </body> +<section> +<title><c>econf</c> options</title> +<body> + +<p> +<c>econf</c> is designed to work with configure scripts generated by +GNU Autoconf. It first passes the default options listed below to the configure +script, followed by any additional parameters passed to <c>econf</c>. +</p> + +<ul> + <li><c>--prefix="${EPREFIX}"/usr</c></li> + <li><c>--mandir="${EPREFIX}"/usr/share/man</c></li> + <li><c>--infodir="${EPREFIX}"/usr/share/info</c></li> + <li><c>--datadir="${EPREFIX}"/usr/share</c></li> + <li><c>--sysconfdir="${EPREFIX}"/etc</c></li> + <li><c>--localstatedir="${EPREFIX}"/var/lib</c></li> + <li> + <c>--build="${CBUILD}"</c> (only passed if <c>CBUILD</c> is non-empty) + </li> + <li><c>--host="${CHOST}"</c></li> + <li> + <c>--target="${CTARGET}"</c> (only passed if <c>CTARGET</c> is non-empty) + </li> + <li> + <c>--libdir</c> is set from the value of the <c>LIBDIR_${ABI}</c> variable + in profiles. + </li> + <li><c>--disable-dependency-tracking</c></li> + <li><c>--disable-silent-rules</c></li> +</ul> + +<p> +In EAPI 6 and later, the following options are passed in addition: +</p> + +<ul> + <li><c>--docdir="${EPREFIX}"/usr/share/doc/${PF}</c></li> + <li><c>--htmldir="${EPREFIX}"/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +In EAPI 7 and later, the following option is passed in addition: +</p> + +<ul> + <li><c>--with-sysroot="${ESYSROOT:-/}"</c></li> +</ul> + +</body> +</section> </chapter> </guide> diff --git a/ebuild-writing/functions/src_configure/text.xml b/ebuild-writing/functions/src_configure/text.xml index 0740309..50ccc42 100644 --- a/ebuild-writing/functions/src_configure/text.xml +++ b/ebuild-writing/functions/src_configure/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_configure/"> <chapter> <title>src_configure</title> @@ -38,8 +38,8 @@ <codesample lang="ebuild"> src_configure() { if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi + econf + fi } </codesample> </body> @@ -49,20 +49,29 @@ src_configure() { <title>Sample <c>src_configure</c></title> <body> <codesample lang="ebuild"> +inherit flag-o-matic + src_configure() { - use sparc && filter-flags -fomit-frame-pointer - append-ldflags -Wl,-z,now + use sparc && filter-flags -fomit-frame-pointer + append-ldflags -Wl,-z,now - econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) + econf \ + $(use_enable ssl) \ + $(use_enable perl perlinterp) } </codesample> + +<note> +You also need to inherit the +<uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> +eclass in order to use the <c>append-ldflags</c> function. +</note> + </body> </section> <section> -<title><c>src_configure</c> Processes</title> +<title><c>src_configure</c> processes</title> <body> <p> The following subsections cover different topics which often occur when writing @@ -76,8 +85,5 @@ The following subsections cover different topics which often occur when writing </chapter> <include href="configuring/"/> -<!--<include href="build-environment/"/> -<include href="building/"/> -<include href="no-build-system/"/>--> </guide> diff --git a/ebuild-writing/functions/src_install/docompress/text.xml b/ebuild-writing/functions/src_install/docompress/text.xml new file mode 100644 index 0000000..adaef2b --- /dev/null +++ b/ebuild-writing/functions/src_install/docompress/text.xml @@ -0,0 +1,51 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_install/docompress/"> +<chapter> +<title>Controllable compression</title> +<body> + +<p> +You can call the <c>docompress</c> function in <c>src_install</c> to control +which items in the destination folder <c>${D}</c> should be compressed and +which shouldn't be compressed. You can include or exclude directories or plain +files. The default inclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc</c></li> + <li><c>/usr/share/info</c></li> + <li><c>/usr/share/man</c></li> +</ul> + +<p> +The default exclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +When a directory is in- or excluded, all files and directories in the given +directories shall be added to the corresponding list. If a file is in- or +excluded, the file shall be added to the corresponding list (exclusion is +stronger than inclusion <d/> if a file is in both lists, the inclusion will +be ignored). +</p> + +<p> +If the first argument of <c>docompress</c> is <c>-x</c>, the items specified +will be added to the exclusion list, otherwise they will be added to the +inclusion list. +</p> + +<note> +When <c>docompress</c> is called, it is <e>not</e> required that the paths +specified as its arguments are pointing to existing files or directories. +However, if a file still doesn't exist when <c>src_install</c> has completed, +it will be ignored with a warning. +</note> + +</body> +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_install/text.xml b/ebuild-writing/functions/src_install/text.xml index 530baf1..85cfa6e 100644 --- a/ebuild-writing/functions/src_install/text.xml +++ b/ebuild-writing/functions/src_install/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_install/"> <chapter> <title>src_install</title> @@ -31,39 +31,41 @@ <section> <title>Default <c>src_install</c></title> <body> -<p> -For EAPIs 0,1,2, and 3, the default <c>src_install</c> function is the -following: -</p> -<codesample lang="ebuild"> -src_install() -{ - return -} -</codesample> + <p> For EAPIs 4 and later, the default <c>src_install</c> function is the following: </p> <codesample lang="ebuild"> src_install() { - if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]] ; then emake DESTDIR="${D}" install fi - if ! declare -p DOCS >/dev/null 2>&1 ; then + if ! declare -p DOCS >/dev/null 2>&1 ; then local d for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \ FAQ CREDITS CHANGELOG ; do [[ -s "${d}" ]] && dodoc "${d}" done - elif declare -p DOCS | grep -q "^declare -a " ; then + elif [[ $(declare -p DOCS) == "declare -a"* ]] ; then dodoc "${DOCS[@]}" else dodoc ${DOCS} fi } </codesample> -<important>The following examples assume EAPI 4 or later</important> +<p> +For EAPIs 6 and later, the default <c>src_install</c> function is the following: +</p> +<codesample lang="ebuild"> +src_install() { + if [[ -f Makefile ]] || [[ -f GNUmakefile ]] || [[ -f makefile ]] ; then + emake DESTDIR="${D}" install + fi + einstalldocs +} +</codesample> + </body> </section> @@ -73,8 +75,8 @@ src_install() { <codesample lang="ebuild"> src_install() { - emake DESTDIR="${D}" install - dodoc README CHANGES + emake DESTDIR="${D}" install + dodoc README CHANGES } </codesample> @@ -82,7 +84,7 @@ src_install() { </section> <section> -<title>Easy Installs</title> +<title>Easy installs</title> <body> <p> Often, especially with autotools-powered packages, there is a <c>Makefile</c> @@ -91,7 +93,7 @@ install to a non-root location. If possible, this should be used: </p> <codesample lang="ebuild"> - emake DESTDIR="${D}" install + emake DESTDIR="${D}" install </codesample> <note> @@ -101,30 +103,33 @@ if you hit an error. </note> <p> - Sometimes this will end up installing a few things into strange - places. If and only if this is the case, the <c>einstall</c> - function can be used. It is usually necessary to include additional - <c>dodoc</c> statements for the <c>README</c>, <c>ChangeLog</c>, etc - in these cases: +Usually the package's build system will not install the <c>README</c>, +<c>ChangeLog</c>, etc. files, so it is necessary to include additional +<c>dodoc</c> statements for them: </p> <codesample lang="ebuild"> - einstall - dodoc README CHANGES + emake DESTDIR="${D}" install + dodoc README CHANGES + dodoc -r doc </codesample> +<p> +<c>dodoc</c> supports <c>-r</c> as the first argument, which allows directories +to be installed recursively. +</p> + <note> -There is no need to <c>dodoc</c> <c>COPYING</c>! The license belongs -to <c>${PORTDIR}/licenses</c>. Sometimes though, you might want to -install <c>COPYING</c> regardless, if it explains how different -licenses are applied to different parts of the application, for -example. +There is no need for <c>dodoc COPYING</c>! The license belongs in the +repository's <c>licenses/</c> directory. Sometimes though, you might want to +install <c>COPYING</c> regardless, if it explains how different licenses are +applied to different parts of the application, for example. </note> </body> </section> <section> -<title>Trivial Installs</title> +<title>Trivial installs</title> <body> <p> @@ -135,64 +140,64 @@ compilation required) themes: </p> <codesample lang="ebuild"> - dodir /usr/share/foo-styles/ - cp -R "${S}/" "${D}/" || die "Install failed!" + dodir /usr/share/foo-styles/ + cp -R "${S}/" "${D}/" || die "Install failed!" </codesample> <p> Or sometimes a combination of <c>insinto</c> and <c>doins</c> (plus related -functions -- see <uri link="::function-reference/install-functions"/>) <d/> the following is based -upon the <c>sys-fs/udev</c> install: +functions <d/> see <uri link="::function-reference/install-functions/"/>) <d/> +the following is based upon the <c>sys-fs/udev</c> install: </p> <codesample lang="ebuild"> src_install() { - dobin udevinfo - dobin udevtest - into / - dosbin udev - dosbin udevd - dosbin udevsend - dosbin udevstart - dosbin extras/scsi_id/scsi_id - dosbin extras/volume_id/udev_volume_id - - exeinto /etc/udev/scripts - doexe extras/ide-devfs.sh - doexe extras/scsi-devfs.sh - doexe extras/cdsymlinks.sh - doexe extras/dvb.sh - - insinto /etc/udev - newins "${FILESDIR}/udev.conf.post_050" udev.conf - doins extras/cdsymlinks.conf - - # For devfs style layout - insinto /etc/udev/rules.d/ - newins etc/udev/gentoo/udev.rules 50-udev.rules - - # scsi_id configuration - insinto /etc - doins extras/scsi_id/scsi_id.config - - # set up symlinks in /etc/hotplug.d/default - dodir /etc/hotplug.d/default - dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug - - # set up the /etc/dev.d directory tree - dodir /etc/dev.d/default - dodir /etc/dev.d/net - exeinto /etc/dev.d/net - doexe etc/dev.d/net/hotplug.dev - - doman *.8 - doman extras/scsi_id/scsi_id.8 - - dodoc ChangeLog FAQ HOWTO-udev_for_dev README TODO - dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt} - dodoc docs/persistent_naming/* docs/writing_udev_rules/* - - newdoc extras/volume_id/README README_volume_id + dobin udevinfo + dobin udevtest + into / + dosbin udev + dosbin udevd + dosbin udevsend + dosbin udevstart + dosbin extras/scsi_id/scsi_id + dosbin extras/volume_id/udev_volume_id + + exeinto /etc/udev/scripts + doexe extras/ide-devfs.sh + doexe extras/scsi-devfs.sh + doexe extras/cdsymlinks.sh + doexe extras/dvb.sh + + insinto /etc/udev + newins "${FILESDIR}/udev.conf.post_050" udev.conf + doins extras/cdsymlinks.conf + + # For devfs style layout + insinto /etc/udev/rules.d/ + newins etc/udev/gentoo/udev.rules 50-udev.rules + + # scsi_id configuration + insinto /etc + doins extras/scsi_id/scsi_id.config + + # set up symlinks in /etc/hotplug.d/default + dodir /etc/hotplug.d/default + dosym ../../../sbin/udevsend /etc/hotplug.d/default/10-udev.hotplug + + # set up the /etc/dev.d directory tree + dodir /etc/dev.d/default + dodir /etc/dev.d/net + exeinto /etc/dev.d/net + doexe etc/dev.d/net/hotplug.dev + + doman *.8 + doman extras/scsi_id/scsi_id.8 + + dodoc ChangeLog FAQ HOWTO-udev_for_dev README TODO + dodoc docs/{overview,udev-OLS2003.pdf,udev_vs_devfs,RFC-dev.d,libsysfs.txt} + dodoc docs/persistent_naming/* docs/writing_udev_rules/* + + newdoc extras/volume_id/README README_volume_id } </codesample> @@ -204,7 +209,7 @@ simple <c>Makefile</c> driven install. </section> <section> -<title>Other Installs</title> +<title>Other installs</title> <body> <p> Sometimes, there will be a <c>Makefile</c> that does not @@ -215,5 +220,20 @@ upstream explaining the situation to them. </body> </section> +<section> +<title><c>src_install</c> processes</title> +<body> + +<p> +The following subsections cover different topics which often occur when writing +<c>src_install</c> functions. +</p> + +<contentsTree/> + +</body> +</section> </chapter> + +<include href="docompress/"/> </guide> diff --git a/ebuild-writing/functions/src_prepare/autopackage/text.xml b/ebuild-writing/functions/src_prepare/autopackage/text.xml index 56c6b47..42fb255 100644 --- a/ebuild-writing/functions/src_prepare/autopackage/text.xml +++ b/ebuild-writing/functions/src_prepare/autopackage/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_prepare/autopackage/"> <chapter> <title>Autopackage</title> diff --git a/ebuild-writing/functions/src_prepare/eapply/text.xml b/ebuild-writing/functions/src_prepare/eapply/text.xml new file mode 100644 index 0000000..97f4445 --- /dev/null +++ b/ebuild-writing/functions/src_prepare/eapply/text.xml @@ -0,0 +1,136 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_prepare/eapply/"> +<chapter> +<title>Patching with eapply</title> +<body> + +<p> +The canonical way of applying patches in ebuilds is to use the package +manager's <c>eapply</c> command, either by calling it explicitly, or by +assigning the <c>PATCHES</c> variable supported by the default +<c>src_prepare</c> implementation. +</p> + +<important> +Applying patches to the sources from the upstream tarball is <e>strongly</e> +preferred to distributing your own modified tarball. +</important> + +<p> +The <c>eapply</c> command takes one or more regular file or directory paths as +its arguments. Optionally, these can be preceded by GNU <c>patch</c> options. +</p> + +<note> +The <c>--</c> delimiter indicates the end of options. This is useful if a +filename begins with a hyphen. +</note> + +<ul> + <li> + If an argument is a regular file, it will be applied in the working + directory by calling GNU <c>patch</c> with patch level <c>-p1</c>. + Specifying an explicit <c>-p<e>N</e></c> option will override the default + patch level. + </li> + <li> + For a directory, <c>eapply</c> applies all patch files with names ending + in <c>.diff</c> or <c>.patch</c> in that directory, in POSIXbetical order + of their names. Any other files in the directory are ignored. + Again, <c>-p<e>N</e></c> can be used to override the default <c>-p1</c> + patch level. Note that <c>eapply</c> will not recurse into subdirectories. + </li> +</ul> + +<p> +<c>eapply</c> was added in EAPI 6. It differs from the previously available +<c>epatch</c> in several ways: +</p> + +<ul> + <li> + <c>eapply</c> will not unpack patches for you. + </li> + <li> + The patch level is no longer detected automatically. Patch levels other + than <c>-p1</c> must be specified manually. + </li> + <li> + When specifying a directory, at least one file with a name ending in + <c>.diff</c> or <c>.patch</c> must exist or the command fails. + </li> +</ul> +</body> + +<section> +<title>Basic <c>eapply</c></title> +<body> + +<p> +In its simplest form, <c>eapply</c> takes a single filename and applies that +patch. It will automatically <c>die</c> if the apply fails. The following is +taken from <c>sys-libs/gpm</c>: +</p> + +<codesample lang="ebuild"> + eapply "${FILESDIR}"/${P}-musl.patch +</codesample> + +<p> +In the following simplified example taken from <c>www-client/firefox</c>, +a patchset is added to <c>SRC_URI</c> in order to fetch and unpack it. +<c>eapply</c> is then called with a directory argument. It applies all patches +found in that directory: +</p> + +<codesample lang="ebuild"> +SRC_URI+="https://dev.gentoo.org/~larry/patchsets/${P}-patches-01.tar.xz" + +src_prepare() { + eapply "${WORKDIR}/firefox-patches" + eapply_user +} +</codesample> + +<p> +The <uri link="::ebuild-writing/misc-files/patches/"/> chapter gives some +guidelines about where patches should be hosted and about their formatting. +</p> + +<p> +The default <c><uri link="::ebuild-writing/functions/src_prepare"/></c> +function will look for a global PATCHES array to apply a list of patches +for you. +</p> + +<codesample lang="ebuild"> +PATCHES=( + # Fix install location + "${FILESDIR}/${P}-destdir.patch" + # Respect MAKEOPTS #876543 + "${FILESDIR}/${P}-parallel_build.patch" +) +</codesample> +</body> +</section> + +<section> +<title>Advanced <c>eapply</c></title> +<body> + +<p> +This example shows how different patch levels can be applied: +</p> + +<codesample lang="ebuild"> +src_prepare() { + eapply -p2 "${WORKDIR}/${P}-suse-update.patch" + eapply -p0 "${FILESDIR}/${PV}-no-TIOCGDEV.patch" + eapply "${FILESDIR}/${PV}-gcc-6.patch" + eapply_user +} +</codesample> +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_prepare/epatch/text.xml b/ebuild-writing/functions/src_prepare/epatch/text.xml deleted file mode 100644 index 1322a5e..0000000 --- a/ebuild-writing/functions/src_prepare/epatch/text.xml +++ /dev/null @@ -1,155 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_prepare/epatch/"> -<chapter> -<title>Patching with epatch</title> - -<body> -<p> -The canonical way of applying patches in ebuilds is to -use <c>epatch</c> (from <c>eutils.eclass</c>, which you must make sure -to import!) inside <c>src_prepare</c>. This function automatically -handles <c>-p</c> levels, <c>gunzip</c> and so on as necessary. Also note that olds ebuild may still use src_unpack to apply patches. This is because those ebuilds are based in EAPI="1". You are advised to use EAPI="2" and apply your patches in src_prepare function instead. -</p> - -<p> -Note that distributing modified tarballs rather than a vanilla tarball -and patches is <e>highly</e> discouraged. -</p> -</body> - -<section> -<title>Basic <c>epatch</c></title> -<body> - -<p> -In its simplest form, <c>epatch</c> takes a single filename and -applies that patch. It will automatically <c>die</c> if the apply -fails. The following is taken from <c>app-misc/detox</c>: -</p> - -<codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - epatch "${FILESDIR}/${P}-destdir.patch" - epatch "${FILESDIR}/${P}-parallel_build.patch" -} -</codesample> - -<p> -For larger patches, using <uri link="::general-concepts/mirrors/#suitable-download-hosts">your devspace</uri> rather -than <c>files/</c> is more appropriate. In these situations, it is -usually best to <c>bzip2</c> the patch in question (as opposed to -<c>files/</c> patches, which must not be compressed). For example, -from <c>app-admin/showconsole</c>: -</p> - -<codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} -</codesample> -<p>As stated before, if you are using EAPI >=2, you should apply the patches in the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function</p> -<codesample lang="ebuild"> -src_prepare() { - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} -</codesample> - -<p> -Remember to add the patch to <c>SRC_URI</c>. -</p> -</body> - -<subsection> -<title>CVS Keyword Lines and Patches</title> -<body> -<p> -If your patch includes any changes to CVS <c>$Id: $</c> -(or <c>$Header: $</c>, or <c>$Date: $</c>) lines, it cannot be -distributed under <c>files/</c>, since CVS will clobber the patch when -you commit. In these situations, either remove this hunk of the patch -manually, or mirror the file. -</p> -</body> -</subsection> - -</section> - -<section> -<title>Multiple Patches with <c>epatch</c></title> -<body> - -<p> -epatch can also apply multiple patches (which can be selectively based -upon arch) from a single directory. This can be useful if upstream -have releases that need more patches. -</p> - -<p> -A simple example: -</p> - -<codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ - EPATCH_FORCE="yes" epatch -} -</codesample> - -<p> -Here, one of the <c>SRC_URI</c> components is a tarball containing -many patches with file extension <c>.patch</c>. -</p> - -<p> -Variables which may be defined include: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - </tr> - <tr> - <ti><c>EPATCH_SOURCE</c></ti> - <ti>Specifies the directory in which epatch looks for patches.</ti> - </tr> - <tr> - <ti><c>EPATCH_SUFFIX</c></ti> - <ti>File extension for patches.</ti> - </tr> - <tr> - <ti><c>EPATCH_OPTS</c></ti> - <ti>Default options to <c>patch</c>.</ti> - </tr> - <tr> - <ti><c>EPATCH_EXCLUDE</c></ti> - <ti>List of patches to exclude.</ti> - </tr> - <tr> - <ti><c>EPATCH_FORCE</c></ti> - <ti> - Force epatch to apply patches even if they do not follow the - canonical naming form (set to <c>yes</c>). - </ti> - </tr> -</table> - -<p> -Bulk patches should be named in the form -<c>??_${ARCH}_foo.${EPATCH_SUFFIX}</c>. If they are -not, <c>EPATCH_FORCE="yes"</c> must be set. To apply a patch on <c>all</c> -archs, use all for the <c>${ARCH}</c> part. -</p> - -</body> -</section> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_prepare/text.xml b/ebuild-writing/functions/src_prepare/text.xml index 29b1588..342a112 100644 --- a/ebuild-writing/functions/src_prepare/text.xml +++ b/ebuild-writing/functions/src_prepare/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_prepare/"> <chapter> <title>src_prepare</title> @@ -31,15 +31,38 @@ <section> <title>Default <c>src_prepare</c></title> <body> + <p> -Starting from EAPI="2", the src_prepare function is the appropriate area to perform -any kind of patching and source code manipulation, instead of src_unpack. +Before EAPI 6, the default implementation did nothing: </p> + <codesample lang="ebuild"> src_prepare() { - true; + true } </codesample> + +<p> +Beginning with EAPI 6, the src_prepare function gained a new default +implementation: +</p> + +<codesample lang="ebuild"> +src_prepare() { + if [[ $(declare -p PATCHES 2>/dev/null) == "declare -a"* ]]; then + [[ -n ${PATCHES[@]} ]] && eapply "${PATCHES[@]}" + else + [[ -n ${PATCHES} ]] && eapply ${PATCHES} + fi + eapply_user +} +</codesample> + +<note> +With EAPI 6, you must call <c>eapply_user</c> or <c>default</c> if you define +<c>src_prepare</c>! +</note> + </body> </section> @@ -48,16 +71,30 @@ src_prepare() { <body> <codesample lang="ebuild"> src_prepare() { - epatch "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" - use pam && epatch "${FILESDIR}/${PV}/${P}-pam.patch" + eapply "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" + eapply "${FILESDIR}/${PV}/${P}-pam.patch" + + eapply_user - sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" + sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" } </codesample> </body> </section> +<section> +<title><c>src_prepare</c> processes</title> +<body> +<p> +The following subsections cover different topics which often occur +when writing <c>src_prepare</c> functions. +</p> + +<contentsTree/> +</body> +</section> + </chapter> -<include href="epatch/"/> +<include href="eapply/"/> <include href="autopackage/"/> </guide> diff --git a/ebuild-writing/functions/src_test/text.xml b/ebuild-writing/functions/src_test/text.xml index dd02d4b..793e99f 100644 --- a/ebuild-writing/functions/src_test/text.xml +++ b/ebuild-writing/functions/src_test/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_test/"> <chapter> <title>src_test</title> @@ -31,23 +31,13 @@ <section> <title>Default <c>src_test</c></title> <body> -<p> From sys-apps/portage-2.1.2.9 </p> +<p>The default test phase in EAPI 6 is equivalent to the following:</p> <codesample lang="ebuild"> src_test() { - if emake -j1 check -n &> /dev/null; then - vecho ">>> Test phase [check]: ${CATEGORY}/${PF}" - if ! emake -j1 check; then - hasq test $FEATURES && die "Make check failed. See above for details." - hasq test $FEATURES || eerror "Make check failed. See above for details." - fi - elif emake -j1 test -n &> /dev/null; then - vecho ">>> Test phase [test]: ${CATEGORY}/${PF}" - if ! emake -j1 test; then - hasq test $FEATURES && die "Make test failed. See above for details." - hasq test $FEATURES || eerror "Make test failed. See above for details." - fi - else - vecho ">>> Test phase [none]: ${CATEGORY}/${PF}" + if nonfatal emake check -n &> /dev/null; then + emake check + elif nonfatal emake test -n &> /dev/null; then + emake test fi } </codesample> @@ -59,34 +49,52 @@ src_test() { <body> <codesample lang="ebuild"> src_test() { - cd "${S}"/src/testdir + cd "${S}"/src/testdir || die - # Test 49 won't work inside a portage environment - sed -i -e 's~test49.out~~g' Makefile + # Test 49 won't work inside a Portage environment + sed -i -e 's~test49.out~~g' Makefile || die - # Try to run the non-gui tests only - make test-nongui \ - || die "At least one test failed" + # Try to run the non-gui tests only + # pass -j1 if tests do not support being run in parallel + emake -j1 test-nongui } </codesample> </body> </section> <section> -<title>Common <c>src_test</c> Tasks</title> +<title>Supporting test suites in packages</title> <body> + +<p> +If the packaged software is equipped with a test suite, it is sensible +to run it. Sometimes the package will need additional dependencies for this, +i.e., dependencies that are only required to run the test suite. Such test-only +dependencies should be specified in DEPEND or BDEPEND behind a USE flag; +often, the <c>test</c> USE flag will be used for this. Please refer to the +section on <uri link="::general-concepts/dependencies/#Test dependencies"/> +for more information. +</p> + +<p> +Note that the <c>test</c> USE flag is only necessary if there are +test dependencies, tests are being built conditionally, or it is desirable +to vary behaviour based on whether tests will be run (e.g. downloading large +files in SRC_URI). It is not appropriate to use the flag to simply indicate that +tests exist and are expected to pass. +</p> + <p> Often the default <c>src_test</c> is fine. Sometimes it is necessary to remove certain tests from the list if they cannot be used with a -portage environment. Reasons for such a failure could include: +Portage environment. Reasons for such a failure could include: </p> <ul> - <li>Needing to use X.</li> <li> Needing to work with files which are disallowed by the sandbox. </li> - <li>Requiring user input (src_test must not be interactive).</li> + <li>Requiring user input (<c>src_test</c> must not be interactive).</li> <li>Requiring root privileges.</li> </ul> @@ -96,45 +104,172 @@ using <c>sed</c> or skipping a particular <c>make</c> target is sufficient. </p> +<p> +Try to ensure that tests work properly for your ebuild. A good test +suite is extremely helpful for arch maintainers. +Sometimes it is necessary to skip tests entirely. This can be done by +setting <c>RESTRICT="test"</c> in the ebuild. +</p> + <note> -<c>emake</c> should not be used for <c>src_test</c> <d/> trying to -parallelise tests unless the <c>Makefile</c> was specifically designed -for this can cause all sorts of strange problems. +If upstream provides a test suite that doesn't work, consider talking +to them about getting it fixed. A broken test suite requires developers +to investigate each test failure in order to determine whether it is +genuine or indicates a broken test. </note> +</body> +</section> +<section> +<title>Tests that require network or service access</title> +<body> <p> -Try to ensure that tests work properly for your ebuild. A good test -suite is extremely helpful for arch maintainers. +Sometimes test suites (and other build-time programs) attempt to use +remote or local network, or production servers running on the host. All +of these are strictly forbidden. Developers should either fix such tests +to work in an isolated environment, or disable them completely unless +explicitly allowed by the user. At the bare minimum, the tests must +not fail with <c>FEATURES=network-sandbox</c> being enabled. +</p> + +<p> +Internet access within the build procedure is forbidden for +the following reasons: +</p> +<ul> + <li> + the build may be running in an environment with no or restricted + Internet access, and this must not cause the tests (build) to fail; + </li> + + <li> + the Internet connection may be unstable (e.g. poor reception) + in which case an interrupted connection or packet loss must not + cause the tests to fail or hang, and it should not cause unnecessary + delays; + </li> + + <li> + the Internet connection may be running on a limited data plan + in which case the additional network use may cause additional + charges or other inconveniences to the user; + </li> + + <li> + the remote network services used by the tests may become unavailable + temporarily or permanently, causing unexpected test failures; + </li> + + <li> + accessing remote sites always poses a privacy issue, and possibly + a threat to security (e.g. through inadvertently exposing + information about the system). + </li> +</ul> + +<p> +Fixing tests that require Internet access usually requires cooperation +with upstream, and porting the tests to use test techniques such as +mocking or using replay data. For this reason, developers report +the issue upstream and skip tests that require network access. +It is recommended to explicitly leave a note as to why the tests are +skipped, so that other developers can re-enable them locally to run +a more complete test suite. +</p> + +<p> +It is generally considered acceptable to rely on IPv4 <c>localhost</c> being +resolvable and available for binding. Tests should only connect to services +that are started as part of the testsuite. It is not acceptable to connect +to daemons run outside the test environment. +</p> + +<p> +Local server access within the build procedure is forbidden for the following +reasons: +</p> + +<ul> + <li> + tests must run reliably independently of whether a particular + server is running throughout the build process or not, + </li> + + <li> + using production services for running tests is extremely + <b>dangerous</b> as it may inadvertently expose bugs in those + services, causing instability, data loss or even exposing security + vulnerabilities. + </li> +</ul> + +<p> +Fixing tests that require access to local services is usually done +via starting additional isolated instances of those services during +the test phase. Those services must either be running on a UNIX +socket or on the loopback interface, to reliably prevent remote access. +</p> + +<p> +For all networked services exposed during the test phase (either by +the ebuild or the tests themselves), UNIX sockets are strongly preferred +over IP sockets as they provide better means for unique naming +and access control mechanisms. IP sockets can be subject to port +collisions with other local services and they can be accessed by local +system users who may exploit a vulnerability through the tests. +</p> + +<p> +Additional protection against those issues is provided through +<c>FEATURES=network-sandbox</c>. However, this is only an optional +Portage feature relying on specific Linux kernel namespace mechanisms +and developers should not rely on it being enabled. </p> </body> </section> <section> -<title>Skipping Tests</title> +<title>Tests that require X11</title> <body> <p> -Sometimes it is necessary to skip tests entirely. This can be done -using a dummy <c>src_test</c> function: +Some packages include tests (or other build-time applications) that +attempt to use the user's X11 session and fail being unable to connect +to it. Those tests need to be fixed to work independently of the X11 +server that might or might not be running when packages are being built. +</p> + +<p> +If the program in question does not strictly need X11 but merely +attempts to take opportunity of the <c>DISPLAY</c> variable being set, +the best solution is to simply unset this variable in the ebuild. </p> <codesample lang="ebuild"> src_test() { - # Tests don't even remotely work inside portage - true + # tests attempt to connect to X11 and fail when it is set + # however, they work just fine without X11 + unset DISPLAY + + default } </codesample> <p> -Another option would be to set <c>RESTRICT="test"</c> in the ebuild. +If the package actually requires a running X11 server to run +the complete test suite, you can use the <c>virtualx</c> eclass to +provide an isolated Xvfb environment for the tests to use. It provides +a virtual X11 display that is not connected to any physical device +and that programs can use reliably. </p> -<note> -If upstream provide a test suite which doesn't work, consider talking -to them about getting it fixed. A broken test suite is worse than no -test suite at all, since we are unable to tell whether a test failure -indicates a genuine fault. -</note> +<codesample lang="ebuild"> +inherit virtualx + +src_test() { + virtx default +} +</codesample> </body> </section> diff --git a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml b/ebuild-writing/functions/src_unpack/cvs-sources/text.xml deleted file mode 100644 index 2f24cc7..0000000 --- a/ebuild-writing/functions/src_unpack/cvs-sources/text.xml +++ /dev/null @@ -1,190 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/cvs-sources/"> -<chapter> -<title>CVS Sources</title> - -<body> -<p> -Rather than working with a source tarball, it is possible to use -upstream's CVS server directly. This can be useful when there is a -need to test unreleased snapshots on a regular basis. -</p> -</body> - -<section> -<title>Disadvantages of CVS Sources</title> -<body> - -<p> -Note that CVS ebuilds should <b>not</b> generally be added to the tree -for the following reasons: -</p> - -<ul> - <li> - Upstream CVS servers tend to be far less reliable than our mirroring - system. - </li> - <li> - CVS ebuilds create a very heavy server load <d/> not only is CVS not - mirrored, but allowing a CVS checkout is considerably more work for - a server than simply serving up a file via HTTP or FTP. - </li> - <li> - Many users who are behind strict firewalls cannot use CVS. - </li> -</ul> - -<p> -It is safer to make a snapshot instead. For example, vim snapshots are made using: -</p> - -<pre> -$ cvs -z3 -d :pserver:anonymous@cvs.sourceforge.net:/cvsroot/vim export -r HEAD vim -</pre> -</body> -</section> - -<section> -<title>Disadvantages of CVS Live Sources</title> -<body> - -<p> -CVS ebuilds which work against CVS <c>HEAD</c> rather than a specific -date or revision are even worse candidates for tree inclusion: -</p> - -<ul> - <li> - You can never be sure whether upstream's CVS will actually - build at any given point; which will most likely cause QA issues. - </li> - <li> - It is extremely difficult to track down bugs when you cannot install - the same version of a package as the reporter. - </li> - <li> - Many upstream package maintainers tend to get upset if people aren't - using a specific released version. - </li> -</ul> - -</body> -</section> - -<section> -<title>Using CVS Sources</title> -<body> - -<note> -CVS ebuilds must be either with empty <c>KEYWORDS</c> or -package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are -strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and -to ebuilds that extract a static revision but still use CVS for -fetching. -</note> - -<p> -To use a CVS source, <c>cvs.eclass</c> must be inherited, and then a -number of variables must be set. The following variables are often -useful: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - <th>Example</th> - </tr> - <tr> - <ti><c>ECVS_SERVER</c></ti> - <ti>Server and path</ti> - <ti><c>"cvs.sourceforge.net:/cvsroot/vim"</c></ti> - </tr> - <tr> - <ti><c>ECVS_MODULE</c></ti> - <ti>Module</ti> - <ti><c>"vim"</c></ti> - </tr> - <tr> - <ti><c>ECVS_BRANCH</c></ti> - <ti>Branch</ti> - <ti><c>"HEAD"</c></ti> - </tr> - <tr> - <ti><c>ECVS_AUTH</c></ti> - <ti>Auth method</ti> - <ti><c>"ext"</c></ti> - </tr> - <tr> - <ti><c>ECVS_USER</c></ti> - <ti>Username</ti> - <ti><c>"anoncvs"</c></ti> - </tr> - <tr> - <ti><c>ECVS_PASS</c></ti> - <ti>Password</ti> - <ti><c>""</c></ti> - </tr> - <tr> - <ti><c>ECVS_TOPDIR</c></ti> - <ti>Unpack location</ti> - <ti><c>"${DISTDIR}/cvs-src/${ECVS_MODULE}"</c></ti> - </tr> -</table> - -<p> -See the eclass itself for the full range of options. To perform the -actual checkout, use the <c>cvs_src_unpack</c> function. -</p> - -<p> -Here's a simple example, based upon the CVS options in vim.eclass: -</p> - -<codesample lang="ebuild"> -inherit cvs - -SRC_URI="" - -src_unpack() { - ECVS_SERVER="cvs.sourceforge.net:/cvsroot/vim" - ECVS_USER="anonymous" - ECVS_PASS="" - ECVS_AUTH="pserver" - if [[ $(get_major_version ) -ge 7 ]] ; then - ECVS_MODULE="vim7" - else - ECVS_MODULE="vim" - fi - ECVS_TOP_DIR="${DISTDIR}/cvs-src/${ECVS_MODULE}" - cvs_src_unpack -} -</codesample> - -<p> -Here's another approach, based upon the <c>emacs-cvs</c> ebuild, which -relies upon the default <c>src_unpack</c> provided in the eclass; this -approach is simpler but less flexible: -</p> - -<codesample lang="ebuild"> -inherit cvs - -ECVS_AUTH="ext" -CVS_RSH="ssh" -ECVS_SERVER="savannah.gnu.org:/cvsroot/emacs" -ECVS_MODULE="emacs" -ECVS_BRANCH="emacs-unicode-2" -ECVS_USER="anoncvs" -ECVS_PASS="" -ECVS_CVS_OPTIONS="-dP" - -# ...and so on. No src_unpack() is specified. -</codesample> - -</body> -</section> - -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/deb-sources/text.xml b/ebuild-writing/functions/src_unpack/deb-sources/text.xml deleted file mode 100644 index bdbadb4..0000000 --- a/ebuild-writing/functions/src_unpack/deb-sources/text.xml +++ /dev/null @@ -1,12 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/deb-sources/"> -<chapter> -<title>Debian Sources</title> - -<body> -<todo> -from vapier: we dont have to 'handle' these because all debian packages have a source tarball ... the .deb format is pretty simple though, it's managed by the 'ar' utility from binutils. you can unpack a .deb by simply doing ar x blah.deb ... this will give you three files: debian-binary: plain text file which just contains version number of the .deb format control.tar.gz: a few files which control installing/verifying of package data.tar.gz: all the compiled files ... you could just extract it to / -</todo> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/other-formats/text.xml b/ebuild-writing/functions/src_unpack/other-formats/text.xml index 3647c80..891b322 100644 --- a/ebuild-writing/functions/src_unpack/other-formats/text.xml +++ b/ebuild-writing/functions/src_unpack/other-formats/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_unpack/other-formats/"> <chapter> -<title>Other Archive Formats</title> +<title>Other archive formats</title> <body> <p> @@ -11,7 +11,7 @@ Instructions for some of them are detailed below: </body> <section> -<title>Zip Files</title> +<title>Zip files</title> <body> <p> @@ -19,7 +19,7 @@ If a package is supplied as a .zip file, you should: </p> <ul> - <li><c>DEPEND</c> upon <c>app-arch/unzip</c></li> + <li><c>BDEPEND</c> upon <c>app-arch/unzip</c></li> <li>Use <c>unpack</c> as normal</li> </ul> @@ -27,7 +27,7 @@ If a package is supplied as a .zip file, you should: </section> <section> -<title>Shar Files</title> +<title>Shar files</title> <body> <p> If a package is supplied as a <c>.shar</c> file, you should repackage it locally @@ -39,7 +39,7 @@ done a release in at least ten years. </section> <section> -<title>RAR Files</title> +<title>RAR files</title> <body> <p> diff --git a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml index dcf9113..0029c53 100644 --- a/ebuild-writing/functions/src_unpack/rpm-sources/text.xml +++ b/ebuild-writing/functions/src_unpack/rpm-sources/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_unpack/rpm-sources/"> <chapter> -<title>RPM Sources</title> +<title>RPM sources</title> <body> <p> @@ -19,16 +19,16 @@ that will unpack the RPM files. </p> <p> -If you do need to apply patches then override <c>src_unpack</c> in a +If you do need to call additional unpack functions then override <c>src_unpack</c> in a manner such as: </p> <codesample lang="ebuild"> -src_unpack () { - rpm_src_unpack ${A} - cd "${S}" +src_unpack() { + rpm_src_unpack ${A} + cd "${S}" - use ssl && epatch "${FILESDIR}/${PV}/${P}-ssl.patch" + use ssl && eapply "${FILESDIR}/${PV}/${P}-ssl.patch" } </codesample> @@ -40,7 +40,7 @@ format. </body> <section> -<title>Example RPM Handling</title> +<title>Example RPM handling</title> <body> <p> @@ -52,18 +52,20 @@ patches. The filename should be <c>suse-fetchmail-6.2.5.54.1.ebuild</c>. </p> <codesample lang="ebuild"> -# Copyright 1999-2005 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -inherit eutils versionator rpm +EAPI=7 + +inherit rpm -MY_PV=$(replace_version_separator 3 '-') +MY_PV=$(ver_rs 3 '-') MY_P=fetchmail-${MY_PV} -SRC_URI="http://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm" DESCRIPTION="SuSE 9.2 Fetchmail Source Package" -HOMEPAGE="http://www.suse.com" +HOMEPAGE="https://www.suse.com" +SRC_URI="https://suse.osuosl.org/suse/i386/9.2/suse/src/${MY_P}.src.rpm" +S=${WORKDIR}/fetchmail-$(ver_cut 1-3) LICENSE="GPL-2 public-domain" SLOT="0" @@ -74,20 +76,22 @@ RESTRICT="mirror" # Need to test if the file can be unpacked with rpmoffset and cpio # If it can't then set: -#DEPEND="app-arch/rpm" +#BDEPEND="app-arch/rpm" # To force the use of rpmoffset and cpio instead of rpm2cpio from # app-arch/rpm, then set the following: #USE_RPMOFFSET_ONLY=1 -S=${WORKDIR}/fetchmail-$(get_version_component_range 1-3) - -src_unpack () { +src_unpack() { rpm_src_unpack ${A} - cd "${S}" - EPATCH_SOURCE="${WORKDIR}" EPATCH_SUFFIX="patch" \ - EPATCH_FORCE="yes" epatch +} + +src_prepare() { + for i in "${WORKDIR}"/*.patch ; do + eapply "${i}" + done + eapply_user } </codesample> diff --git a/ebuild-writing/functions/src_unpack/svn-sources/text.xml b/ebuild-writing/functions/src_unpack/svn-sources/text.xml deleted file mode 100644 index e436c97..0000000 --- a/ebuild-writing/functions/src_unpack/svn-sources/text.xml +++ /dev/null @@ -1,116 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/svn-sources/"> -<chapter> -<title>Subversion Sources</title> - -<body> -<p> -As with CVS, an eclass exists for working directly with upstream -Subversion repositories. See <uri link="::eclass-reference/subversion.eclass/">subversion.eclass</uri> -for a full list of functions and variables. Also see -the <uri link="::ebuild-writing/functions/src_unpack/cvs-sources"/> -ection. -</p> -</body> - -<section> -<title>Disadvantages of Subversion Sources</title> -<body> - -<p> -Note that Subversion ebuilds should <b>not</b> generally be added to -the tree for much the same reasons that live CVS ebuilds should not (see -<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>). -Indeed, there should be even less impetus to add a live Subversion ebuild than a live CVS ebuild, as -Subversion checkouts are roughly a factor of five larger than an -equivalent CVS checkout. -</p> - -<p> -It is safer (and better for the user) to make a snapshot instead. For -example, <c>gentoo-syntax</c> snapshots could be made using: -</p> - -<pre> -$ svn export svn://svn.berlios.de/svnroot/repos/gentoo-syntax -r HEAD gentoo-syntax -</pre> -</body> -</section> - -<section> -<title>Using Subversion Sources</title> -<body> - -<note> -Subversion ebuilds must be either with empty <c>KEYWORDS</c> or -package.masked (but <e>not</e> both). Empty <c>KEYWORDS</c> are -strongly preferred. This applies to "live" ebuilds (<c>-9999</c>) and -to ebuilds that extract a static revision but still use Subversion for -fetching. -</note> - -<p> -To use a Subversion source, <c>subversion.eclass</c> must be -inherited, and then at least <c>ESVN_REPO_URI</c> must be set. The -following variables are also noteworthy: -</p> - -<table> - <tr> - <th>Variable</th> - <th>Purpose</th> - <th>Example</th> - </tr> - <tr> - <ti><c>ESVN_REPO_URI</c></ti> - <ti>Server and path (http, https, svn)</ti> - <ti><c>"svn://svn.example.com/foobar/trunk"</c></ti> - </tr> - <tr> - <ti><c>ESVN_STORE_DIR</c></ti> - <ti>Unpack location</ti> - <ti><c>ESVN_STORE_DIR="${DISTDIR}/svn-src"</c></ti> - </tr> - <tr> - <ti><c>ESVN_PROJECT</c></ti> - <ti>Project name of ebuild</ti> - <ti><c>ESVN_PROJECT="${PN/-svn}"</c></ti> - </tr> - <tr> - <ti><c>ESVN_BOOTSTRAP</c></ti> - <ti>Bootstrap command or script</ti> - <ti><c>ESVN_BOOTSTRAP="autogen.sh"</c></ti> - </tr> - <tr> - <ti><c>ESVN_PATCHES</c></ti> - <ti>Patches to apply during bootstrap</ti> - <ti><c>ESVN_PATCHES="${FILESDIR}/*.patch"</c></ti> - </tr> -</table> - -<p> -See the eclass itself and <uri link="::eclass-reference/subversion.eclass/">subversion.eclass</uri> -for the full range of options. To perform the actual checkout, use -the <c>subversion_src_unpack</c> function, which calls -both <c>subversion_svn_fetch</c> and <c>subversion_bootstrap</c> -itself. -</p> - -<p> -Here is a simple example, based upon the Subversion options in -<c>litu-svn-20040902.ebuild</c>; this approach is sufficient for most -Subversion ebuilds: -</p> - -<codesample lang="ebuild"> -inherit subversion - -ESVN_REPO_URI="http://tao.uab.es/ion/svn/libtu/trunk" -ESVN_PROJECT="libtu-snapshot" -</codesample> - -</body> -</section> - -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/text.xml b/ebuild-writing/functions/src_unpack/text.xml index 542b3fb..250d947 100644 --- a/ebuild-writing/functions/src_unpack/text.xml +++ b/ebuild-writing/functions/src_unpack/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/src_unpack/"> <chapter> <title>src_unpack</title> @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Extract source packages and do any necessary patching or fixes.</ti> + <ti>Extract source packages.</ti> </tr> <tr> <th>Sandbox</th> @@ -33,9 +33,9 @@ <body> <codesample lang="ebuild"> src_unpack() { - if [ "${A}" != "" ]; then - unpack ${A} - fi + if [[ -n ${A} ]]; then + unpack ${A} + fi } </codesample> </body> @@ -44,26 +44,19 @@ src_unpack() { <section> <title>Sample <c>src_unpack</c></title> <body> + <codesample lang="ebuild"> src_unpack() { - unpack ${A} - cd "${S}" - - epatch "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" - use pam && epatch "${FILESDIR}/${PV}/${P}-pam.patch" - - sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" + unpack ${P}.tar.xz + use foo && unpack ${P}-foo-extension.tar.xz } </codesample> -<note> -When using EAPI >=2, you should use the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function to apply patches or alter any of the source files, instead of the src_unpack. -</note> </body> </section> <section> -<title>Unpacking Tarballs</title> +<title>Unpacking tarballs</title> <body> <p> The <c>unpack</c> function should be used to unpack tarballs, compressed @@ -80,7 +73,43 @@ usually simpler to avoid working with <c>${A}</c>. </section> <section> -<title><c>src_unpack</c> Actions</title> +<title>Known file formats</title> +<body> + +<p> +The <c>unpack</c> function recognizes the following file formats: +</p> + +<ul> + <li><c>*.tar</c></li> + <li> + <c>*.gz</c>, <c>*.Z</c>, + <c>*.tar.gz</c>, <c>*.tgz</c>, <c>*.tar.Z</c> + </li> + <li> + <c>*.bz2</c>, <c>*.bz</c>, + <c>*.tar.bz2</c>, <c>*.tbz2</c>, <c>*.tar.bz</c>, <c>*.tbz</c> + </li> + <li><c>*.lzma</c>, <c>*.tar.lzma</c></li> + <li><c>*.xz</c>, <c>*.tar.xz</c>, <c>*.txz</c></li> + <li><c>*.zip</c>, <c>*.ZIP</c>, <c>*.jar</c></li> + <li><c>*.a</c>, <c>*.deb</c></li> +</ul> + +<p> +In EAPI 6 and later, filename extensions are matched case-insensitively. +</p> + +<important> +Unless the utility needed for unpacking is in the system set, the ebuild must +specify the necessary build time dependency (<c>BDEPEND</c>) for it. +</important> + +</body> +</section> + +<section> +<title><c>src_unpack</c> actions</title> <body> <p> The following subsections cover different topics which often occur when writing @@ -93,10 +122,7 @@ The following subsections cover different topics which often occur when writing </chapter> -<include href="cvs-sources/"/> -<include href="svn-sources/"/> -<include href="tla-sources/"/> +<include href="vcs-sources/"/> <include href="rpm-sources/"/> -<include href="deb-sources/"/> <include href="other-formats/"/> </guide> diff --git a/ebuild-writing/functions/src_unpack/tla-sources/text.xml b/ebuild-writing/functions/src_unpack/tla-sources/text.xml deleted file mode 100644 index 97a8b40..0000000 --- a/ebuild-writing/functions/src_unpack/tla-sources/text.xml +++ /dev/null @@ -1,12 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/functions/src_unpack/tla-sources/"> -<chapter> -<title>Arch Sources</title> - -<body> -<todo> -Anyone want to write this? You can probably mostly copy the CVS Sources and Subversion Sources chapters. -</todo> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/functions/src_unpack/vcs-sources/text.xml b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml new file mode 100644 index 0000000..68fbe91 --- /dev/null +++ b/ebuild-writing/functions/src_unpack/vcs-sources/text.xml @@ -0,0 +1,100 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/functions/src_unpack/vcs-sources/"> +<chapter> +<title>Version Control System (VCS) sources</title> +<body> + +<p> +Rather than working with a source tarball, it is possible to use upstream +source code repositories directly. This can be useful when there is a need to +test unreleased snapshots on a regular basis. A number of eclasses exists for +this purpose; see their documentation for a list of available functions and +variables. +</p> + +<ul> + <li><uri link="::eclass-reference/cvs.eclass/"/></li> + <li><uri link="::eclass-reference/darcs.eclass/"/></li> + <li><uri link="::eclass-reference/git-r3.eclass/"/></li> + <li><uri link="::eclass-reference/mercurial.eclass/"/></li> + <li><uri link="::eclass-reference/subversion.eclass/"/></li> +</ul> + +<note> +VCS ebuilds must be with empty <c>KEYWORDS</c> but <e>not</e> package.masked +(except if the mask is for an independent reason). Usually the <c>KEYWORDS</c> +line should be omitted altogether. This applies to "live" ebuilds (<c>-9999</c>) +and to ebuilds that extract a static revision but still use a version control +system for fetching. +</note> + +</body> + +<section> +<title>Disadvantages of VCS sources</title> +<body> + +<p> +Note that VCS ebuilds should <b>not</b> generally be added to the tree for the +following reasons: +</p> + +<ul> + <li> + Upstream VCS servers tend to be far less reliable than our mirroring + system. + </li> + <li> + VCS ebuilds create a very heavy server load <d/> not only are repositories + not mirrored, but fetching sources from them is considerably more work for + a server than simply serving up a file via HTTP or FTP. + </li> + <li> + Local copies of a repository are several times larger than a tarball of the + same sources, and tend to grow over time because they include the history. + </li> + <li> + Many users who are behind strict firewalls cannot use protocols like CVS. + </li> +</ul> + +<p> +It is safer (and better for the user) to make a snapshot instead. For example, +<c>app-editors/emacs</c> snapshots are made using: +</p> + +<pre> +$ git archive --prefix=emacs/ HEAD | xz > emacs-${PV}.tar.xz +</pre> + +</body> +</section> + +<section> +<title>Disadvantages of VCS live sources</title> +<body> + +<p> +VCS ebuilds that work against the latest head (or tip) rather than a specific +date or revision are even worse candidates for tree inclusion: +</p> + +<ul> + <li> + You can never be sure whether upstream's source will actually build at any + given point; which will most likely cause QA issues. + </li> + <li> + It is extremely difficult to track down bugs when you cannot install the + same version of a package as the reporter. + </li> + <li> + Many upstream package maintainers tend to get upset if people aren't using + a specific released version. + </li> +</ul> + +</body> +</section> +</chapter> +</guide> diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml index d10a51f..c5a6cbc 100644 --- a/ebuild-writing/functions/text.xml +++ b/ebuild-writing/functions/text.xml @@ -1,20 +1,38 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/functions/"> <chapter> -<title>Ebuild Functions</title> +<title>Ebuild phase functions</title> <body> <p> -When installing packages from source, the function call order is <c>pkg_setup</c>, -<c>src_unpack</c>, <c>src_prepare</c>, <c>src_compile</c>, <c>src_test</c> (optional, <c>FEATURES="test"</c>), -<c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing packages -from a binary, the function call order is <c>pkg_setup</c>, <c>pkg_preinst</c>, -<c>pkg_postinst</c>. -As some phases haven't been introduced from the beginning, you can have a look at -<uri link="::ebuild-writing/eapi"/> for an overview, what have been introduced in which EAPI. +When installing packages from source, the phase function call order is +<c>pkg_pretend</c>, <c>pkg_setup</c>, +<c>src_unpack</c>, <c>src_prepare</c>, <c>src_configure</c>, <c>src_compile</c>, +<c>src_test</c> (optional, <c>FEATURES="test"</c>), +<c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing +packages from a binary, the phase function call order is <c>pkg_pretend</c>, +<c>pkg_setup</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. +As some phases haven't been introduced from the beginning, you can have a look +at <uri link="::ebuild-writing/eapi/"/> for an overview, what have been +introduced in which EAPI. </p> -<figure short="How the ebuild functions are processed" link="diagram.png"/> +<p> +Ebuilds should usually define phases in the order they are called, +as set out above, for readability. +</p> + +<figure short="How the ebuild phase functions are processed" link="diagram.png"/> + +<p> +The <c>pkg_pretend</c> function is to be used for performing various +early sanity checks, such as ensuring that certain kernel options are +enabled. It is important to keep in mind that <c>pkg_pretend</c> runs +separately from the rest of the phase function sequence. Consequently, +there is no environment saving or propagation to the next +phase. Moreover, ebuild dependencies are not guaranteed to be +satisfied at this phase. +</p> <p> The <c>pkg_prerm</c> and <c>pkg_postrm</c> functions are called when uninstalling a @@ -31,8 +49,9 @@ location, and Portage records digests of the files installed. </p> <p> -When testing or debugging, you can instruct Portage to execute a specific function -from an ebuild by using the <c>ebuild</c> command, see the <c>ebuild(1)</c> manual +When testing or debugging, you can instruct Portage to execute a +specific phase function of an ebuild by using the <c>ebuild</c> +command, see the <c>ebuild(1)</c> manual page for further information. </p> @@ -41,14 +60,51 @@ Downloading a package's source happens before any of these phases, so <c>emerge --fetchonly</c> should perform all the network access you need (unless you're using live ebuilds). Network access outside of this would not be cached locally (e.g. in <c>${DISTDIR}</c>, see -<uri link="::ebuild-writing/variables#Predefined Read-Only Variables."/>), +<uri link="::ebuild-writing/variables/#Predefined read-only variables"/>), which makes it hard to have reproducible builds (see -<uri link="::ebuild-writing/functions/src_unpack/cvs-sources#Disadvantages of CVS Sources"/>). +<uri link="::ebuild-writing/functions/src_unpack/vcs-sources/#Disadvantages of vcs sources"/>). Avoid network access in any phase by using local files, extending <c>SRC_URI</c> (see -<uri link="::ebuild-writing/variables#Ebuild-defined Variables"/>), etc. +<uri link="::ebuild-writing/variables/#Ebuild-defined variables"/>), etc. +</p> +</body> + +<section> +<title>Default phase functions</title> +<body> + +<p> +The default <c>pkg_nofetch</c> and <c>src_*</c> phase functions are accessible +via a function having a name that begins with <c>default_</c> and ends with the +respective phase function name. For example, a call to a function with the name +<c>default_src_compile</c> is equivalent to a call to the default +<c>src_compile</c> implementation. +</p> + +<p> +The default phase functions are: </p> + +<ul> + <li><c>default_pkg_nofetch</c></li> + <li><c>default_src_unpack</c></li> + <li><c>default_src_prepare</c></li> + <li><c>default_src_configure</c></li> + <li><c>default_src_compile</c></li> + <li><c>default_src_test</c></li> + <li><c>default_src_install</c></li> +</ul> + +<p> +A function named <c>default</c> is redefined for each of the above phases, +so that it will call the <c>default_*</c> function corresponding to +the current phase. For example, a call to the <c>default</c> function +during the <c>src_compile</c> phase is equivalent to a call to the +<c>default_src_compile</c> function. +</p> + </body> +</section> <section> <title>Contents</title> diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml index 1012edf..fe05e6b 100644 --- a/ebuild-writing/messages/text.xml +++ b/ebuild-writing/messages/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/messages/"> <chapter> <title>Messages</title> @@ -28,7 +28,7 @@ occupy 4 columns with their fancy leading markers. </body> <section> -<title>Information Messages</title> +<title>Information messages</title> <body> <p> @@ -45,9 +45,9 @@ with a green asterisk. On earlier versions, elog behaves just like einfo. <codesample lang="ebuild"> pkg_postinst() { - elog "You will need to set up your /etc/foo/foo.conf file before" - elog "running foo for the first time. For details, please see the" - elog "foo.conf(5) manual page." + elog "You will need to set up your /etc/foo/foo.conf file before" + elog "running foo for the first time. For details, please see the" + elog "foo.conf(5) manual page." } </codesample> @@ -61,8 +61,8 @@ logged by default. <codesample lang="ebuild"> src_compile() { - einfo "Starting a silent compile that takes hours." - ./build + einfo "Starting a silent compile that takes hours." + ./build || die } </codesample> @@ -70,7 +70,7 @@ src_compile() { </section> <section> -<title>Warning Messages</title> +<title>Warning messages</title> <body> <p> @@ -82,7 +82,7 @@ used for warning messages rather than information. </section> <section> -<title>Error Messages</title> +<title>Error messages</title> <body> <p> @@ -100,7 +100,7 @@ is mainly used for displaying additional error details before bailing out. <p> The <c>eqawarn</c> function can be used by eclass authors to notify ebuild writers about - deprecated functionality. eqawarn is defined in eutils. Portage doesn't log the qa message + deprecated functionality. eqawarn is defined in eutils prior to EAPI=7. Portage doesn't log the qa message class by default so users don't get annoyed by seeing messages they can't do much about. </p> @@ -119,7 +119,7 @@ See <uri link="::function-reference/message-functions/"/> for a full list of fun </section> <section> -<title>Good and Bad Messages</title> +<title>Good and bad messages</title> <body> <p> @@ -129,7 +129,7 @@ Here is an example of a bad message: <codesample lang="ebuild"> i=10 while ((i--)) ; do - ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass" + ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass" done </codesample> diff --git a/ebuild-writing/misc-files/changelog/text.xml b/ebuild-writing/misc-files/changelog/text.xml deleted file mode 100644 index 7ee5ce7..0000000 --- a/ebuild-writing/misc-files/changelog/text.xml +++ /dev/null @@ -1,111 +0,0 @@ -<?xml version="1.0"?> -<guide self="ebuild-writing/misc-files/changelog/"> -<chapter> -<title>ChangeLog</title> - -<body> -<p> -The <c>ChangeLog</c> must be updated with each commit. The -<uri link="::tools-reference/echangelog/">echangelog tool</uri> should be used to create <c>ChangeLog</c> entries; -the format of a <c>ChangeLog</c> is now defined as "whatever -<c>echangelog</c> creates". -</p> - -<p> -You should include references to any relevant bugs. The standard -format for doing this is via the phrase <c>bug #20600</c> — this -format (with the hash sign included) is recognised via -<uri link="http://packages.gentoo.org">packages.gentoo.org</uri> and -similar tools. When including user-submitted ebuilds or patches, you -should credit the user with their full name and email address (or -whatever they use to identify themselves on bugzilla <d/> some users -prefer to be known only by a nickname). -</p> - -<p> -If you are changing keywords, make sure you clearly state what -keywords you add or remove. "Marked stable" is a nuisance for -architecture teams, even if there was only one keyword in the ebuild -at the time. "Stable on all archs" isn't generally any better (and -should you really be stabling on all archs?) — do you mean "all", or -"all the ones that are currently keyworded"? A list like "x86 sparc -mips" is much more useful. -</p> - -<p> -A typical <c>ChangeLog</c> snippet might look like the following: -</p> - -<pre> - *vim-6.3.068 (25 Mar 2005) - - 25 Mar 2005; Ciaran McCreesh <ciaranm@gentoo.org> +vim-6.3.068.ebuild: - New release. Fixes bug #79981, bug #81289, bug #83383, bug #83416, bug - #83565, bug #85758, upstream patches up to 6.3.068. - - 22 Mar 2005; Aron Griffis <agriffis@gentoo.org> vim-6.3-r4.ebuild: - Stable on alpha -</pre> - -<note> -If a <c>ChangeLog</c> file is not present in your current working directory, -then you should write a <c>ChangeLog</c> entry in the parent's directory -<c>ChangeLog</c> file. -</note> - -<section> -<title>Writing correct ChangeLog messages</title> -<body> -<note> -It is <b>very</b> important that your <c>cvs commit</c> messages are -also informative to aid the QA team or architecture teams as well as -other developers if they are trying to troubleshoot issues which are -known to not have occured in previous versions of ebuilds, for -example. If your ChangeLog message is concise there is usually nothing -wrong with using it as the <c>cvs commit</c> message. -</note> - -<p> -Your message should explain what specifically you changed and, if -relevant, why. You don't need to write an essay or even a complete -sentence (<c>ChangeLog</c> messages, however, are required to be in -'proper' English so no <c>fixed that bug kthx Bob</c> messages — -please do use punctuation), so long as it is easily understandable and -(preferably) greppable. Bad and good examples, all of which are based -upon real messages: -</p> - -<ul> - <li><b>BAD:</b> Changed keywords</li> - <li><e>GOOD:</e> Added ~x86 keyword</li> -</ul> - -<ul> - <li><b>BAD:</b> Stable</li> - <li><e>GOOD:</e> Stable on x86, sparc, mips</li> -</ul> - -<ul> - <li><b>BAD:</b> Fix stuff</li> - <li><e>GOOD:</e> Fix USE=foo logic error</li> -</ul> - -<ul> - <li><b>BAD:</b> .</li> - <li><e>GOOD:</e> Purge old ebuilds</li> -</ul> - -<ul> - <li> - <b>BAD:</b> Who the fuck reads this anyway? (<b>Editor's note</b>: - No, seriously, this is a genuine example. Do <e>not</e> do - this...) - </li> - <li><e>GOOD:</e> Version bump to 0.5.1.</li> -</ul> - -</body> -</section> -</body> -</chapter> -</guide> diff --git a/ebuild-writing/misc-files/metadata/text.xml b/ebuild-writing/misc-files/metadata/text.xml index 4b8d042..4d549f4 100644 --- a/ebuild-writing/misc-files/metadata/text.xml +++ b/ebuild-writing/misc-files/metadata/text.xml @@ -1,29 +1,45 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/misc-files/metadata/"> <chapter> -<title>Package and Category <c>metadata.xml</c></title> +<title>Package and category <c>metadata.xml</c></title> <body> <p> The <c>metadata.xml</c> file is used to specify additional data about a package or category. </p> +</body> <section> -<title>Package Metadata</title> +<title>Syntax</title> <body> + <p> -For packages, <c>metadata.xml</c> can specify a long description and -maintainer information. If a long description in any language is -provided, an English long description must be present. A typical -example might look like: +A metadata file follows the syntax defined in +<uri link="https://www.gentoo.org/glep/glep-0068.html">GLEP 68</uri>. +The character set <b>must</b> be UTF-8 as specified by +<uri link="https://www.gentoo.org/glep/glep-0031.html">GLEP 31</uri>. </p> -<subsection> -<body> +<p> +Concerning indentation there is no strict rule governing the style and +width. However the following minimal set of rules need to be followed: +</p> + +<ul> + <li> + Indentation should be consistent, i.e. either spaces or tabs, but + not both. + </li> + <li> + Keep the existing style when touching metadata.xml files that + belong to other developers. + </li> +</ul> <p> -A <path>metadata.xml</path> file can contain a number of tags: +The following table summarizes the tags that may appear in a +metadata.xml: </p> <table> @@ -33,182 +49,212 @@ A <path>metadata.xml</path> file can contain a number of tags: </tr> <tr> <ti> - <brite><pkgmetadata></brite> + <c><catmetadata></c> </ti> <ti> - This is the root element of the <path>metadata.xml</path> file for + This is the root element of the <c>metadata.xml</c> file for + categories. It has no attributes. It contains a number of + <c><longdescription></c> tags, each for a different language. + </ti> +</tr> +<tr> + <ti> + <c><pkgmetadata></c> + </ti> + <ti> + This is the root element of the <c>metadata.xml</c> file for packages. It has no attributes. The following subtags are allowed: - <brite><herd></brite>, - <brite><maintainer></brite>, - <brite><longdescription></brite>, - <brite><use></brite>, and - <brite><upstream></brite>. - There should be at least one <brite><herd></brite> or - <brite><maintainer></brite> subtag. + <c><maintainer></c>, + <c><longdescription></c>, + <c><stabilize-allarches></c>, + <c><slots></c>, + <c><use></c>, and + <c><upstream></c>. + While all the subtags are optional, <upstream> may + appear at most once. </ti> </tr> <tr> <ti> - <brite><catmetadata></brite> + <c><maintainer></c> </ti> <ti> - This is the root element of the <path>metadata.xml</path> file for - categories as per <uri link="https://wiki.gentoo.org/wiki/GLEP:34">GLEP 34</uri>. - It has no attributes. It contains a number of - <brite><longdescription></brite> tags, each for a different - language. + This tag specifies the persons and/or projects responsible for + the maintenance of a package. The <c>type</c> attribute must + be specified and can be either <c>"person"</c> or <c>"project"</c>. + There is one required subtag: + <c><email></c>. It has two optional subtags: + <c><name></c> and + <c><description></c>. </ti> </tr> <tr> + <ti><c><email></c></ti> <ti> - <brite><herd></brite> + This contains the e-mail address of the maintainer. It is required. </ti> +</tr> +<tr> + <ti><c><name></c></ti> <ti> - If a package is maintained by one or more herds, names of these herds - can be specified with the <brite><herd></brite> tag. The names - used in this tag must be the same as specified in the <uri - link="http://sources.gentoo.org/viewcvs.py/*checkout*/gentoo/xml/htdocs/proj/en/metastructure/herds/herds.xml?content-type=text/plain&rev=HEAD">herds.xml</uri> - file. + This contains freetext with the name of the maintainer. It is optional. </ti> </tr> <tr> + <ti><c><description></c></ti> <ti> - <brite><maintainer></brite> + The description tag contains a description of the maintainership, or for + example a remark that someone interested can take over the maintainership. + It is optional. </ti> +</tr> +<tr> + <ti><c><longdescription></c></ti> <ti> - Besides being part of a herd, a package can also be maintained directly. - The maintainers of a package can be specified with the - <brite><maintainer></brite> tag. This tag has one required subtag: - <brite><email></brite>. It has two optional subtags: - <brite><name></brite>, and <brite><description></brite>. + This tag contains a description for a category or a package. + For packages, it is used to augment the + <uri link="::ebuild-writing/variables/#Ebuild-defined variables"> + DESCRIPTION</uri> field in the ebuilds themselves. This tag has + two optional subtags: <c><pkg></c> and <c><cat></c>. </ti> </tr> <tr> - <ti><brite><email></brite></ti> + <ti><c><stabilize-allarches></c></ti> <ti> - This contains the e-mail address of the maintainer. It is required. + Indicates an architecture-independent package. An ebuild can be marked + stable for all relevant architectures, when it has been tested on only one + architecture. This tag must have empty content. </ti> </tr> <tr> - <ti><brite><name></brite></ti> + <ti><c><slots></c></ti> <ti> - This contains freetext with the name of the maintainer. It is optional. + This tag describes the + <uri link="::general-concepts/slotting/">slots</uri> of a package. + It has two optional subtags: + <c><slot></c> and <c><subslots></c>. </ti> </tr> <tr> - <ti><brite><description></brite></ti> + <ti><c><slot></c></ti> <ti> - The description tag contains a description of the maintainership, or for - example a remark that someone interested can take over the maintainership. - It is optional. + This contains information for a particular slot. The <c>name</c> + attribute is mandatory and specifies the name of the slot. </ti> </tr> <tr> - <ti><brite><longdescription></brite></ti> + <ti><c><subslots></c></ti> <ti> - This tag contains a description of the package. This is to augment the - DESCRIPTION field in the ebuilds themselves. This tag has two optional - subtags: <brite><pkg></brite> and <brite><cat></brite>. + Describes the meaning of subslots for the whole package. This + tag may appear at most once. </ti> </tr> <tr> - <ti><brite><use></brite></ti> + <ti><c><use></c></ti> <ti> - This tag contains descriptions of <uri - link="::ebuild-writing/variables#iuse">USE flags</uri>. + This tag contains descriptions of + <uri link="::ebuild-writing/variables/#IUSE">USE flags</uri>. This tag is optional and, if specified, has one required subtag: - <brite><flag></brite>. + <c><flag></c>. </ti> </tr> <tr> - <ti><brite><flag></brite></ti> + <ti><c><flag></c></ti> <ti> This tag contains a description of how the named USE flag affects this - package. It is required if the <brite><use></brite> tag is specified. + package. It is required if the <c><use></c> tag is specified. It also requires the USE flag to be named in the <c>name</c> attribute. - This tag has two optional subtags: <brite><pkg></brite> and - <brite><cat></brite>. + This tag has two optional subtags: <c><pkg></c> and + <c><cat></c>. </ti> </tr> <tr> - <ti><brite><upstream></brite></ti> + <ti><c><upstream></c></ti> <ti> This tag contains information about the upstream developers/project. + It supports multiple optional subtags: <c><maintainer></c>, + <c><changelog></c>, <c><doc></c>, + <c><bugs-to>,</c>, and <c><remote-id></c>. </ti> </tr> <tr> - <ti><brite><maintainer></brite></ti> + <ti><c><maintainer></c></ti> <ti> - Name and e-mail of an upstream maintainer. May appear more than once. + Provides information about the upstream maintainer. It requires a + <c><name></c> subtag to be specified, supports an optional + <c><email></c> subtag and an optional <c>status</c> attribute. + Note that the <c>type</c> attribute <e>must not</e> be specified + for upstream maintainers. </ti> </tr> <tr> - <ti><brite><email></brite></ti> + <ti><c><name></c></ti> <ti> - The email address of an upstream may appear only once and must appear in first place. + The name of an upstream maintainer should contain a block of text with upstream's name. + This element is mandatory for an upstream maintainer and must appear exactly once. </ti> </tr> <tr> - <ti><brite><name></brite></ti> + <ti><c><email></c></ti> <ti> - The name of an upstream maintainer should contain a block of text with upstream's name. - This element is mandatory for an upstream maintainer and must appear only once. + The email address of an upstream maintainer. May appear only once. </ti> </tr> <tr> - <ti><brite><changelog></brite></ti> + <ti><c><changelog></c></ti> <ti> Should contain a URL where the location of the upstream changelog can be found. The URL must be version independent and must point to a changelog which is only updated on new releases of the corresponding package. (This also implies that one can link to an automatically updated changelog in case of vcs snapshots - only.) + only). May appear at most once. </ti> </tr> <tr> - <ti><brite><doc></brite></ti> + <ti><c><doc></c></ti> <ti> Should contain a URL where the location of the upstream documentation can be found. The link must not point to any third party documentation and must be version independent. If the documentation is available in more than one language, a lang attribute can be used which follows the same rules as the one for - longdescription. + <c><longdescription></c>. </ti> </tr> <tr> - <ti><brite><bugs-to></brite></ti> + <ti><c><bugs-to></c></ti> <ti> Should contain a place where bugs can be filed, a URL or an e-mail address prefixed - with mailto:. + with <c>mailto:</c>. May appear at most once. </ti> </tr> <tr> - <ti><brite><remote-id></brite></ti> + <ti><c><remote-id></c></ti> <ti> Should specify a type of package identification tracker and the identification that corresponds to the package in question. remote-id should make it easier to index information such as its Freshmeat ID or its CPAN name. + It has a mandatory attribute <c>type</c> which identifies the type + of upstream source. </ti> </tr> <tr> - <ti><brite><pkg></brite></ti> + <ti><c><pkg></c></ti> <ti> - This tag contains a valid package name in the format of a DEPEND. + This tag contains a valid qualified package name. </ti> </tr> <tr> - <ti><brite><cat></brite></ti> + <ti><c><cat></c></ti> <ti> This tag contains a valid category name as defined in - <path>profiles/categories</path>. + <c>profiles/categories</c>. </ti> </tr> </table> <p> -There are also some attributes that can be used with these tags. They are all -optional: +There are also some attributes that can be used with these tags: </p> <table> @@ -220,301 +266,439 @@ optional: <tr> <ti>lang</ti> <ti> - <brite><description></brite>, <brite><longdescription></brite>, - <brite><use></brite>, <brite><doc></brite> + <c><description></c>, <c><longdescription></c>, + <c><slots></c>, <c><use></c>, <c><doc></c> </ti> <ti> In every case where a description is required, there must be at <e>least</e> an english description. If an additional description in another language is given, this attribute is used to specify the language - used. The format is the two-character language code as defined by the <uri - link="http://www.w3.org/WAI/ER/IG/ert/iso639.htm#2letter">ISO-639-1</uri> - norm. + used. The format is an IETF language tag as defined by the + <uri link="https://tools.ietf.org/rfc/bcp/bcp47.txt">BCP 47</uri> + specification. Most often, this will be a two-character language code. </ti> </tr> <tr> <ti>restrict</ti> <ti> - <brite><herd></brite>, <brite><maintainer></brite>, - <brite><longdescription></brite>, <brite><flag></brite> + <c><maintainer></c>, <c><longdescription></c>, + <c><stabilize-allarches></c>, <c><flag></c> </ti> <ti> The restrict attribute allows one to restrict the application of certain - tags to certain versions of a package. When this attribute is used, a tag - without this attribute must also exist. That tag without the restrict - attribute will serve as the default. The format of the restrict attribute - is that of the DEPEND flag, except that "<" and - ">" need to be specified by &lt; and &gt;.<br /> - <br /> - For example, in the <c>sys-libs/db</c> package, - <c>restrict="&gt;=sys-libs/db-3.2.9-r5"</c> on the - <brite>maintainer</brite> tag shows that I'm currently maintaining all - versions greater then 3.2.9-r5. + tags to certain versions of a package. The format of the restrict attribute + is that of a EAPI 0 package dependency specification (i.e. USE-conditional + or slot dependendencies are not allowed). Since <c><</c> and <c>></c> + are special characters in XML, they must be escaped using <c>&lt;</c> + and <c>&gt;</c>. </ti> </tr> <tr> <ti>name</ti> <ti> - <brite><flag></brite> + <c><flag></c>, <c><slot></c> </ti> <ti> - This attribute is required on the <brite><flag></brite> tag. It - simply contains the USE flag. - <br /><br /> - For example, in the <c>sys-apps/hal</c> package, <c><flag name='acpi'> - Enables ACPI</flag></c> + When this attribute is required on the <c><flag></c> tag, it + simply contains the name of the USE flag. For the + <c><slot></c> tag, it specifies the + <uri link="::general-concepts/slotting/#Slot names"> + slot name</uri> to which it applies. A slot name of <c>*</c> + allows for a single <c><slot></c> tag to match all the slots of a + package, in which case no other slot tags may be present. </ti> </tr> <tr> <ti>status</ti> <ti> - <brite><maintainer></brite> + <c><maintainer></c> </ti> <ti> - The upstream maintainer element has a status attribute, which is one of active or inactive. - This attribute is not mandatory. The absence of it shall be interpreted as unknown. - Please note: This attribute is only allowed in the <upstream> <maintainer> element! + The upstream maintainer element has a status attribute, which is + one of <c>"active"</c> or <c>"inactive"</c>. This attribute is not + mandatory. The absence of it shall be interpreted as + <c>"unknown"</c>. Please note that this attribute is only allowed + for the <c><maintainer></c> subtags of the <c><upstream></c> + element! </ti> </tr> <tr> <ti>type</ti> <ti> - <brite><remote-id></brite> + <c><remote-id></c> </ti> <ti> - A string identifying the type of upstream source. A list of valid strings are kept in metadata.dtd. + A string identifying the type of upstream source. A list of valid strings are kept in + <uri link="https://www.gentoo.org/dtd/metadata.dtd">metadata.dtd</uri>. Developers should email the gentoo-dev mailing list before using a new type value. </ti> </tr> +<tr> + <ti>type</ti> + <ti> + <c><maintainer></c> + </ti> + <ti> + Defines the type of the maintainer for a package. There are only + two valid values: <c>"person"</c> and <c>"project"</c>. The latter + denotes an official + <uri link="::general-concepts/projects/">Gentoo project</uri>. + </ti> +</tr> </table> </body> -</subsection> +</section> +<section> +<title>Package metadata</title> +<body> +<p> +All packages <b>must</b> include a <c>metadata.xml</c> file which +provides information about package description, maintainers, local USE +flags, upstream etc. +</p> +<p> +For developers' convenience, a skeleton file is provided in the +Gentoo tree with the name +<uri link="https://gitweb.gentoo.org/repo/gentoo.git/tree/skel.metadata.xml"> +skel.metadata.xml</uri>. The metadata file can also be created +using the <c>app-portage/metagen</c> tool. +</p> + +<p> +Commits of package metadata files are handled by <c>pkgdev</c> as +part of regular package maintenance. +</p> + +<p> +Unless specified otherwise, the maintainer who is listed in the +metadata first shall be the assignee for the bugs for that package as +per <uri link="https://www.gentoo.org/glep/glep-0067.html#bug-assignment"> +GLEP 67</uri>. +</p> </body> -</section> -<section> -<title>Metadata Examples</title> <subsection> -<title>First Example</title> +<title>Package metadata examples</title> +<body> + +<p> +In the following sections, various examples of metadata.xml are +provided. These examples are based on actual package metadata files to +keep things as realistic as possible. However, they may not include +these files verbatim and should be taken as hypothetical examples. +</p> +</body> + +<subsubsection> +<title>Projects as maintainers</title> <body> <p> -In this first example we provide you with the <path>metadata.xml</path> for -OpenOffice of which the ebuilds are completely managed by a herd called -<c>openoffice</c>: +For the first example, a package maintained by a single project is +presented. It is a simplified version of <c>metadata.xml</c> for +the package <c>app-office/libreoffice</c>. The package +maintainer is identified by the email address <c>office@gentoo.org</c> +with the name <c>Gentoo Office Project</c> as specified in the +optional <c><name></c> subtag. It also provides a long package +description. </p> <codesample lang="sgml"> -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> - <herd>openoffice</herd> + <maintainer type="project"> + <email>office@gentoo.org</email> + <name>Gentoo Office Project</name> + </maintainer> <longdescription> - OpenOffice is the opensource version of staroffice. - This ebuild allows you to compile it yourself. Unfortunately this - compilation can take up to a day depending on the speed of your - computer. It will however make a snappier openoffice than the binary - version. + LibreOffice is the successor of OpenOffice.org. This ebuild + allows you to compile it yourself. Unfortunately this compilation can + take up to a day depending on the speed of your computer. It will + however make a snappier LibreOffice than the binary version. </longdescription> </pkgmetadata> </codesample> <p> -The <c>openoffice</c> herd is defined in <path>herds.xml</path> by the -<uri link="http://www.gentoo.org/proj/en/metastructure">Gentoo Metastructure Project</uri>: +The email address <c>office@gentoo.org</c> corresponds to the +<c>Gentoo Office Project</c> as defined in +<uri link="https://api.gentoo.org/metastructure/projects.xml"> +projects.xml</uri>. This file lists all the projects in Gentoo and it +is generated from the +<uri link="https://wiki.gentoo.org/wiki/Project:Gentoo"> +projects listing</uri> available on the Gentoo Wiki: </p> -<note> -This example may be outdated when you read it. It's just an example! -</note> - <codesample lang="sgml"> -<herd> - <name>openoffice</name> - <email>openoffice@gentoo.org</email> - <description>Openoffice related packages</description> - <maintainer><email>pauldv@gentoo.org</email></maintainer> - <maintainer><email>suka@gentoo.org</email></maintainer> -</herd> +<project> + <email>office@gentoo.org</email> + <name>Gentoo Office Project</name> + <url>https://wiki.gentoo.org/wiki/Project:Office</url> + <description> + The Office project manages the office implementations + and related packages in Gentoo. + </description> + <member> + <email>dilfridge@gentoo.org</email> + <name>Andreas K. Hüttel</name> + <role>member</role> + </member> + <member> + <email>scarabeus@gentoo.org</email> + <name>Tomáš Chvátal</name> + <role>member</role> + </member> +</project> </codesample> -<p> -If you want to add (or remove) yourself from a herd, edit <path>herds.xml</path> -located in <path>[gentoo]/xml/htdocs/proj/en/metastructure/herds</path> in Gentoo's CVS repository. Make sure you -know the e-mail alias the herd listens to (for instance the "sound" herd has -<mail link="sound@gentoo.org">sound@gentoo.org</mail>) and add yourself to the -alias (by editing <path>/var/mail/alias/misc/<alias name></path> on -dev.gentoo.org). -</p> - </body> -</subsection> -<subsection> -<title>Second Example</title> +</subsubsection> +<subsubsection> +<title>Local USE flag descriptions</title> <body> <p> -For the second example, we will examine the <path>metadata.xml</path> of -<c>app-portage/mirrorselect</c>. This ebuild is maintained by the -<c>tools-portage</c> herd, but has a separate maintainer. +The second example is formed after the <c>metadata.xml</c> of +<c>sys-apps/portage</c>. It lists multiple maintainers where one +is a developer and the other is a project. It illustrates how local +USE flag descriptions are specified and also contains an upstream +element. It is also worth pointing out the use of <c>mailto:</c> +prefix in <c><bugs-to></c> tag due to the presence of an email address +as opposed to a URL. Conversely, email addresses specified in the +<c><email></c> tags require no such prefix. </p> <codesample lang="sgml"> -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> - <herd>tools-portage</herd> - <maintainer> - <email>johnm@gentoo.org</email> - <name>John Mylchreest</name> + <maintainer type="person"> + <email>larry@gentoo.org</email> + <name>Larry the Cow</name> </maintainer> - <longdescription> - This utility is used to select the fastest mirror (distfiles) and provide a - nicer front-end for mirror selection (both rsync + distfiles) to a user. - </longdescription> + <maintainer type="project"> + <email>dev-portage@gentoo.org</email> + </maintainer> + <use> + <flag name="epydoc">Build html API documentation with epydoc.</flag> + <flag name="ipc">Use inter-process communication between Portage and running ebuilds.</flag> + <flag name="pypy2_0">Use pypy-c2.0 as Python interpreter.</flag> + <flag name="python2">Use python2 as Python interpreter.</flag> + <flag name="python3">Use python3 as Python interpreter.</flag> + <flag name="xattr"> + Preserve extended attributes (filesystem-stored metadata) when + installing files. Usually only required for hardened systems. + </flag> + </use> + <upstream> + <bugs-to>mailto:dev-portage@gentoo.org</bugs-to> + <changelog>https://gitweb.gentoo.org/proj/portage.git/plain/RELEASE-NOTES</changelog> + <doc>https://wiki.gentoo.org/wiki/Handbook:AMD64/Working/Portage</doc> + </upstream> </pkgmetadata> </codesample> </body> -</subsection> -<subsection> -<title>Third Example</title> +</subsubsection> +<subsubsection> +<title>Split maintainership</title> <body> <p> -For the third example, we will describe the <path>metadata.xml</path> of -<c>sys-apps/hal</c>. This ebuild is maintained by the <c>gentopia</c> herd -and contains USE flag descriptions. +This example splits the maintainership based on package versions using +the attribute <c>restrict</c>. According to the +<c>metadata.xml</c> of <c>sys-boot/grub</c>, the ebuilds +for version 2 and above are maintained by floppym@gentoo.org whereas +earlier versions are maintained by the Gentoo Base System +project. Note the use of "&gt;" as opposed to ">" in +<c>restrict</c>. +</p> + +<p> +The example also uses the <c><pkg></c> tag in USE flag +descriptions. Slot dependency specifiers are not allowed inside +<c><pkg></c>, therefore the notation +<c><pkg>sys-boot/grub</pkg>:2</c> is adopted as opposed to +<c><pkg>sys-boot/grub:2</pkg></c>. +</p> + +<p> +Lastly, the <c><remote-id></c> tag in the upstream description +is demonstrated. </p> <codesample lang="sgml"> -<?xml version="1.0" encoding="UTF-8"> -<!DOCTYPE pkgmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> <pkgmetadata> -<herd>gentopia</herd> -<maintainer> - <email>compnerd@gentoo.org</email> -</maintainer> -<maintainer> - <email>steev@gentoo.org</email> -</maintainer> -<use> - <flag name='acpi'>Enables HAL to attempt to read from - /proc/acpi/event, if unavailable, HAL will read events from - <pkg>sys-power/acpid</pkg>. If you need multiple acpi - readers, ensure acpid is in your default runlevel along with HAL. This - will also enable HAL to read Toshia and IBM acpi events which do not - get sent via /proc/acpi/event</flag> - <flag name='crypt'>Allows HAL to mount volumes that are encrypted using - LUKS. <pkg>sys-fs/cryptsetup-luks</pkg> which has recently been renamed - to <pkg>sys-fs/cryptsetup</pkg> allows you to create such encrypted - volumes. HAL will be able to handle volumes that are removable or - fixed.</flag> - <flag name='dell'>Builds an installs the Dell addon, which reads data from - the Dell SM BIOS via <pkg>sys-libs/libsmbios</pkg>. It will read your - service tag information and your hardware backlight data as well as - allow you to modify the backlight settings on a Dell laptop.</flag> - <flag name='disk-partition'>Allows HAL to use libparted from - <pkg>sys-apps/parted</pkg> to read raw partition data from your disks - and process that data. Future versions of HAL (possibly 0.5.11 and - higher) will allow you to create, modify, delete and format partitions - from a GUI interface agnostic of your desktop environment.</flag> - <flag name='doc'>Generates documentation that describes HAL's fdi - format.</flag> - <flag name='pcmcia'>Allows HAL to process PCMCIA/CardBus slot data which - includes inserts and removals and act on these events.</flag> - <flag name='selinux'>Installs SELinux policies and links HAL to the SELinux - libraries.</flag> -</use> + <maintainer restrict="&gt;=sys-boot/grub-2" type="person"> + <email>floppym@gentoo.org</email> + </maintainer> + <maintainer type="project"> + <email>base-system@gentoo.org</email> + <name>Gentoo Base System</name> + </maintainer> + <use> + <flag name="device-mapper"> + Enable support for device-mapper from <pkg>sys-fs/lvm2</pkg> + </flag> + <flag name="efiemu"> + Build and install the efiemu runtimes + </flag> + <flag name="fonts">Build and install fonts for the gfxterm module</flag> + <flag name="mount"> + Build and install the grub-mount utility + </flag> + <flag name="libzfs"> + Enable support for <pkg>sys-fs/zfs</pkg> + </flag> + <flag name="multislot"> + Allow concurrent installation of <pkg>sys-boot/grub</pkg>:0 and + <pkg>sys-boot/grub</pkg>:2 by renaming all programs. + </flag> + <flag name="themes">Build and install GRUB themes (starfield)</flag> + <flag name="truetype"> + Build and install grub-mkfont conversion utility + </flag> + </use> + <upstream> + <remote-id type="sourceforge">dejavu</remote-id> + </upstream> </pkgmetadata> </codesample> </body> -</subsection> -<subsection> -<title>Fourth Example</title> +</subsubsection> +<subsubsection> +<title>Slots and subslots</title> <body> <p> -This example demonstrates the usage of the upstream element: +The main focus of this example is to demonstrate how slots and +subslots are specified, by examining the metadata of +<c>media-libs/libpng</c>. There may be multiple reasons for +slotting depending on the nature of the package. For this particular +package, it can be seen that the slots are used to provide different +versions of the library with varying binary compatibility and that +developers are advised to build against the slot 0. Furthermore, +different versions of this package with the same subslot provide the +same Application Binary Interface (ABI), according to the description +specified in the <c><subslots></c> tag. </p> <codesample lang="sgml"> -<upstream> - <maintainer status="inactive"> - <email>foo@bar.bar</email> - <name>Foo Bar</name> - </maintainer> - <maintainer status="active"> - <email>foo@gentoo.org</email> - <name>Foo Gentoo</name> - </maintainer> - <changelog>http://foo.bar/changelog.txt</changelog> - <doc lang="en">http://foo.bar/doc/index.html</doc> - <doc lang="de">http://foo.bar/doc/index.de.html</doc> - <bugs-to>https://bugs.foo.bar</bugs-to> - <remote-id type="freshmeat">foobar</remote-id> - <remote-id type="sourceforge">foobar</remote-id> -</upstream> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> +<pkgmetadata> + <maintainer type="project"> + <email>base-system@gentoo.org</email> + <name>Gentoo Base System</name> + </maintainer> + <use> + <flag name="apng">support unofficial APNG (Animated PNG) spec</flag> + </use> + <upstream> + <remote-id type="cpe">cpe:/a:libpng:libpng</remote-id> + <remote-id type="sourceforge">apng</remote-id> + </upstream> + <slots> + <slot name="0"> + For building against. This is the only slot + that provides headers and command line tools. + </slot> + <slot name="1.2"> + For binary compatibility, provides libpng12.so.0 only. + </slot> + <slot name="1.5"> + For binary compatibility, provides libpng15.so.15 only. + </slot> + <subslots>Reflect ABI compatibility for libpng.so.</subslots> + </slots> +</pkgmetadata> </codesample> </body> +</subsubsection> </subsection> - +<subsection> +<title>Maintainer-needed</title> +<body> <p> -All new packages <b>must</b> include a <c>metadata.xml</c> file. That file -should specify at least one herd or one maintainer. It is however recommended, -if at all possible, to find a herd willing to be listed. +Maintainer-needed ("orphaned") packages have no maintainers responsible for +them. Per +<uri link="https://www.gentoo.org/glep/glep-0067.html#case-of-maintainer-needed-packages"> +GLEP 67</uri>, these packages must not contain any <c><maintainer></c> +subtags under <c><pkgmetadata></c> in their <c>metadata.xml</c>. A strict +test for this condition would be: </p> -<p> -If a package has no maintainer, <c>maintainer-needed@gentoo.org</c> -should be listed as the maintainer. -</p> +<pre> +[[ $(xmllint --xpath "count(/pkgmetadata/maintainer)" metadata.xml) -eq 0 ]] +</pre> <p> -To easily create <c>metadata.xml </c>files, you can use -<c>app-portage/metagen</c>. There is also a skeleton file, see -<c>/usr/portage/skel.metadata.xml</c>. +By convention, a comment line containing the string <c>maintainer-needed</c> +is inserted. Other tags which are relevant to the package may be +present in the metadata. Bugs for these packages must be assigned to +<c>maintainer-needed@gentoo.org</c>. The QA team periodically generates the +<uri link="https://qa-reports.gentoo.org/output/maintainer-needed.html"> +orphaned packages list</uri> along with their corresponding bugs as +part of the QA reports. </p> -<p> -Commits of package metadata files are handled by <c>repoman</c>. You -should ensure that you have <c>dev-libs/libxml2</c> installed so that -the XML can be validated. -</p> +<codesample lang="sgml"> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE pkgmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> +<pkgmetadata> + <!-- maintainer-needed --> + <upstream> + <maintainer status="active"> + <email>rasmus@alum.mit.edu</email> + <name>Matt Rasmussen</name> + </maintainer> + <doc lang="en">http://keepnote.org/manual/</doc> + <bugs-to>https://code.google.com/p/keepnote/issues/list</bugs-to> + </upstream> + <longdescription lang="en"> + KeepNote is a note taking application. With KeepNote, you can + store your class notes, TODO lists, research notes, journal entries, + paper outlines, etc in a simple notebook hierarchy with rich-text + formatting, images, and more. Using full-text search, you can + retrieve any note for later reference. + </longdescription> +</pkgmetadata> +</codesample> +</body> +</subsection> </section> <section> -<title>Category Metadata</title> +<title>Category metadata</title> <body> <p> For categories, <c>metadata.xml</c> specifies a long description (in -English and optionally in other languages). The format is specified -formally in <uri link="https://wiki.gentoo.org/wiki/GLEP:34"> -GLEP 34</uri>, and the character set <b>must</b> be UTF-8 as specified -by <uri link="https://wiki.gentoo.org/wiki/GLEP:31">GLEP -31</uri>. A typical example: +English and optionally in other languages). A typical example: </p> <codesample lang="sgml"> - <?xml version="1.0" encoding="UTF-8"?> - <!DOCTYPE catmetadata SYSTEM "http://www.gentoo.org/dtd/metadata.dtd"> - <catmetadata> - <longdescription lang="en"> - The app-vim category contains plugins and syntax file - packages for the Vim text editor. - </longdescription> - <longdescription lang="de"> - Die Kategorie app-vim enthält Plugins und Syntax-Pakete - für den Vim Texteditor. - </longdescription> - </catmetadata> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE catmetadata SYSTEM "https://www.gentoo.org/dtd/metadata.dtd"> +<catmetadata> + <longdescription lang="en"> + The app-vim category contains plugins and syntax file + packages for the Vim text editor. + </longdescription> + <longdescription lang="de"> + Die Kategorie app-vim enthält Plugins und Syntax-Pakete + für den Vim Texteditor. + </longdescription> +</catmetadata> </codesample> <p> @@ -531,13 +715,24 @@ is currently: <pre> xmllint --noout --valid metadata.xml -glep31check metadata.xml -cvs commit -m "Adding category metadata.xml for my-category" metadata.xml +git add metadata.xml +git commit --gpg-sign </pre> -</body> -</section> +<p> +The commit message should be formatted properly. +A sample commit is shown below: +</p> + +<pre> +commit db359439bcd52f5a7f20d2332ab62feb16657504 +Author: Alexis Ballier <aballier@gentoo.org> +Date: Tue Sep 22 10:47:49 2015 +0200 + + dev-ros: Add metadata.xml for the category. +</pre> </body> +</section> </chapter> </guide> diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml index 0be488c..862910c 100644 --- a/ebuild-writing/misc-files/patches/text.xml +++ b/ebuild-writing/misc-files/patches/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/misc-files/patches/"> <chapter> <title>Patches</title> @@ -18,32 +18,43 @@ is conventional. Patches are best named <c>${P}-what-it-does.patch</c> (or description of what the patch is for. If the patch is to fix a specific bug, it is often useful to add in the bug number <d/> for example, <c>vim-7.0-cron-vars-79981.patch</c>. If the patch is pulled from -upstream's CVS / SVN repository, it can help to include the revision +upstream's VCS repository, it can help to include the revision number in the patch name as a suffix to the version part <d/> <c>fluxbox-0.9.12-3860-menu-backups.patch</c>. </p> <p> -Larger patches should be <uri link="::general-concepts/mirrors/#suitable-download-hosts">mirrored</uri>, -preferrable on the Gentoo Infrastructure. When mirroring patches, choosing a -name that will not cause conflicts is important — the <c>${P}</c> -prefix is highly recommended here. Mirrored patches are often -compressed with <c>bzip2</c>. Remember to list these patches in -<c>SRC_URI</c>. +Larger patches should be +<uri link="::general-concepts/mirrors/#Suitable download hosts"> +mirrored</uri>, preferably on the Gentoo Infrastructure. When +mirroring patches, choosing a name that will not cause conflicts is +important — the <c>${P}</c> prefix is highly recommended +here. Mirrored patches are often compressed with <c>xz</c> or +<c>bzip2</c>. Remember to list these patches in <c>SRC_URI</c>. Please +see <uri link="::ebuild-maintenance/new-ebuild/#The files directory"/> +for more information. </p> <note> Patches included in <c>${FILESDIR}</c> should never be compressed. </note> +<warning> +Starting from EAPI=6, the patch strip level defaults to <c>-p1</c>. +Although it can be overridden with a <c>eapply -p<strip_level></c> +command, it is highly recommended to adapt the patch itself to work +with the <c>-p1</c> default. +</warning> + <p> If a package requires many patches, even if they are individually small, it is often best to create a patch tarball to avoid cluttering up the tree too much. </p> +</body> <section> -<title>Patch Descriptions</title> +<title>Patch descriptions</title> <body> <p> It is possible to include a description with a patch. This is often @@ -57,8 +68,8 @@ later. Good things to include in comments are: What the patch actually does. Bug numbers are good here. </li> <li> - Where the patch came from. Is it an upstream CVS/SVN pull, - something from Bugzilla, something you wrote? + Where the patch came from. For example, is it from an upstream VCS, + something from Bugzilla, or something you wrote? </li> <li> Whether the patch has been sent upstream, if applicable. @@ -85,8 +96,8 @@ from the <c>vim</c> patch tarball: <pre> # Detect Gentoo apache files properly. Gentoo bug 83565. ---- runtime/filetype.vim.orig 2005-03-25 01:44:12.000000000 +0000 -+++ runtime/filetype.vim 2005-03-25 01:45:15.000000000 +0000 +--- a/runtime/filetype.vim ++++ b/runtime/filetype.vim @@ -93,6 +93,9 @@ " Gentoo apache config file locations (Gentoo bug #76713) au BufNewFile,BufRead /etc/apache2/conf/*/* setf apache @@ -102,27 +113,347 @@ from the <c>vim</c> patch tarball: </section> <section> -<title>Adding Patches to the tree</title> +<title>Conditional patching</title> <body> <p> -When adding a patch to the tree be sure to check that the patch doesn't have -CVS keywords in it that will be expanded (such as <c>$Id$</c>). If the patch -contains these, it will break manifests unless you add it to the tree -correctly. In the case that it does have the keywords, you should add it by -doing: +Patching is ideally only done to make the package in question build properly, +and should not be done to modify the runtime behaviour of the package. This is +what USE flags and features of the package are for. As such, it is preferable to +apply patches unconditionally and avoid conditional patching. +</p> + +<p> +There are a number of reasons to avoid conditional patching: +</p> + +<ul> + <li> + It may go unnoticed that a patch fails to apply, if a package is not being + tested with a given flag + </li> + <li> + More variance is introduced and problems with a package can become much more + difficult to debug + </li> + <li> + Patches should preferably be upstreamed, but conditional patches cannot + </li> +</ul> + +<p> +Consider the following example <c>src_prepare()</c> implementation: +</p> + +<codesample lang="ebuild"> +src_prepare() { + if use threads; then + PATCHES+=( "${FILESDIR}"/${P}-mt.patch ) + fi + default +} +</codesample> + +<p> +As this patch is only applied when <c>USE="threads"</c> is set, any developer +creating new versions of this package might not detect whether the patch applies +successfully if they don't test with the same flag. +</p> + +<p> +Although conditional patching is discouraged it can be unavoidable and as such, +it is not considered a banned practice, but, to the extent possible, patches +should be written such that they affect behaviour correctly based on e.g. build +time definitions and configuration options rather than USE flags directly. This +allows them to be applied unconditionally. +</p> + +</body> +</section> + +<section> +<title>Clean patch howto</title> +<body> + +<p> +"Clean patch" does not refer to the patch itself (as in the changes it makes to +the source code). It refers to all the metadata that exists in the patch to +make it "maintainable". +</p> + +</body> + +<subsection> +<title>Why</title> +<body> + +<p> +This may take more effort "up front", but the amount of effort that it saves +for everyone else in the future more than makes up for it. This refers to other +distributions or upstream maintainers who read the patch, or future Gentoo +maintainers. By keeping all patches "clean", people can quickly and easily +assess a patch without searching through many other files. +</p> + +</body> +</subsection> + +<subsection> +<title>File naming</title> +<body> + +<p> +Your patch name should be short and to the point. When doing a file listing +(e.g., <c>ls files/</c>), it's a lot easier to be able to scan for relevant +patches when they have good keywords in their file names. +</p> + +<p> +It should also include the package name and the version it was written against. +This way, people searching for patches or who happen to just stumble across the +file itself have a clue as to what it's for. Stripping out the <c>${PN}</c> +(and to a lesser extent, the <c>${PV}</c>) makes the filename significantly +less useful. The fact the files are typically stored in +<c>${CATEGORY}/${PN}/files/</c> is irrelevant, because the patch may be used +outside Gentoo. +</p> + +</body> +</subsection> + +<subsection> +<title>How</title> +<body> + +<p> +Here's a check list of things to keep in the patch header: +</p> + +<ul> + <li> + External references + <ul> + <li>Upstream mailing archives</li> + <li>Upstream bug reports</li> + <li>Upstream commit links</li> + <li>Upstream ChangeLog entries</li> + <li>Gentoo bug reports</li> + </ul> + </li> + <li> + Short/medium explanation + <ul> + <li>Why is the patch needed?</li> + <li>What is it fixing?</li> + <li>Why is it fixing it the way it is?</li> + <li>Proposal for better fixes in the future?</li> + <li>Is it a stop gap measure (workaround)?</li> + <li>How was it regression tested?</li> + <li> + Examples of before/after behaviour + <ul> + <li>How to reproduce bug without patch</li> + <li>How to show bug is fixed after patch</li> + <li> + Maybe upstream fixed it in a different way, so this test can be + used to show that the patch is no longer needed with newer versions + </li> + </ul> + </li> + </ul> + </li> + <li> + Status + <ul> + <li>Was it merged/rejected/postponed/etc. upstream?</li> + <li>Is it distribution-specific?</li> + </ul> + </li> + <li> + Attribution + <ul> + <li>Who found the bug?</li> + <li>Who fixed the bug?</li> + <li>Who wrote the patch?</li> + <li>Who tested the patch?</li> + <li>Who gave advice on the patch?</li> + </ul> + </li> +</ul> + +<p> +All this information should be <e>in the patch itself</e>. It should never be +found in something like the ebuild. If you really want to put a comment next +to a patch in an ebuild, then this is about the only thing that is OK +(where 93671 is the Gentoo bug number): +</p> + +<codesample lang="ebuild"> +PATCHES=( + "${FILESDIR}"/${P}-dont-umask.patch #93671 +) +</codesample> + +<p> +When documenting these things, it might be useful to use RFC822/Git-style tags +to format the metadata. So when documenting the author, use: +</p> + +<pre> +From: Nice Person <foo@cow.example.com> +</pre> + +<p> +Or when documenting relevant URLs, use something like: +</p> + +<pre> +Bug: https://upstream.example.com/12345 +Bug: https://bugs.gentoo.org/9889 +</pre> + +<p> +And if you want to note your copyright signoff, slap on a Signed-off-by tag: </p> <pre> -cvs add -ko files/${P}-the-cool-patch.patch +Signed-off-by: Diligent Developer <larry@gentoo.org> </pre> <p> -<c>-ko</c> disables keyword expansion for that specific file. If it doesn't -have keywords in it, then you can add it normally without the extra argument. +Finally, your patch should be clear of useless cruft. If it was not taken +straight from an upstream SCM (<c>git format-patch</c> or <c>svn diff -r #</c> +or <c>cvs diff -r 1.123 -r 1.124</c>), then the metadata is useless. So delete +it. This refers to things like the diff command used to produce the patch, +or the timestamps on the files, local revision info, or other similar spam. +Note that the context info (the stuff that comes after the <c>@@</c>) should +be left, as that can be invaluable when applying patches to later versions. +For example: </p> + +<pre> +@@ -80,6 +82,7 @@ case $sys in + ^^^^^^^^^^^^ keep this part +</pre> + +<p> +Extra points if you make the filename in the <c>---</c>/<c>+++</c> section +consistent and sane. That is, remove different leading <c>backup/paths/</c> +and <c>.orig</c>/<c>.new</c> suffixes. Your patch should be in the <c>-p1</c> +format because this tends to be much more standard than any other <c>-p#</c>. +It is also what <c>eapply</c> understands by default. A good suggestion is to +use either <c>a/</c> and <c>b/</c> (as in <c>git format-patch</c>) or the +package name/version as the leading portion that gets stripped. +</p> + +<p> +Also note that <c>patch</c> uses the timestamp info in order to remove empty +files automatically. Alternatively, you can specify the <c>-E</c> option with +<c>eapply</c> if you want to remove an empty file. +</p> + +<p> +Removed lines should not appear in the patch because they are commented <d/> +just remove them entirely. Patches show removed lines by prefixing them with +a <c>-</c>, so no information is lost by simply deleting lines rather than +commenting them out (which adds noise). This makes the patch shorter and +more readable. +</p> + +<p> +The following function (for your interactive shell, not for the ebuild) will +help deleting these things: +</p> + +<codesample lang="ebuild"> +scrub_patch() { + sed -i \ + -e '/^index /d' \ + -e '/^new file mode /d' \ + -e '/^Index:/d' \ + -e '/^=========/d' \ + -e '/^RCS file:/d' \ + -e '/^retrieving/d' \ + -e '/^diff/d' \ + -e '/^Files .* differ$/d' \ + -e '/^Only in /d' \ + -e '/^Common subdirectories/d' \ + -e '/^deleted file mode [0-9]*$/d' \ + -e '/^+++/s:\t.*::' \ + -e '/^---/s:\t.*::' \ + "$@" +} + +scrub_patch some-patch-you-found.patch +</codesample> + </body> -</section> +</subsection> + +<subsection> +<title>Examples</title> +<body> + +<p> +This shows a simple explanation and a URL for more info (this patch could do +with some attribution however). No metadata exists from running the <c>diff</c> +command (timestamps, etc.). +</p> + +<pre><!-- man-1.6d-fbsd.patch --> +Fixes compilation in FreeBSD. +https://bugs.gentoo.org/138123 + +--- man-1.6d/gencat/genlib.c ++++ man-1.6d/gencat/genlib.c +@@ -54,7 +54,7 @@ + #include <unistd.h> + #endif + +-#ifndef __linux__ ++#if !defined(__linux__) && !defined(__FreeBSD__) + #include <memory.h> + static int bcopy(src, dst, length) + char *src, *dst; +</pre> + +<pre><!-- util-linux-2.12q-dont-umask.patch --> +Don't force umask to 022 or the -o umask option doesn't work. +Patch by Daniel Drake. +https://bugs.gentoo.org/93671 + +--- mount/mount.c ++++ mount/mount.c +@@ -1491,8 +1491,6 @@ main(int argc, char *argv[]) { + if ((p = strrchr(progname, '/')) != NULL) + progname = p+1; + +- umask(022); +- + /* People report that a mount called from init without console + writes error messages to /etc/mtab + Let us try to avoid getting fd's 0,1,2 */ +</pre> + +<pre><!-- iproute2-2.6.25.20080417-build.patch --> +Don't let target flags bleed into build flags. +Fix by Bertrand Jacquin. +https://bugs.gentoo.org/226035 + +--- netem/Makefile ++++ netem/Makefile +@@ -2,6 +2,7 @@ DISTGEN = maketable normal pareto paretonormal + DISTDATA = normal.dist pareto.dist paretonormal.dist experimental.dist + + HOSTCC ?= $(CC) ++CCOPTS = $(CBUILD_CFLAGS) + LDLIBS += -lm + + all: $(DISTGEN) $(DISTDATA) +</pre> + </body> +</subsection> +</section> </chapter> </guide> diff --git a/ebuild-writing/misc-files/text.xml b/ebuild-writing/misc-files/text.xml index 31f1421..3fe6026 100644 --- a/ebuild-writing/misc-files/text.xml +++ b/ebuild-writing/misc-files/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/misc-files/"> <chapter> -<title>Miscellaneous Files</title> +<title>Miscellaneous files</title> <body> <p> @@ -18,6 +18,5 @@ This section contains some notes on various miscellaneous files. </chapter> <include href="metadata/"/> -<include href="changelog/"/> <include href="patches/"/> </guide> diff --git a/ebuild-writing/text.xml b/ebuild-writing/text.xml index 1107a9b..0817a04 100644 --- a/ebuild-writing/text.xml +++ b/ebuild-writing/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/"> <chapter> -<title>Ebuild Writing</title> +<title>Ebuild writing</title> <body> <p> @@ -29,6 +29,6 @@ with some general notes and extended examples. <include href="using-eclasses/"/> <include href="functions/"/> <include href="misc-files/"/> +<include href="user-submitted/"/> <include href="common-mistakes/"/> -<include href="ebuild-maintenance/" /> </guide> diff --git a/ebuild-writing/use-conditional-code/text.xml b/ebuild-writing/use-conditional-code/text.xml index 3db3a40..cb818a2 100644 --- a/ebuild-writing/use-conditional-code/text.xml +++ b/ebuild-writing/use-conditional-code/text.xml @@ -1,7 +1,7 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/use-conditional-code/"> <chapter> -<title>USE Flag Conditional Code</title> +<title>USE flag conditional code</title> <body> <p> @@ -15,35 +15,35 @@ readable. <p> The <c>if [ "`use foo`" ]</c> and <c>if [ -n "`use foo`" ]</c> forms which are -occasionally seen in older code must <b>not</b> be used. +occasionally seen in older code must <b>not</b> be used. This is because, since Portage 2.1, the 'use' Portage helper does not produce any output when the use flag is enabled or disabled so the [ "`use foo`" ] statement is pretty much identical to [ "" ] which always evaluates to false. </p> <note> <c>die</c> will not work as expected within a subshell, so code in the form <c>use foo && ( blah ; blah )</c> should be avoided in favour of a proper if -statement. See <uri link="::ebuild-writing/error-handling/#die and Subshells"/>. +statement. See <uri link="::ebuild-writing/error-handling/#die and subshells"/>. </note> <codesample lang="ebuild"> - # USE conditional blocks... - if use livecd ; then - # remove some extra files for a small livecd install - rm -fr "${vimfiles}"/{compiler,doc,ftplugin,indent} - fi + # USE conditional blocks... + if use livecd ; then + # remove some extra files for a small livecd install + rm -fr "${vimfiles}"/{compiler,doc,ftplugin,indent} || die + fi - # Inverse USE conditional blocks... - if ! use cscope ; then - # the --disable-cscope configure arg doesn't quite work properly, - # so sed it out of feature.h if we're not USEing cscope. - sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope" - fi + # Inverse USE conditional blocks... + if ! use cscope ; then + # the --disable-cscope configure arg doesn't quite work properly, + # so sed it out of feature.h if we're not USEing cscope. + sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope" + fi - # USE conditional statements... - use ssl && epatch "${FILESDIR}/${P}-ssl.patch" - use sparc && filter-flags -fomit-frame-pointer + # USE conditional statements... + use ssl && eapply "${FILESDIR}/${P}-ssl.patch" + use sparc && filter-flags -fomit-frame-pointer - # Inverse USE conditional statements... - use ncurses || epatch "${FILESDIR}/${P}-no-ncurses.patch" + # Inverse USE conditional statements... + use ncurses || eapply "${FILESDIR}/${P}-no-ncurses.patch" </codesample> <p> diff --git a/ebuild-writing/user-submitted/text.xml b/ebuild-writing/user-submitted/text.xml new file mode 100644 index 0000000..9e2bc1c --- /dev/null +++ b/ebuild-writing/user-submitted/text.xml @@ -0,0 +1,67 @@ +<?xml version="1.0" encoding="UTF-8"?> +<guide self="ebuild-writing/user-submitted/"> +<chapter> +<title>User-submitted ebuilds</title> + +<body> + +<p> +User-submitted ebuilds should never be blindly trusted and should +always be well-tested and audited before being committed to the tree. +The developer committing the user-submitted ebuild is vouching that +the ebuild meets all Gentoo Linux development standards. +</p> + +<p> +The user-submitted ebuild must not contain custom headers like this: +</p> + +<pre> +# Ebuild updated by: me <me@example.com> +</pre> + +<p> +Such information should be included in the git commit message instead. +The use of tags such as <c>Suggested-By:</c> or <c>Reported-By:</c> in +the commit message, as explained in the +<uri link="::ebuild-maintenance/git/#Git commit message format"> +commit message format section</uri>, is highly encouraged. +Note that ebuilds received in the form of git patches or pull requests +will have the user as the commit author by default, in which case +including the user information in the commit message explicitly +may not be necessary. If that is not the case, you may wish to use +git commit's <c>--author</c> parameter to explicitly give them credit. +</p> + +<p> +Developers must check for a valid <c>Signed-off-by</c> line either within +the provided patches by a user or within a comment on e.g. Bugzilla. +See <uri link="::general-concepts/copyright-policy/#Certificate of Origin"/> +for details. +</p> + +<p> +Users should be encouraged to submit diffs to an existing ebuild if they +are submitting an upgrade. Doing this will help to avoid re-introduction +of previously fixed bugs into "new" ebuilds. When not working from a +diff but from a complete user-submitted ebuild, the <c>diff -u</c> command +should be used to see what has changed; attention should be payed for +anything from the current ebuild that should appear in the new ebuild, +or anything in the new ebuild that should be fixed or removed. +</p> + +<p> +In general, it is preferable to have the user do the work required to +get their ebuild up to par, so that they can learn from their mistakes +and submit cleaner ebuilds in the future. Be sure to be thankful for any +submission, even if it isn't very good. Be polite but honest <d/> if an +ebuild isn't usable, the user can be told in a way that does not insult +their current ebuild-writing abilities. Remember that the user who +submitted that broken ebuild may be a skilled and productive member of +our project in the future <d/> that is, if they receive the right amount +of encouragement and support and continue to improve in their abilities. +</p> + +</body> +</chapter> +</guide> diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml index 5030318..679d028 100644 --- a/ebuild-writing/users-and-groups/text.xml +++ b/ebuild-writing/users-and-groups/text.xml @@ -1,89 +1,323 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/users-and-groups/"> <chapter> -<title>Users and Groups</title> +<title>Users and groups</title> <body> <p> -If your ebuild requires a user or group to be added for a daemon, for example, -this should be performed via the functions available in <c>user.eclass</c>. -Regardless of whether you are adding a group or a user, this should be performed -in the <c>pkg_setup</c> function: <c>pkg_setup</c> is sandbox-safe, -is called before the compile process so a build that requires the user to exist will -have it, and is also called for both binary and source packages. You may also -use the <c>pkg_preinst</c> or <c>pkg_postinst</c> functions for user creation, if -the user is not required during or before <c>src_install</c>. +Creating users and groups is governed by <uri +link="https://gentoo.org/glep/glep-0081.html">GLEP 81</uri>. It is implemented +via <c>acct-user</c> and <c>acct-group</c> eclasses. New users and groups +are created as packages respectively in <c>acct-user</c> and <c>acct-group</c> +categories. +</p> + +<p> +First, check the <uri link="https://api.gentoo.org/uid-gid.txt">UID/GID +assignment list</uri> and choose a free UID/GID in the range between 101 and +749. If you are adding a user and a group with the same name, use the same +number for their UID and GID, respectively. When in doubt, take the next free +number from 101 upwards. The helper script <c>./bin/used_free_uidgids.sh</c> +available in the data/api.git repository can be used to find the next available +UID or GID. +</p> + +<p> +Add your new user(s) and group(s) to the <c>uid-gid.txt</c> file +located in the +<uri link="https://gitweb.gentoo.org/data/api.git">data/api.git</uri> +repository and push them before adding the actual packages. +This counts as reserving the identifiers and will prevent collisions. +Afterwards, you can push the new ebuilds. +</p> + +<p> +The historical way of using <c>user.eclass</c> directly is now deprecated +and must not be used for new packages. </p> </body> <section> -<title>Adding Groups</title> +<title>Group ebuilds</title> <body> <p> -To add a group, use the <c>enewgroup</c> function: +Group ebuilds are placed in <c>acct-group</c> category, with the package name +matching the group name. The following ebuild for <c>acct-group/suricata</c> +can be used as a template for writing group ebuilds: </p> <pre> -enewgroup <name> [gid] +# Copyright 2019-2021 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +EAPI=7 + +inherit acct-group + +DESCRIPTION="Group for Suricata IDS" +ACCT_GROUP_ID=477 </pre> <p> -By default the next available group ID is selected. To set a specfic group ID, -pass it an extra argument to <c>enewgroup</c>. +<c>ACCT_GROUP_ID</c> must be set to the requested GID. </p> -<note> -Group IDs should rarely be hardcoded. If this is the case, you should -probably check first on gentoo-dev. -</note> - </body> </section> <section> -<title>Adding Users</title> +<title>User ebuilds</title> <body> <p> -To add a user, use the <c>enewuser</c> function: +User ebuilds are placed in <c>acct-user</c> category, with the package name +matching the user name. The following ebuild for <c>acct-user/suricata</c> +can be used as a template for writing user ebuilds: </p> <pre> -enewuser <user> [uid] [shell] [homedir] [groups] [params] +# Copyright 2019-2021 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +EAPI=7 + +inherit acct-user + +DESCRIPTION="User for Suricata IDS" +ACCT_USER_ID=477 +ACCT_USER_GROUPS=( ${PN} ) + +acct-user_add_deps </pre> <p> -By default, both <c>enewuser</c> and <c>enewgroup</c> allocate the next available user -ID or group ID to the new user or group - if not, you explicitly have to specify -one. +<c>ACCT_USER_ID</c> must be set to the requested GID. <c>ACCT_USER_GROUPS</c> +should list all the groups user belongs to, the primary group first. All +the other keys are optional. +</p> + +<p> +<c>ACCT_USER_SHELL</c> can be used to set the shell for the user. If unset, +the best system equivalent of nologin is used. <c>ACCT_USER_HOME</c> specifies +the home directory, with <c>/dev/null</c> being the default. +<c>ACCT_USER_HOME_OWNER</c> can be used to override the ownership of the home +directory, and <c>ACCT_USER_HOME_PERMS</c> to override the default permissions. +The defaults are the user and primary group for the owner, and 0755 for the +permissions. +</p> + +<important> +Whenever possible, the default shell and home directory should be +used. The rationale for this is explained below. +</important> + +<p> +You should embark upon a GLEP81 migration like an EAPI +update. Rather than simply copy your user's settings into an +<c>acct-user</c> package, you should take the opportunity to +re-evaluate your user's name, shell, home directory, and its +permissions. Our GLEP 81 implementation will reveal many user +management issues that were allowed to fester in the past. +</p> +</body> + +<subsection> +<title>Choosing a shell</title> +<body> +<p> +In most cases, the default shell (that is, no shell) should be +used. Services can still be started as a user who has no shell, and +daemons are able to drop privileges to a user who has no shell. If +necessary, the administrator can override a user's default shell with +<c>su -s <shell> <username></c>. This is sufficient for +testing, management of SSH credentials, and for initial configuration +in an ebuild's <c>pkg_config</c> phase. +</p> +<p> +An obvious exception to this rule is if a human being will need to log +into the account interactively, as is the case with the <c>root</c> +user. Other exceptions certainly exist, but should be evaluated +case-by-case. In other words, if you haven't checked, don't set your +user's shell to <c>/bin/bash</c> because you think he <e>might</e> +need it. +</p> +<p> +The goal here is twofold. First, the principle of least privilege says +that if a user doesn't need a real shell, he shouldn't have one. And +along those same lines, not having a shell gives the system +administrator some peace of mind: he doesn't have to be as concerned +with whether or not that user has a password (and how strong it is), +or whether or not its filesystem permissions are all set correctly, or +whether or not it can log in via SSH, et cetera. +</p> +</body> +</subsection> + +<subsection> +<title>Choosing a home directory</title> +<body> +<p> +In most cases, the default home directory (that is, no home directory) +should be used. GLEP81 changed two aspects of user management with +respect to home directories: +</p> + +<ol> + <li> + Creating a user can now modify the permissions on an existing + directory. Should the need arise, this is necessary for a new + version of an <c>acct-user</c> package to be able to fix the + ownership and permissions of its home directory. + </li> + <li> + All user data aside from the username became non-local to ebuilds + that depend on that user. This is merely a side-effect of moving + the user creation out of the client package, and into a separate + <c>acct-user</c> package. + </li> +</ol> + +<p> +The first item means that you should be conservative when choosing a +home directory. If at all possible, avoid choosing a home directory +that is used by another package. In particular, no two +<c>acct-user</c> packages should use the same home directory. At best, +the ownership and permissions on a shared home directory would need to +be kept synchronized between all packages that share it. At worst, one +package goes out-of-sync and introduces a security hole for the others +who no longer have the expected permissions. +</p> +<p> +The second item means that if your package requires a user, you can +no longer be sure of that user's home directory or its ownership and +permissions. If your package requires a directory to be owned and +writable by some user, then your package's ebuild should create that +directory and ensure that it is writable by the user. In other +words, you should not rely on the directory being created +"transitively" by a dependency, even if that dependency is an +<c>acct-user</c> package. +</p> +<p> +In summary, +</p> +<ul> + <li> + Avoid using an <c>ACCT_USER_HOME</c> that belongs to another + package. + </li> + <li> + No two acct-user packages should define the same + <c>ACCT_USER_HOME</c>. + </li> + + <li> + If for example your package's configuration needs <username> + to be able to write to <c>/var/lib/<username></c>, then your + package's ebuild should create that directory and set its + ownership and permissions. Barring any other considerations, the + corresponding <c>acct-user</c> package should leave + <c>ACCT_USER_HOME</c> at its default (empty) value; setting + <c>ACCT_USER_HOME=/var/lib/<username></c> creates + unnecessary duplication and risks desynchronizing the permissions. + </li> +</ul> +</body> +</subsection> + +<subsection> +<title>Choosing home directory ownership</title> +<body> +<p> +In most cases, the default home directory ownership is correct. If a +non-default home directory is needed at all, then it should be +writable by its user and giving ownership of it to someone else would +prevent that. Being unwritable indicates that a shared and potentially +sensitive location was chosen. Moreover, the fact that the home +directory is not writable suggests that the default home directory +(which is also not writable) would suffice instead; the home directory +guidelines explain why the default is preferable in that case. For +example, setting <c>ACCT_USER_HOME_OWNER="root:root"</c> is suspicious +because it appears intended to "undo" the ownership changed by your +user package, and that would only be necessary if the path in question +is used by some other package. +</p> +</body> +</subsection> + +<subsection> +<title>Choosing home directory permissions</title> +<body> +<p> +In many cases, the default home directory permissions (0755) will +suffice. But, if your package will work with mode 0700 or 0750, then +those are preferable. This is the principle of least privilege +again. If your package works with a non-writable home directory, then +you should probably be using the default of <e>no</e> home directory! +</p> +<warning> +The world-writable bit should never be set in +<c>ACCT_USER_HOME_PERMS</c>. This should never be necessary, and is +usually exploitable. +</warning> +</body> +</subsection> + +<subsection> +<title>Epilogue</title> +<body> +<p> +These suggestions are not rules and are not written in stone, except +perhaps for the world-writable warning. There are packages in the tree +that <c>chroot()</c> to <c>$HOME</c>, and require that directory to be +owned by <c>root:root</c> for security reasons. In cases like that, +it's impossible to avoid implicitly tying the user to the package that +needs it via the home directory, and the best you can do is attempt to +ensure that the users and paths are unique so that no conflicts arise. +</p> + +<p> +Unless your package is exceptional, though, following these guidelines +will minimize the potential for problems down the road. </p> +</body> +</subsection> +</section> + +<section> +<title>Utilizing users and groups in packages</title> +<body> <p> -Arguments for <c>enewuser</c> must be passed in the order as shown above: if you do -not want to specify a fixed user ID however but do want to set a specific shell, -for example, use <c>-1</c> for the <c>uid</c> parameter. The same applies for any other -parameter where you want to keep the default setting. +In order to make your package install specific users and groups, specify them +as dependencies. Accounts needed at build time must be included +in <c>DEPEND</c>, and accounts needed at runtime must be included +in <c>RDEPEND</c>. </p> <p> -Groups for the <c>groups</c> argument should be separated by a comma (<c>,</c>) and -wrapped correctly, for example: +For example, an ebuild requiring the user and group <c>foo</c> at runtime would +specify: </p> <pre> -enewuser frozd -1 -1 -1 "backup,frozd" +RDEPEND=" + acct-user/foo + acct-group/foo" </pre> <p> -Finally, any data left over for the <c>params</c> argument is passed directly to -useradd. +This would also be sufficient if ownership of installed files were set +in <c>pkg_preinst</c>. However, if the ebuild needs the user and group +to be present at build-time already, it would specify: </p> -<note> -User IDs should rarely be hardcoded. If this is the case, you should -probably check first on gentoo-dev. -</note> +<pre> +RDEPEND=" + acct-user/foo + acct-group/foo" +DEPEND="${RDEPEND}" +</pre> </body> </section> diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml index de9ec7f..7fa2c7b 100644 --- a/ebuild-writing/using-eclasses/text.xml +++ b/ebuild-writing/using-eclasses/text.xml @@ -1,73 +1,83 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/using-eclasses/"> <chapter> -<title>Using Eclasses</title> +<title>Using eclasses</title> <body> <p> An eclass is a collection (library) of functions or functionality that is shared between packages. See <uri link="::eclass-writing/" /> for the full story on what -eclasses can do, how they work and how to write them, and <uri link="::eclass-reference/">the eclass reference</uri> +eclasses can do, how they work and how to write them, and <uri link="::eclass-reference/"/> for documentation on various commonly used eclasses. This section only explains how to use an eclass which has already been written. </p> </body> <section> -<title>The <c>inherit</c> Function</title> +<title>The <c>inherit</c> function</title> <body> <p> To use an eclass, it must be 'inherited'. This is done via the <c>inherit</c> -function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement must -come at the top of the ebuild, <e>before</e> any functions. Conditional inherits are -illegal (except where the inheritance criteria are cache-constant <d/> see <uri -link="::general-concepts/portage-cache"/>). +function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement +must come at the top of the ebuild, <e>before</e> any functions. +Conditional inherits are illegal (except where the inheritance criteria are +cache-constant <d/> see <uri link="::general-concepts/portage-cache/"/>). </p> <p> -After inheriting an eclass, its provided functions can be used as normal. Here'san example ebuild, <c>foomatic-0.1-r2.ebuild</c>, which uses four eclasses: +When using <c>inherit</c>, it is best practice to sort the arguments (eclasses) +alphabetically. An exception is where the phases exported by an eclass are +affected by subsequent arguments. For example, <c>multilib-minimal.eclass</c> +mentions in its +<uri link="::eclass-reference/multilib-minimal.eclass/">documentation</uri> +that it should be inherited last because it overrides most phases. +</p> + +<p> +After inheriting an eclass, its provided functions can be used as +normal. Here's an example ebuild, <c>foomatic-0.1-r2.ebuild</c>, which +uses three eclasses: </p> <codesample lang="ebuild"> -# Copyright 1999-2010 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 -# $Header: $ -EAPI="2" +EAPI=7 -inherit eutils bash-completion flag-o-matic autotools +inherit autotools bash-completion-r1 flag-o-matic DESCRIPTION="Tool for foo" -HOMEPAGE="http://foomatic.sf.net" +HOMEPAGE="https://foomatic.sf.net" SRC_URI="mirror://sourceforge/${PN}/${P}.tar.gz" LICENSE="GPL-2" SLOT="0" -KEYWORDS="alpha ~amd64 ~x86 ~x86-fbsd" +KEYWORDS="alpha ~amd64 ~x86 ~x64-macos" -RDEPEND=">=sys-libs/ncurses-5.2 - >=sys-libs/readline-4.1" +RDEPEND="sys-libs/ncurses:0= + >=sys-libs/readline:0=" DEPEND="${RDEPEND}" src_prepare() { - epatch "${FILESDIR}/${P}-gentoo.patch" + eapply "${FILESDIR}/${P}-gentoo.patch" + eapply_user eautoreconf } src_configure() { - econf --sysconfdir=/etc/devtodo + econf --sysconfdir="${EPREFIX}"/etc/devtodo } src_compile() { replace-flags -O? -O1 - emake || die "emake failed" + default } src_install() { - emake DESTDIR="${D}" install || die "emake install failed" - dodoc AUTHORS ChangeLog README TODO || die "dodoc failed" - dobashcompletion "${FILESDIR}/${PN}.bash-completion" ${PN} + default + dobashcomp "${FILESDIR}/${PN}.bash-completion" ${PN} } </codesample> @@ -77,11 +87,11 @@ Note the <c>inherit</c> immediately after the header. </p> <p> -The <c>eutils</c> eclass (see <uri link="::eclass-reference/eutils.eclass/">eutils.eclass</uri>) is needed to get the -<c>epatch</c> function. The <c>flag-o-matic</c> eclass (see <uri -link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic.eclass</uri>) is needed for <c>replace-flags</c>, and -the <c>bash-completion</c> eclass (<uri link="::eclass-reference/bash-completion.eclass/">bash-completion.eclass</uri>) is used -to handle the bash completion file via <c>dobashcompletion</c> and <c>bash-completion_pkg_postinst</c>. +The <c>autotools</c> eclass (see <uri link="::eclass-reference/autotools.eclass/"/>) is needed to get the +<c>eautoreconf</c> function. The <c>flag-o-matic</c> eclass (see <uri +link="::eclass-reference/flag-o-matic.eclass/"/>) is needed for <c>replace-flags</c>, and +the <c>bash-completion-r1</c> eclass (<uri link="::eclass-reference/bash-completion-r1.eclass/"/>) is used +to handle the bash completion file via <c>dobashcomp</c>. </p> </body> diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index a31baa2..97e5995 100644 --- a/ebuild-writing/variables/text.xml +++ b/ebuild-writing/variables/text.xml @@ -1,4 +1,4 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="ebuild-writing/variables/"> <chapter> <title>Variables</title> @@ -12,12 +12,13 @@ which are of use throughout the ebuild. </body> <section> -<title>Predefined Read-Only Variables</title> +<title>Predefined read-only variables</title> <body> <p> -The following variables are defined for you. You must not attempt to set -them. +The following variables are defined for you. You must not attempt to +set them. Developers must not rely on package manager specific values +for these variables when writing ebuilds. </p> <table> @@ -63,15 +64,14 @@ them. <tr> <ti><c>FILESDIR</c></ti> <ti> - Path to the ebuild's <c>files/</c> directory, commonly used - for small patches and files. Value: - <c>"${PORTDIR}/${CATEGORY}/${PN}/files"</c>. + Path to the package's <c>files/</c> directory, commonly used for small + patches and other files. </ti> </tr> <tr> <ti><c>WORKDIR</c></ti> <ti> - Path to the ebuild's root build directory. Value: + Path to the ebuild's root build directory. For example: <c>"${PORTAGE_BUILDDIR}/work"</c>. </ti> </tr> @@ -79,21 +79,30 @@ them. <ti><c>T</c></ti> <ti> Path to a temporary directory which may be used by the - ebuild. Value: <c>"${PORTAGE_BUILDDIR}/temp"</c>. + ebuild. For example: <c>"${PORTAGE_BUILDDIR}/temp"</c>. </ti> </tr> <tr> <ti><c>D</c></ti> <ti> - Path to the temporary install directory. Value: + Path to the temporary install directory. For example: <c>"${PORTAGE_BUILDDIR}/image"</c>. </ti> </tr> <tr> + <ti><c>HOME</c></ti> + <ti> + Path to a temporary directory for use by any programs invoked by + an ebuild that may read or modify the home directory. For example: + <c>"${PORTAGE_BUILDDIR}/homedir"</c>. + </ti> + </tr> + <tr> <ti><c>ROOT</c></ti> <ti> - Path to the root directory. When not using <c>${D}</c>, - always prepend <c>${ROOT}</c> to the path. + The absolute path to the root directory into which the package is to be + merged. Only allowed in pkg_* phases. + See <uri link="::ebuild-writing/variables/#ROOT"/> </ti> </tr> <tr> @@ -103,13 +112,133 @@ them. fetched for the package are stored. </ti> </tr> + <tr> + <ti><c>EPREFIX</c></ti> + <ti> + The normalised offset-prefix path of an offset installation. + See <uri link="https://wiki.gentoo.org/wiki/Project:Prefix/Technical_Documentation"> + Gentoo Prefix Technical Documentation</uri> for more information. + </ti> + </tr> + <tr> + <ti><c>ED</c></ti> + <ti> + Shorthand for <c>${D%/}${EPREFIX}/</c>. + </ti> + </tr> + <tr> + <ti><c>EROOT</c></ti> + <ti> + Shorthand for <c>${ROOT%/}${EPREFIX}/</c>. + </ti> + </tr> + <tr> + <ti><c>SYSROOT</c></ti> + <ti> + (EAPI=7) The absolute path to the root directory containing build dependencies + satisfied by <c>DEPEND</c> + </ti> + </tr> + <tr> + <ti><c>ESYSROOT</c></ti> + <ti> + (EAPI=7) Shorthand for <c>${SYSROOT%/}${EPREFIX}/</c>. + </ti> + </tr> + <tr> + <ti><c>BROOT</c></ti> + <ti> + (EAPI=7) The absolute path to the root directory containing build dependencies + satisfied by <c>BDEPEND</c>, typically executable build tools. + </ti> + </tr> + <tr> + <ti><c>MERGE_TYPE</c></ti> + <ti> + The type of package that is being merged. Possible values are: + <c>source</c> if building and installing a package from source, + <c>binary</c> if installing a binary package previously built from + the ebuild, <c>buildonly</c> if building a binary package without + installing it. + </ti> + </tr> + <tr> + <ti><c>REPLACING_VERSIONS</c></ti> + <ti> + A whitespace-separated list of all versions (<c>PVR</c>) of this package + that are being replaced (uninstalled or overwritten) as a result of this + install. It is a list, not a single optional value, to handle pathological + cases such as installing <c>foo-2:2</c> to replace <c>foo-2:1</c> and + <c>foo-3:2</c>. Available in <c>pkg_preinst</c> and <c>pkg_postinst</c>. + </ti> + </tr> + <tr> + <ti><c>REPLACED_BY_VERSION</c></ti> + <ti> + The single version (<c>PVR</c>) of this package that is replacing the + version provided by this ebuild, if it is being uninstalled as part of + an install. An empty string otherwise, i.e., if it is being uninstalled + without replacement. Available in <c>pkg_prerm</c> and <c>pkg_postrm</c>. + </ti> + </tr> </table> </body> + +<subsection> +<title>ROOT</title> +<body> + +<p> +The idea behind <c>ROOT</c> is that one can build a system with +<c>ROOT=/somewhere</c> and then chroot into it or tar up +<c>/somewhere</c> as a system image. It is not designed to allow the +user to run <c>/somewhere/usr/bin/foo</c>. +</p> + +<p> +Ebuilds may reference <c>ROOT</c> only during <c>pkg_*</c> phases. It +can't be used correctly in <c>src_*</c> phases, since <c>ROOT</c> may +be different when merging a binary package. For example, a binary +package may be built with <c>ROOT=/</c> and then installed onto a +system using <c>ROOT=/somewhere</c>. +</p> + +<p> +When building a package, <c>ROOT</c> should not be used to satisfy the +required dependencies on libraries, headers files etc. Instead, the +files on the build system should be specified using <c>/</c>. +</p> + +<p> +In a cross compiling environment, ebuilds must not call any of the +binaries inside <c>ROOT</c> since they may not be executable on the +build system. +</p> + +<p> +Below is an example of an ebuild that uses <c>ROOT</c> in +<c>pkg_postinst()</c> to conditionally print an error message if an +old and obsolete configuration file still exists: +</p> + +<codesample lang="ebuild"> +pkg_postinst() { + if [[ -e ${ROOT}/etc/oldconfig ]]; then + ewarn "You still have the obsolete config file" + ewarn " ${ROOT}/etc/oldconfig." + ewarn "Please migrate your settings to ${ROOT}/etc/newconfig" + ewarn "and remove ${ROOT}/etc/oldconfig." + fi +} +</codesample> + +</body> +</subsection> </section> <section> -<title>Ebuild-defined Variables</title> +<title>Ebuild-defined variables</title> <body> <p> @@ -124,24 +253,27 @@ The following variables may or must be defined by every ebuild. <tr> <ti><c>EAPI</c></ti> <ti> - The EAPI. See <uri link="::ebuild-writing/eapi"/>. + The EAPI. See <uri link="::ebuild-writing/eapi/"/>. </ti> </tr> <tr> <ti><c>DESCRIPTION</c></ti> <ti> - A short (less than 80 characters) description of the package's + A short (not more than 80 characters) description of the package's purpose. Mandatory. </ti> </tr> <tr> <ti><c>HOMEPAGE</c></ti> <ti> - Package's homepage. Mandatory (except for virtuals). If you are - unable to locate an official one, try to provide a link to - <uri link="http://freshmeat.net">freshmeat.net</uri> or a similar - package tracking site. Never refer to a variable name in the - string; include only raw text. + Package's homepage(s). Mandatory (except for virtuals), accepts + multiple values. In some contexts, it is customary to provide + package tracker and/or code hosting links besides the main homepage + (e.g. PyPI link for Python packages, GitHub link when code can't + easily be found on homepage) for convenience. If no homepage for + the package is available, please set it to + <c>https://wiki.gentoo.org/wiki/No_homepage</c>. + Never refer to a variable name in the string; include only raw text. </ti> </tr> <tr> @@ -149,7 +281,7 @@ The following variables may or must be defined by every ebuild. <ti> A list of source URIs for the package. Can contain <c>USE</c>-conditional parts, see - <uri link="::ebuild-writing/variables#SRC_URI"/>. + <uri link="::ebuild-writing/variables/#SRC_URI"/>. </ti> </tr> <tr> @@ -157,20 +289,20 @@ The following variables may or must be defined by every ebuild. <ti> The package's license, corresponding exactly (including case) to a file in <c>licenses/</c>. Mandatory (except for virtuals). - See <uri link="::ebuild-writing/variables#LICENSE"/>. + See <uri link="::ebuild-writing/variables/#LICENSE"/>. </ti> </tr> <tr> <ti><c>SLOT</c></ti> <ti> The package's <c>SLOT</c>. Mandatory. - See <uri link="::ebuild-writing/variables#SLOT"/>. + See <uri link="::ebuild-writing/variables/#SLOT"/>. </ti> </tr> <tr> <ti><c>KEYWORDS</c></ti> <ti> - See <uri link="::ebuild-writing/variables#KEYWORDS"/> and + See <uri link="::ebuild-writing/variables/#KEYWORDS"/> and <uri link="::keywording/"/>. </ti> </tr> @@ -178,22 +310,29 @@ The following variables may or must be defined by every ebuild. <ti><c>IUSE</c></ti> <ti> A list of all <c>USE</c> flags (excluding arch flags, but - including <c>USE_EXPAND</c> flags) used within the ebuild. See - <uri link="::ebuild-writing/variables#IUSE"/>. + including <c>USE_EXPAND</c> flags) used within the ebuild. + See <uri link="::ebuild-writing/variables/#IUSE"/>. </ti> </tr> <tr> <ti><c>REQUIRED_USE</c></ti> <ti> - A list of assertions that must be met by the configuration of - <c>USE</c> flags to be valid for this ebuild. (Requires - <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.) + A list of assertions that must be met by the configuration of <c>USE</c> + flags to be valid for this ebuild. + See <uri link="::ebuild-writing/variables/#REQUIRED_USE"/>. + </ti> + </tr> + <tr> + <ti><c>PROPERTIES</c></ti> + <ti> + A space-delimited list of properties, with conditional syntax support. + <c>interactive</c>, <c>live</c>, and <c>test_network</c> are valid values. </ti> </tr> <tr> <ti><c>RESTRICT</c></ti> <ti> - A space-delimited list of portage features to restrict. + A space-delimited list of Portage features to restrict. Valid values are <c>fetch</c>, <c>mirror</c>, <c>strip</c>, <c>test</c> and <c>userpriv</c>. See <c>man 5 ebuild</c> for details. </ti> @@ -201,23 +340,31 @@ The following variables may or must be defined by every ebuild. <tr> <ti><c>DEPEND</c></ti> <ti> - A list of the package's build dependencies. See - <uri link="::general-concepts/dependencies"/>. + A list of the package's build dependencies. + See <uri link="::general-concepts/dependencies/"/>. + Starting with EAPI-7, applies to CHOST only. + </ti> + </tr> + <tr> + <ti><c>BDEPEND</c></ti> + <ti> + (EAPI=7) A list of the package's CBUILD build dependencies. + See <uri link="::general-concepts/dependencies/"/>. </ti> </tr> <tr> <ti><c>RDEPEND</c></ti> <ti> - A list of the package's runtime dependencies. See - <uri link="::general-concepts/dependencies"/>. + A list of the package's runtime dependencies. + See <uri link="::general-concepts/dependencies/"/>. </ti> </tr> <tr> <ti><c>PDEPEND</c></ti> <ti> A list of packages to be installed (if possible) after the package - is merged. Use this only when <c>RDEPEND</c> would cause cyclic - dependencies. See <uri link="::general-concepts/dependencies"/>. + is merged. Use this <e>only</e> when <c>RDEPEND</c> would cause cyclic + dependencies. See <uri link="::general-concepts/dependencies/"/>. </ti> </tr> <tr> @@ -230,102 +377,243 @@ The following variables may or must be defined by every ebuild. </ti> </tr> <tr> - <ti><c>PROPERTIES</c></ti> + <ti><c>DOCS</c></ti> <ti> - A space-delimited list of properties, with conditional - syntax support. <c>interactive</c> is the only valid value - for now. + An array or whitespace-separated list of documentation files for + the default <c>src_install</c> function to install using <c>dodoc</c>. + If undefined, a reasonable default list is used. See the + <uri link="::ebuild-writing/functions/src_install/#Default src_install"> + default <c>src_install</c> function</uri>. </ti> </tr> <tr> - <ti><c>DOCS</c></ti> + <ti><c>HTML_DOCS</c></ti> <ti> - An array or space-delimited list of documentation files for - the default src_install function to install using dodoc. If - undefined, a reasonable default list is used. (Requires - <uri link="::ebuild-writing/eapi/#eapi=4">EAPI>=4</uri>.) + An array or space-delimited list of documentation files or + directories for the <c>einstalldocs</c> function to install + recursively. (Requires + <uri link="::ebuild-writing/eapi/#EAPI 6">EAPI>=6</uri>.) </ti> </tr> </table> </body> -</section> -<section> -<title>SLOT</title> +<subsection> +<title>SRC_URI</title> + +<subsubsection> +<title>Conditional sources</title> <body> <p> -When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use <c>SLOT=""</c>, as -this will disable slotting for this package. +Conditional source files based upon USE flags are allowed using the usual +<c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary +packages <d/> downloading sparc binaries on ppc would be a waste of bandwidth. </p> -<p> -See <uri link="::general-concepts/slotting/" /> for more information on this variable. -</p> +<codesample lang="ebuild"> +SRC_URI="https://example.com/files/${P}-core.tar.bz2 + x86? ( https://example.com/files/${P}/${P}-sse-asm.tar.bz2 ) + ppc? ( https://example.com/files/${P}/${P}-vmx-asm.tar.bz2 ) + sparc? ( https://example.com/files/${P}/${P}-vis-asm.tar.bz2 ) + doc? ( https://example.com/files/${P}/${P}-docs.tar.bz2 )" +</codesample> </body> -</section> +</subsubsection> -<section> -<title>KEYWORDS</title> +<subsubsection> +<title>Renaming sources</title> <body> <p> -The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do -<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>. +Sometimes the upstream URI uses generic names that can easily clash with other +packages when creating a single mirror. Using the <c>-></c> syntax allows +you to rename the file when it's fetched from upstream for storing on mirrors +and in the local distdir. </p> <p> -See <uri link="::keywording/"/> for how to handle this variable. +Here we download a file from upstream which has a plain name like +<c>1.0.tar.gz</c> and save/mirror it with a better name like +<c>thepackage-1.0.tar.gz</c>. As usual, all tokens, including the operator +and the output file name, must be separated by whitespace. </p> -</body> -</section> +<codesample lang="ebuild"> +SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz" +</codesample> -<section> -<title>SRC_URI</title> +</body> +</subsubsection> -<subsection> -<title>Conditional Sources</title> +<subsubsection> +<title>Third-party mirrors</title> <body> <p> -Conditional source files based upon USE flags are allowed using the usual -<c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary -packages <d/> downloading sparc binaries on ppc would be a waste of bandwidth. +If the items in <c>SRC_URI</c> are available on multiple third-party mirrors, +and the same set of mirrors is shared across multiple ebuilds, then you +don't have to repeatedly list each of them in every ebuild. +The <c>profiles/thirdpartymirrors</c> file in the <c>::gentoo</c> repository +contains named groups of mirrors, in the format specified by the +Package Manager Specification (PMS), accessible through the +<c>mirror://</c> +pseudo-protocol. +</p> + +<p> +One might define a set of "example" mirrors, +</p> + +<pre> +example https://download.example.com https://mirror1.example.org/example +</pre> + +<p> +that can afterwards be referenced through a <c>mirror://</c> URI: </p> <codesample lang="ebuild"> -SRC_URI="http://example.com/files/${P}-core.tar.bz2 - x86? ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 ) - ppc? ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 ) - sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 ) - doc? ( http://example.com/files/${P}/${P}-docs.tar.bz2 )" +SRC_URI="mirror://example/${PN}/${P}.tar.gz" </codesample> <p> -If a <c>USE_EXPAND</c> variable is used to control whether certain optional -components are installed, the correct thing to do if the variable is unset is -generally to install <e>all</e> available components. +There are two valid cases for using <c>thirdpartymirrors</c>: +</p> + +<ol> + <li> + providing multiple download locations for mirror- or fetch-restricted + packages, + </li> + + <li> + dealing with upstreams that distribute their distfiles via a network + of mirrors without a primary download location or a bouncer service. + </li> +</ol> + +<p> +In any other case, the primary location must be used instead. The distfiles +will be <uri link="::general-concepts/mirrors/">mirrored onto Gentoo +infrastructure</uri>; in that case, the benefit to using third-party mirror +list does not outweigh the burden of maintaining it. +</p> + +</body> +</subsubsection> + +<subsubsection> +<title>Lifting restrictions</title> +<body> + +<p> +In EAPI 8, individual items in <c>SRC_URI</c> can be exempted from automatic +mirroring and fetching restrictions (imposed by <c>RESTRICT="mirror"</c> and +<c>RESTRICT="fetch"</c>) by prefixing the addresses with <c>mirror+</c> or +<c>fetch+</c>. For example, in the following ebuild, </p> <codesample lang="ebuild"> -SRC_URI="http://example.com/files/${P}-core.tar.bz2 - examplecards_foo? ( http://example.com/files/${P}-foo.tar.bz2 ) - examplecards_bar? ( http://example.com/files/${P}-bar.tar.bz2 ) - examplecards_baz? ( http://example.com/files/${P}-baz.tar.bz2 ) - !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? ( - http://example.com/files/${P}-foo.tar.bz2 - http://example.com/files/${P}-bar.tar.bz2 - http://example.com/files/${P}-baz.tar.bz2 ) ) )" +EAPI="8" + +SRC_URI="${P}.tar.gz + mirror+https://dev.gentoo.org/~larry/distfiles/${P}-addons.tar.gz" + +RESTRICT="fetch" </codesample> +<p> +Portage will be prevented from trying to fetch <c>${P}.tar.gz</c> as expected, +but the <c>${P}-patches.tar.gz</c> file will be mirrored and fetched by Portage +without restriction. +</p> + +<p> +The following table shows the effects of the prefixes when <c>RESTRICT="mirror"</c> and <c>RESTRICT="fetch"</c> are set: +</p> + +<table> +<tr> + <th></th> + <th><e>(no prefix)</e></th> + <th><c>fetch+</c></th> + <th><c>mirror+</c></th> +</tr> +<tr> + <th><e>(no RESTRICT)</e></th> + <ti>fetch & mirror</ti> + <ti>fetch & mirror</ti> + <ti>fetch & mirror</ti> +</tr> +<tr> + <th><c>RESTRICT="mirror"</c></th> + <ti>fetch only</ti> + <ti>fetch only</ti> + <ti>fetch & mirror</ti> +</tr> +<tr> + <th><c>RESTRICT="fetch"</c></th> + <ti>unfetchable</ti> + <ti>fetch only</ti> + <ti>fetch & mirror</ti> +</tr> +</table> + </body> +</subsubsection> </subsection> -</section> -<section> +<subsection> +<title>LICENSE</title> +<body> + +<p> +It is possible to specify multiple <c>LICENSE</c> entries, and entries which only +apply if a particular <c>USE</c> flag is set. The format is the same as for +<c>DEPEND</c>. See <uri link="https://www.gentoo.org/glep/glep-0023.html"> +GLEP 23</uri> for details. +</p> + +</body> +</subsection> + +<subsection> +<title>SLOT</title> +<body> + +<p> +When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use +<c>SLOT=""</c>, because the variable must not be empty. +</p> + +<p> +See <uri link="::general-concepts/slotting/" /> for more information on this +variable and see <uri link="::ebuild-maintenance/package-moves/" />. +</p> + +</body> +</subsection> + +<subsection> +<title>KEYWORDS</title> +<body> + +<p> +The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do +<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>. +</p> + +<p> +See <uri link="::keywording/"/> for how to handle this variable. +</p> + +</body> +</subsection> + +<subsection> <title>IUSE</title> <body> @@ -338,29 +626,137 @@ You need not assign the IUSE variable in your ebuild if it is empty. </note> <p> -Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x86-fbsd</c> and so on) should not be -listed. +Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x64-macos</c> and so on) should +not be listed. +</p> + +</body> +</subsection> + +<subsection> +<title>REQUIRED_USE</title> +<body> +<p> +The <c>REQUIRED_USE</c> variable contains a list of assertions that must be +met by the configuration of USE flags to be valid for this ebuild. In order +to be matched, a USE flag in a terminal element must be enabled +(or disabled if it has an exclamation mark prefix). +</p> + +<p> +Essentially, <c>REQUIRED_USE</c> is an analogue of <c>DEPEND</c> style syntax. +For example, to state that some combination is forbidden, i.e. "if foo is set, +bar must be unset": +</p> + +<codesample lang="ebuild"> +REQUIRED_USE="foo? ( !bar )" +</codesample> +<p> +To state "if foo is set, then at least one of bar, baz, and quux must be activated": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="foo? ( || ( bar baz quux ) )" +</codesample> +<p> +To state "exactly one of foo, bar, or baz must be set, but not several": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="^^ ( foo bar baz )" +</codesample> +<p> +Note that the last relationship is that of an Exclusive OR (XOR). +While an XOR could be formed from usual DEPEND syntax, +a specific ^^ operator has been added for this case. +</p> +<p> +Finally, to state "at least one of foo, bar, or baz must be set": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="|| ( foo bar baz )" +</codesample> +<important> +See section <uri link="::general-concepts/use-flags/#Conflicting USE flags"/> +for when (and when not) to use <c>REQUIRED_USE</c>. +</important> +</body> + +<subsubsection> +<title>EAPI 5</title> +<body> +<p> +EAPI 5 added an additional case to simplify conflicting USE flags. +</p> +<p> +To state "zero or one of foo, bar, or baz must be set, but not several": +</p> +<codesample lang="ebuild"> +REQUIRED_USE="?? ( foo bar baz )" +</codesample> +<p>In the previous EAPI, this would be the same as:</p> +<codesample lang="ebuild"> +REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )" +</codesample> +</body> +</subsubsection> +</subsection> + +<subsection> +<title>RESTRICT</title> +<body> + +<p> +While Portage may recognise several different <c>RESTRICT</c> tokens, it is +important that you do not rely on them existing. That is, you should ensure +your ebuild does not fail if those tokens are not exposed or given a different +name by another package manager. You can make use of Portage-provided +<c>RESTRICT</c> tokens, but do not fail hard without them. See +<uri link="https://projects.gentoo.org/pms/7/pms.html#x1-810008.2.8"> +PMS</uri> for the list of standardised <c>RESTRICT</c> tokens, or the above +table. </p> </body> +</subsection> </section> <section> -<title>LICENSE</title> +<title>Variables reserved for the package manager</title> <body> <p> -It is possible to specify multiple <c>LICENSE</c> entries, and entries which only -apply if a particular <c>USE</c> flag is set. The format is the same as for -<c>DEPEND</c>. See <uri link="https://wiki.gentoo.org/wiki/GLEP:23"> -GLEP 23</uri> for details. +Variables and functions that begin with any of the following strings (ignoring +case) are reserved for package manager use. Ebuilds must neither use them nor +rely upon them: +</p> + +<ul> + <li><c>__</c> (two underscores)</li> + <li><c>abort</c></li> + <li><c>dyn</c></li> + <li><c>prep</c></li> +</ul> + +<p> +The same applies to functions and variables that contain any of the following +strings (ignoring case): </p> +<ul> + <li> + <c>ebuild</c> (unless immediately preceded by another letter, and except + for the <c>EBUILD_PHASE</c> and <c>EBUILD_PHASE_FUNC</c> variables) + </li> + <li><c>hook</c></li> + <li><c>paludis</c></li> + <li><c>portage</c></li> +</ul> + </body> </section> <section> -<title>Version and Name Formatting Issues</title> +<title>Version and name formatting issues</title> <body> <p> @@ -369,14 +765,19 @@ conventions. Using capital letters in names or differences in how underscores an are used in versions are particularly common. For example, what Gentoo calls <c>foo-1.2.3b</c> may be expecting a tarball named <c>Foo-1.2-3b.tar.bz2</c>. Rather than hard coding the package string, it is preferable to make <c>MY_PN</c>, <c>MY_PV</c> and <c>MY_P</c> variables and use those to define the -upstream naming. The easy way of redefining the version, which should be used unless you are sure -you know what you are doing, is to use the <c>versionator</c> eclass: +upstream naming. +EAPI=7 debuted a new set of functions, ver_cut, ver_rs and ver_test. +These were backported into older EAPIs with the <c>eapi7-ver</c> eclass. +The easy way of redefining the version, which should be used unless you are sure +you know what you are doing, is to use these functions: </p> <codesample lang="ebuild"> -inherit versionator +inherit eapi7-ver + MY_PN="Foo" -MY_PV=$(replace_version_separator 2 '-') +# Replace the second period separator in PV with - +MY_PV=$(ver_rs 2 '-') MY_P="${MY_PN}-${MY_PV}" </codesample> @@ -387,20 +788,21 @@ switches to a format like <c>Foo-1.3-4.5.tar.bz2</c> (yes, this really happens). <p> It is also possible to use bash substitution to achieve the same effect (this is -how versionator works internally), but this is complicated, error prone and hard +how eapi7-ver works internally), but this is complicated, error prone and hard to read. </p> <p> -Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. This -must <e>not</e> be done for any new code, and should be fixed to use either -versionator or bash substitution where possible. Global scope non-bash code is -highly discouraged. +Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. +This must <e>not</e> be done for any new code and should be fixed to use +built-in version manipulation commands (for EAPI 7 or later), Bash substitution, +or in older EAPIs before 7, <c>eapi7-ver</c>. Global scope non-Bash code is +<e>strongly</e> discouraged. </p> <p> -The <c>versionator</c> eclass can also be used to extract particular components -from a version string. See <c>man versionator.eclass</c> and the eclass source code +The ver_ functions are used extract particular components +from a version string. See <c>man eapi7-ver.eclass</c> and the eclass source code for further documentation and examples. A brief summary of the functions follows. </p> @@ -411,45 +813,282 @@ follows. <th>Purpose</th> </tr> <tr> - <ti><c>get_all_version_components</c></ti> - <ti>Split up a version string into its component parts.</ti> - </tr> - <tr> - <ti><c>get_version_components</c></ti> + <ti><c>ver_rs [range] ' '</c></ti> <ti>Get important version components, excluding '.', '-' and '_'.</ti> </tr> <tr> - <ti><c>get_major_version</c></ti> + <ti><c>ver_cut 1</c></ti> <ti>Get the major version.</ti> </tr> <tr> - <ti><c>get_version_component_range</c></ti> + <ti><c>ver_cut [range]</c></ti> <ti>Extract a range of subparts from a version string.</ti> </tr> <tr> - <ti><c>get_after_major_version</c></ti> + <ti><c>ver_cut 2-</c></ti> <ti>Get everything after the major version.</ti> </tr> <tr> - <ti><c>replace_version_separator</c></ti> + <ti><c>ver_rs [range] [char]</c></ti> <ti>Replace a particular version separator.</ti> </tr> <tr> - <ti><c>replace_all_version_separators</c></ti> + <ti><c>ver_rs 1- [char]</c></ti> <ti>Replace all version separators.</ti> </tr> <tr> - <ti><c>delete_version_separator</c></ti> + <ti><c>ver_rs [range] ''</c></ti> <ti>Delete a version separator.</ti> </tr> <tr> - <ti><c>delete_all_version_separators</c></ti> + <ti><c>ver_rs 1- ''</c></ti> <ti>Delete all version separators.</ti> </tr> </table> +<note> +A helpful guide to the newer complements of the old <c>versionator.eclass</c> +functions can be found +<uri link="https://mgorny.pl/articles/the-ultimate-guide-to-eapi-7.html#replacing-versionator-eclass-uses"> +here</uri>, courtesy of Gentoo developer mgorny. +</note> + +</body> +</section> + +<section> +<title>Trailing slashes in variables</title> +<body> + +<p> +The following variables never end with a trailing slash in EAPI 7: +<c>D</c>, <c>ED</c>, <c>ROOT</c>, <c>EROOT</c>. Conversely, in EAPIs +preceeding EAPI 7, these variables are guaranteed to end with a +trailing slash. When working with EAPIs prior to EAPI 7, developers +are encouraged to use the bash suffix removal for the trailing slash +and add an explicit <c>/</c> when joining paths. For example: +<c>${D%/}/</c>, <c>${ED%/}/</c>, <c>${ROOT%/}/</c>, +<c>${EROOT%/}/</c>. +</p> + +</body> +</section> + +<section> +<title>Use of constant-value variables in ebuilds</title> +<body> + +<p> +Variables have significant value in ebuilds, making it possible to avoid +unnecessary repetitions and make maintenance easier. However, +references to constant-value variables should be used with care as their +excessive use can harm readability and increase maintenance burden (e.g. +when renaming a package). In particular, using variables whose values +have no direct correlation with the expected string should be avoided. +</p> + +<p>The examples of beneficial constant-value variable references are:</p> +<ul> + <li> + using <c>${PV}</c> and the variables derived from it (<c>${P}</c>, + <c>${MY_P}</c>…) in <c>SRC_URI</c> and <c>S</c> to avoid having + to update those variables for every version bump (assuming that + <c>${PV}</c> is used to indicate the upstream version); + </li> + + <li> + using <c>${PF}</c> in <c>--docdir</c> path — this is a canonical + Gentoo path that is always required to match <c>${PF}</c>. + </li> +</ul> + +<p>The examples of bad constant-value variable references are:</p> +<ul> + <li> + using <c>${PN}</c> in <c>HOMEPAGE</c>, <c>EGIT_REPO_URI</c> + or the domain of <c>SRC_URI</c> — it breaks URL parsing in editors + and terminals, and makes it hard to copy the link for external use + (e.g. while reviewing via gitweb), + </li> + + <li> + using <c>${HOMEPAGE}</c> in <c>SRC_URI</c> — it breaks when homepage + changes or additional entry is added, + </li> + + <li> + using <c>${PN}</c> (or other unnecessary helper variables) + excessively in <c>src_install()</c> — it impairs readability for + little benefit and causes a lot of trouble when the package needs to + be renamed. + </li> +</ul> + </body> </section> +<section> +<title>User environment</title> +<body> + +<p> +The following variables may be set in the user's environment and should be +respected by all ebuilds. The purpose of each variable within Gentoo is listed +alongside an example of a valid value. Upstream usage may diverge, but ebuilds +should ensure that these variables are interpreted consistently within Gentoo. +The chosen meanings are inspired by a few real and de-facto standards: +</p> + +<ul> + <li> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/make.html"> + The POSIX (2018) make specification</uri> + </li> + <li> + <uri link="https://www.gnu.org/software/make/manual/html_node/Implicit-Variables.html"> + The GNU make (v4.3) implementation</uri> + </li> + <li> + <uri link="https://www.gnu.org/software/libtool/manual/libtool.html#LT_005fINIT"> + The GNU libtool (v2.4.6) package</uri> + </li> +</ul> + +<p> +Many of these variables only have an effect if they are invoked directly. +For example, your compiler driver is usually responsible for assembling object +files rather than a direct call to <c>${AS}</c>. In that case, setting +<c>ASFLAGS</c> will have no effect on the build process; instead, you would set +something like <c>CFLAGS="-Wa,-alh,-L"</c> to tell the C compiler to pass those +flags to the assembler. The <c>LDFLAGS</c> variable is the exception to this +rule, as it is intended to be passed to the compiler driver rather than +<c>${LD}</c>. +</p> + +<table> + <tr> + <th>Variable</th> + <th>Purpose</th> + <th>Origin</th> + <th>Example</th> + </tr> + <tr> + <ti><c>AR</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/ar.html"> + ar</uri>-compatible library archiver + </ti> + <ti>POSIX make</ti> + <ti><c>x86_64-pc-linux-gnu-ar</c></ti> + </tr> + <tr> + <ti><c>ARFLAGS</c></ti> + <ti>flags for <c>${AR}</c></ti> + <ti>POSIX make</ti> + <ti><c>-v</c></ti> + </tr> + <tr> + <ti><c>AS</c></ti> + <ti>as-compatible assembler</ti> + <ti>GNU make</ti> + <ti><c>x86_64-pc-linux-gnu-as</c></ti> + </tr> + <tr> + <ti><c>ASFLAGS</c></ti> + <ti>flags for <c>${AS}</c></ti> + <ti>GNU make</ti> + <ti><c>--reduce-memory-overheads</c></ti> + </tr> + <tr> + <ti><c>CC</c></ti> + <ti>C compiler driver (also usually used for linking)</ti> + <ti>POSIX make</ti> + <ti><c>clang-9</c></ti> + </tr> + <tr> + <ti><c>CFLAGS</c></ti> + <ti>flags for <c>${CC}</c></ti> + <ti>POSIX make</ti> + <ti><c>-march=native</c></ti> + </tr> + <tr> + <ti><c>CPPFLAGS</c></ti> + <ti>flags for the C preprocessor</ti> + <ti>GNU make</ti> + <ti><c>-D_GNU_SOURCE</c></ti> + </tr> + <tr> + <ti><c>CXX</c></ti> + <ti>C++ compiler driver (also usually used for linking)</ti> + <ti>GNU make</ti> + <ti><c>clang++</c></ti> + </tr> + <tr> + <ti><c>CXXFLAGS</c></ti> + <ti>flags for <c>${CXX}</c></ti> + <ti>GNU make</ti> + <ti><c>-fvisibility=hidden</c></ti> + </tr> + <tr> + <ti><c>LD</c></ti> + <ti>dynamic linker</ti> + <ti>GNU libtool</ti> + <ti><c>x86_64-pc-linux-gnu-ld</c></ti> + </tr> + <tr> + <ti><c>LDFLAGS</c></ti> + <ti>flags for the <e>compiler driver</e> to pass to its linker</ti> + <ti>POSIX make</ti> + <ti><c>-Wl,-O1 -Wl,--as-needed</c></ti> + </tr> + <tr> + <ti><c>LEX</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/lex.html"> + lex</uri>-compatible lexer + </ti> + <ti>POSIX make</ti> + <ti><c>/usr/bin/flex</c></ti> + </tr> + <tr> + <ti><c>LFLAGS</c></ti> + <ti>flags for <c>${LEX}</c></ti> + <ti>POSIX make</ti> + <ti><c>--8bit --posix-compat</c></ti> + </tr> + <tr> + <ti><c>NM</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nm.html"> + nm</uri>-compatible symbol extractor + </ti> + <ti>GNU libtool</ti> + <ti><c>x86_64-pc-linux-gnu-nm</c></ti> + </tr> + <tr> + <ti><c>RANLIB</c></ti> + <ti>archive index generator</ti> + <ti>GNU libtool</ti> + <ti><c>x86_64-pc-linux-gnu-ranlib</c></ti> + </tr> + <tr> + <ti><c>YACC</c></ti> + <ti> + <uri link="https://pubs.opengroup.org/onlinepubs/9699919799/utilities/yacc.html"> + yacc</uri>-compatible compiler-compiler + </ti> + <ti>POSIX make</ti> + <ti><c>/usr/bin/bison</c></ti> + </tr> + <tr> + <ti><c>YFLAGS</c></ti> + <ti>flags for <c>${YACC}</c></ti> + <ti>POSIX make</ti> + <ti><c>-d</c></ti> + </tr> +</table> + +</body> +</section> </chapter> </guide> |
