* [gentoo-dev] [PATCH] ebuild-writing/variables: add a section to explain the ROOT variable #144332
@ 2016-05-15 2:49 Göktürk Yüksek
0 siblings, 0 replies; only message in thread
From: Göktürk Yüksek @ 2016-05-15 2:49 UTC (permalink / raw)
To: devmanual; +Cc: gentoo-dev
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@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>
--
2.7.3
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2016-05-15 2:49 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-05-15 2:49 [gentoo-dev] [PATCH] ebuild-writing/variables: add a section to explain the ROOT variable #144332 Göktürk Yüksek
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox