commit: d1a7be9d1bf8138fe3476a579ce0af004979c914 Author: Göktürk Yüksek <gokturk <AT> binghamton <DOT> edu> AuthorDate: Sun May 15 02:34:54 2016 +0000 Commit: Göktürk Yüksek <gokturk <AT> binghamton <DOT> edu> CommitDate: Wed May 18 06:49:39 2016 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=d1a7be9d
ebuild-writing/variables: add a section to explain the ROOT variable #144332 The text is originally based on the patch provided by Thilo Bangert <bangert at gentoo.org> in the bug. It is revised and expanded to mention the use of ROOT in cross-compiling environments as explained in PMS Table 11.1. Gentoo-Bug: https://bugs.gentoo.org/144332 Signed-off-by: Göktürk Yüksek <gokturk <AT> binghamton.edu> ebuild-writing/variables/text.xml | 55 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 53 insertions(+), 2 deletions(-) diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index 9027cad..dc152e1 100644 --- a/ebuild-writing/variables/text.xml +++ b/ebuild-writing/variables/text.xml @@ -101,8 +101,8 @@ them. <ti><c>ROOT</c></ti> <ti> The absolute path to the root directory into which the package is to be - merged. Use this when referring to installed files in <c>pkg_*</c> - functions. Never use this in <c>src_*</c> functions. + merged. Only allowed in pkg_* phases. See + <uri link="::ebuild-writing/variables#ROOT"/> </ti> </tr> <tr> @@ -393,6 +393,57 @@ GLEP 23</uri> for details. </section> <section> +<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: + +<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> +</p> + +</body> +</section> + +<section> <title>Version and Name Formatting Issues</title> <body>
