| 1 |
The text is originally based on the patch provided by Thilo Bangert |
| 2 |
<bangert at gentoo.org> in the bug. It is revised and expanded to |
| 3 |
mention the use of ROOT in cross-compiling environments as explained |
| 4 |
in PMS Table 11.1. |
| 5 |
|
| 6 |
Gentoo-Bug: https://bugs.gentoo.org/144332 |
| 7 |
Signed-off-by: Göktürk Yüksek <gokturk@××××××××××.edu> |
| 8 |
--- |
| 9 |
ebuild-writing/variables/text.xml | 55 +++++++++++++++++++++++++++++++++++++-- |
| 10 |
1 file changed, 53 insertions(+), 2 deletions(-) |
| 11 |
|
| 12 |
diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml |
| 13 |
index 9027cad..dc152e1 100644 |
| 14 |
--- a/ebuild-writing/variables/text.xml |
| 15 |
+++ b/ebuild-writing/variables/text.xml |
| 16 |
@@ -101,8 +101,8 @@ them. |
| 17 |
<ti><c>ROOT</c></ti> |
| 18 |
<ti> |
| 19 |
The absolute path to the root directory into which the package is to be |
| 20 |
- merged. Use this when referring to installed files in <c>pkg_*</c> |
| 21 |
- functions. Never use this in <c>src_*</c> functions. |
| 22 |
+ merged. Only allowed in pkg_* phases. See |
| 23 |
+ <uri link="::ebuild-writing/variables#ROOT"/> |
| 24 |
</ti> |
| 25 |
</tr> |
| 26 |
<tr> |
| 27 |
@@ -393,6 +393,57 @@ GLEP 23</uri> for details. |
| 28 |
</section> |
| 29 |
|
| 30 |
<section> |
| 31 |
+<title>ROOT</title> |
| 32 |
+<body> |
| 33 |
+ |
| 34 |
+<p> |
| 35 |
+The idea behind <c>ROOT</c> is that one can build a system with |
| 36 |
+<c>ROOT=/somewhere</c> and then chroot into it or tar up |
| 37 |
+<c>/somewhere</c> as a system image. It is not designed to allow the |
| 38 |
+user to run <c>/somewhere/usr/bin/foo</c>. |
| 39 |
+</p> |
| 40 |
+ |
| 41 |
+<p> |
| 42 |
+Ebuilds may reference <c>ROOT</c> only during <c>pkg_*</c> phases. It |
| 43 |
+can't be used correctly in <c>src_*</c> phases, since <c>ROOT</c> may |
| 44 |
+be different when merging a binary package. For example, a binary |
| 45 |
+package may be built with <c>ROOT=/</c> and then installed onto a |
| 46 |
+system using <c>ROOT=/somewhere</c>. |
| 47 |
+</p> |
| 48 |
+ |
| 49 |
+<p> |
| 50 |
+When building a package, <c>ROOT</c> should not be used to satisfy the |
| 51 |
+required dependencies on libraries, headers files etc. Instead, the |
| 52 |
+files on the build system should be specified using <c>/</c>. |
| 53 |
+</p> |
| 54 |
+ |
| 55 |
+<p> |
| 56 |
+In a cross compiling environment, ebuilds must not call any of the |
| 57 |
+binaries inside <c>ROOT</c> since they may not be executable on the |
| 58 |
+build system. |
| 59 |
+</p> |
| 60 |
+ |
| 61 |
+<p> |
| 62 |
+Below is an example of an ebuild that uses <c>ROOT</c> in |
| 63 |
+<c>pkg_postinst()</c> to conditionally print an error message if an |
| 64 |
+old and obsolete configuration file still exists: |
| 65 |
+ |
| 66 |
+<codesample lang="ebuild"> |
| 67 |
+pkg_postinst() { |
| 68 |
+ if [[ -e "${ROOT}/etc/oldconfig" ]]; then |
| 69 |
+ ewarn "You still have the obsolete config file " |
| 70 |
+ ewarn " ${ROOT}/etc/oldconfig." |
| 71 |
+ ewarn "Please migrate your settings to ${ROOT}/etc/newconfig" |
| 72 |
+ ewarn "and remove ${ROOT}/etc/oldconfig." |
| 73 |
+ fi |
| 74 |
+} |
| 75 |
+</codesample> |
| 76 |
+</p> |
| 77 |
+ |
| 78 |
+</body> |
| 79 |
+</section> |
| 80 |
+ |
| 81 |
+<section> |
| 82 |
<title>Version and Name Formatting Issues</title> |
| 83 |
<body> |
| 84 |
|
| 85 |
-- |
| 86 |
2.7.3 |
Archives