man: emerge: Describe the SYSROOT environment variable for EAPI 7

This deprecates the --root-deps option and the PORTAGE_CONFIGROOT
variable.

1 files changed, 29 insertions, 9 deletions

diff --git a/man/emerge.1 b/man/emerge.1
index a3c8dd7cd..f53ba92f5 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -911,6 +911,9 @@ necessary.
 .BR \-\-root=DIR
 Set the \fBROOT\fR environment variable.
 .TP
+.BR \-\-sysroot=DIR
+Set the \fBSYSROOT\fR environment variable.
+.TP
 .BR \-\-root\-deps[=rdeps]
 If no argument is given then build\-time dependencies of packages for
 \fBROOT\fR are installed to \fBROOT\fR instead of /.
@@ -919,12 +922,16 @@ of packages for \fBROOT\fR.
 This option is only meaningful when used together with \fBROOT\fR and it should
 not be enabled under normal circumstances!
 
-Does not affect EAPIs that support \fBHDEPEND\fR.
-Experimental \fBEAPI 5-hdepend\fR provides \fBHDEPEND\fR as a new
-means to adjust installation into "\fI/\fR" and \fBROOT\fR.
-If ebuilds using EAPIs which \fIdo not\fR support \fBHDEPEND\fR are built in
-the same \fBemerge\fR run as those using EAPIs which \fIdo\fR support
-\fBHDEPEND\fR, this option affects only the former.
+Does not affect EAPIs that support \fBBDEPEND\fR or \fBHDEPEND\fR.
+\fBEAPI 7\fR introduces \fBBDEPEND\fR and experimental
+\fBEAPI 5-hdepend\fR features \fBHDEPEND\fR as a means to adjust
+installation into / and \fBROOT\fR.  Use the \fBSYSROOT\fR environment
+variable to control where \fBDEPEND\fR is installed to under
+\fBEAPI 7\fR.
+
+When ebuilds with different EAPIs feature in the same emerge run, the
+appropriate behaviour for each EAPI is applied independently to each
+ebuild.
 .TP
 .BR "\-\-search\-index < y | n >"
 Enable or disable indexed search for search actions. This option is
@@ -1090,8 +1097,19 @@ Defaults to the prefix where portage is currently installed.
 .TP
 \fBROOT\fR = \fI[path]\fR
 Use \fBROOT\fR to specify the target root filesystem to be used for
-merging packages or ebuilds. This variable can be set via the \fB\-\-root\fR
-option or in \fBmake.conf\fR(5) (the command line overrides other settings).
+merging the requested packages or ebuilds and their runtime
+dependencies.  This variable can be set via the \fB\-\-root\fR option
+or in \fBmake.conf\fR(5) (the command line overrides other settings).
+.br
+Defaults to /.
+.TP
+\fBSYSROOT\fR = \fI[path]\fR
+Use \fBSYSROOT\fR to specify the target root filesystem to be used for
+merging the build dependencies satisfied by \fBDEPEND\fR.  This
+variable can be set via the \fB\-\-sysroot\fR option or in
+\fBmake.conf\fR(5) (the command line overrides other settings).  The
+value must either be / or equal to \fBROOT\fR.  When cross-compiling,
+only the latter is valid.
 .br
 Defaults to /.
 .TP
@@ -1099,7 +1117,9 @@ Defaults to /.
 Use \fBPORTAGE_CONFIGROOT\fR to specify the location for various portage
 configuration files
 (see \fBFILES\fR for a detailed list of configuration files).  This variable
-can be set via the \fB\-\-config\-root\fR option.
+can be set via the \fB\-\-config\-root\fR option.  However, it is now
+superseded by the \fBSYSROOT\fR variable and can only be given if its
+value matches \fBSYSROOT\fR or if \fBROOT=/\fR.
 .br
 Defaults to /.
 .SH "OUTPUT"