ROOT

gentoo.org> ebuild-writing/variables/text.xml | 340 +++++++++++++++++++------------------- 1 file changed, 170 insertions(+), 170 deletions(-) diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index f07832e..4c7df4f 100644 --- a/ebuild-writing/variables/text.xml +++ b/ebuild-writing/variables/text.xml @@ -185,6 +185,57 @@ for these variables when writing ebuilds. + + +ROOT + + +

+The idea behind ROOT is that one can build a system with +ROOT=/somewhere and then chroot into it or tar up +/somewhere as a system image. It is not designed to allow the +user to run /somewhere/usr/bin/foo. +

+ +

+Ebuilds may reference ROOT only during pkg_* phases. It +can't be used correctly in src_* phases, since ROOT may +be different when merging a binary package. For example, a binary +package may be built with ROOT=/ and then installed onto a +system using ROOT=/somewhere. +

+ +

+When building a package, ROOT 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 /. +

+ +

+In a cross compiling environment, ebuilds must not call any of the +binaries inside ROOT since they may not be executable on the +build system. +

+ +

+Below is an example of an ebuild that uses ROOT in +pkg_postinst() to conditionally print an error message if an +old and obsolete configuration file still exists: +

+ + +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 +} + + + +

@@ -348,45 +399,11 @@ The following variables may or must be defined by every ebuild. -

-SLOT - - -

-When slots are not needed, use SLOT="0". Do not use -SLOT="", because the variable must not be empty. -

- -

-See for more information on this -variable and see . -

- - -

- -

-KEYWORDS - - -

-The only valid construct involving a * inside KEYWORDS is a -*. Do -not use KEYWORDS="*" or KEYWORDS="~*". -

- -

-See for how to handle this variable. -

- - -

- -

+ SRC_URI - + Conditional Sources @@ -405,9 +422,9 @@ SRC_URI="https://example.com/files/${P}-core.tar.bz2 - + - + Renaming Sources @@ -430,9 +447,9 @@ SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz" - + - + Third-party mirrors @@ -487,9 +504,9 @@ list does not outweigh the burden of maintaining it.

- + - + Lifting restrictions @@ -547,110 +564,161 @@ The following table shows the effects of the prefixes when RESTRICT="mirror"< + -

-IUSE + +LICENSE

-Note that the IUSE variable is cumulative, so there is no need to specify -USE flags used only within inherited eclasses within the ebuild's IUSE. -

- -You need not assign the IUSE variable in your ebuild if it is empty. - - -

-Arch USE flags (sparc, mips, x64-macos and so on) should -not be listed. +It is possible to specify multiple LICENSE entries, and entries which only +apply if a particular USE flag is set. The format is the same as for +DEPEND. See +GLEP 23 for details.

+ -

-LICENSE + +SLOT

-It is possible to specify multiple LICENSE entries, and entries which only -apply if a particular USE flag is set. The format is the same as for -DEPEND. See -GLEP 23 for details. +When slots are not needed, use SLOT="0". Do not use +SLOT="", because the variable must not be empty. +

+ +

+See for more information on this +variable and see .

+ -

-RESTRICT + +KEYWORDS

-While Portage may recognise several different RESTRICT 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 -RESTRICT tokens, but do not fail hard without them. See - -PMS for the list of standardised RESTRICT tokens, or the above -table. +The only valid construct involving a * inside KEYWORDS is a -*. Do +not use KEYWORDS="*" or KEYWORDS="~*". +

+ +

+See for how to handle this variable.

+ -

-ROOT + +IUSE

-The idea behind ROOT is that one can build a system with -ROOT=/somewhere and then chroot into it or tar up -/somewhere as a system image. It is not designed to allow the -user to run /somewhere/usr/bin/foo. +Note that the IUSE variable is cumulative, so there is no need to specify +USE flags used only within inherited eclasses within the ebuild's IUSE.

+ +You need not assign the IUSE variable in your ebuild if it is empty. +

-Ebuilds may reference ROOT only during pkg_* phases. It -can't be used correctly in src_* phases, since ROOT may -be different when merging a binary package. For example, a binary -package may be built with ROOT=/ and then installed onto a -system using ROOT=/somewhere. +Arch USE flags (sparc, mips, x64-macos and so on) should +not be listed.

+ + + + +REQUIRED_USE +

-When building a package, ROOT 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 /. +The REQUIRED_USE 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).

-In a cross compiling environment, ebuilds must not call any of the -binaries inside ROOT since they may not be executable on the -build system. +Essentially, REQUIRED_USE is an analogue of DEPEND style syntax. +For example, to state that some combination is forbidden, i.e. "if foo is set, +bar must be unset":

+ +REQUIRED_USE="foo? ( !bar )" +

-Below is an example of an ebuild that uses ROOT in -pkg_postinst() to conditionally print an error message if an -old and obsolete configuration file still exists: +To state "if foo is set, then at least one of bar, baz, and quux must be activated": +

+ +REQUIRED_USE="foo? ( || ( bar baz quux ) )" + +

+To state "exactly one of foo, bar, or baz must be set, but not several":

+ +REQUIRED_USE="^^ ( foo bar baz )" + +

+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. +

+Finally, to state "at least one of foo, bar, or baz must be set": +

+ +REQUIRED_USE="|| ( foo bar baz )" + + +See section +for when (and when not) to use REQUIRED_USE. + + + +EAPI 5 + +

+EAPI 5 added an additional case to simplify conflicting USE flags. +

+To state "zero or one of foo, bar, or baz must be set, but not several": +

-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 -} +REQUIRED_USE="?? ( foo bar baz )" + +

In the previous EAPI, this would be the same as:

+ +REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )" + + + + + +RESTRICT + + +

+While Portage may recognise several different RESTRICT 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 +RESTRICT tokens, but do not fail hard without them. See + +PMS for the list of standardised RESTRICT tokens, or the above +table. +

@@ -825,74 +893,6 @@ have no direct correlation with the expected string should be avoided.

-REQUIRED_USE - -

-The REQUIRED_USE 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). -

- -

-Essentially, REQUIRED_USE is an analogue of DEPEND style syntax. -For example, to state that some combination is forbidden, i.e. "if foo is set, -bar must be unset": -

- - -REQUIRED_USE="foo? ( !bar )" - -

-To state "if foo is set, then at least one of bar, baz, and quux must be activated": -

- -REQUIRED_USE="foo? ( || ( bar baz quux ) )" - -

-To state "exactly one of foo, bar, or baz must be set, but not several": -

- -REQUIRED_USE="^^ ( foo bar baz )" - -

-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. -

-Finally, to state "at least one of foo, bar, or baz must be set": -

- -REQUIRED_USE="|| ( foo bar baz )" - - -See section -for when (and when not) to use REQUIRED_USE. - - - - -EAPI 5 - -

-EAPI 5 added an additional case to simplify conflicting USE flags. -

-To state "zero or one of foo, bar, or baz must be set, but not several": -

- -REQUIRED_USE="?? ( foo bar baz )" - -

In the previous EAPI, this would be the same as:

- -REQUIRED_USE="foo? ( !bar !baz ) bar? ( !foo !baz ) baz? ( !foo !bar )" - - - -

User environment