[gentoo-portage-dev] Please review: manpage-cleanup

[gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

Hi!

I created a branch for documenting hdepend ([1] and this thread) and would like you to review and possibly merge it.

This branch is based off my manpage-cleanup branch, hence I recommend reading/merging that before this one.

Thanks,
Dennis

[1] https://github.com/devurandom/portage/commits/feature/manpage-hdepend

[gentoo-portage-dev] [PATCH 1/2] Document HDEPEND in ebuild(5)

[Dennis Schridde]

---
 man/ebuild.5 | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/man/ebuild.5 b/man/ebuild.5
index 5bb1afa..9fec816 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -316,6 +316,32 @@ the user does not specify any of the previous choices.
 Note that if any of the packages listed are already merged, the package manager
 will use that to consider the dependency satisfied.
 
+.SS "Cross-compilation"
+Portage supports cross-compilation into a subdirectory specified by \fBROOT\fR.
+.TP
+.B Host
+\fIHost\fR in this context means the platform hosting the build process, i.e.
+what autotools calls CBUILD.  Its packages are contained in the root of the
+filesystem ("\fI/\fR").  If \fBROOT\fR is "\fI/\fR", all dependency types will
+be installed there.  Otherwise (starting from \fBEAPI 6\fR) only \fBHDEPEND\fR
+is installed into "\fI/\fR".  In \fBEAPI 5\fR and earlier, the behaviour is
+controlled by the \fI\-\-root-deps\fR flag to \fBemerge\fR(1), defaulting to
+install only \fBDEPEND\fR into the \fIhost\fR.
+.TP
+.B Target
+\fITarget\fR refers to the platform that the package will later run on, i.e.
+what autotools calls CHOST.  The directory housing this system is specified by
+\fBROOT\fR.  If it is different from "\fI/\fR", i.e. \fIhost\fR and
+\fItarget\fR are not the same, this variable contains the path to the directory
+housing the \fItarget\fR system.  Starting from \fBEAPI 6\fR, \fBDEPEND\fR and
+\fBRDEPEND\fR list the \fItarget\fR dependencies, i.e. those to be installed
+into \fBROOT\fR.  In \fBEAPI 5\fR and earlier, the \fBemerge\fR(1) flag
+\fI\-\-root-deps\fR controlled what the package manager installed there,
+defaulting to only \fBRDEPEND\fR.
+.PP
+See section \fBVARIABLES\fR for more information about the \fBDEPEND\fR,
+\fBRDEPEND\fR and \fBHDEPEND\fR variables.
+
 .SH "VARIABLES"
 .TP
 .B Usage Notes
@@ -547,6 +573,11 @@ This should contain a list of all packages that are required for the program
 to compile (aka \fIbuildtime\fR dependencies).  These are usually libraries and
 headers.
 
+Starting from \fBEAPI 6\fR, tools should go into the \fBHDEPEND\fR variable
+instead, as \fBDEPEND\fR will only be installed into the \fItarget\fR system
+and hence cannot be executed in a cross\-compile setting.  (See section
+\fBCross\-compilation\fR for more information.)
+
 You may use the syntax described above in the \fBDependencies\fR section.
 .TP
 .B RDEPEND
@@ -559,6 +590,16 @@ implicitly set.
 
 You may use the syntax described above in the \fBDependencies\fR section.
 .TP
+.B HDEPEND
+This should contain a list of all packages that are required to be executable
+during compilation of this program (aka \fIhost\fR buildtime dependencies).
+These are usually tools, like interpreters or (cross\-)compilers.
+
+This variable is new in \fBEAPI 6\fR and will be installed into the \fIhost\fR
+system.  (See section \fBCross-compilation\fR for more information.)
+
+You may use the syntax described above in the \fBDependencies\fR section.
+.TP
 .B PDEPEND
 This should contain a list of all packages that should be merged after this
 one (aka \fIpost\fR merge dependencies), but which may be installed by the
-- 
1.7.12

[gentoo-portage-dev] [PATCH 2/2] Doocument behaviour of --root-deps for EAPI 6+ in emerge(1)

[Dennis Schridde]

---
 man/emerge.1 | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/man/emerge.1 b/man/emerge.1
index ea6409c..61d86b7 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -711,10 +711,11 @@ 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!
 
-For currently supported \fBEAPI\fR values, the build-time dependencies are
-specified in the \fBDEPEND\fR variable.
-However, behavior may change for new \fBEAPI\fRs when related extensions are
-added in the future.
+Affects \fBEAPI 5\fR and earlier ebuilds only.
+\fBEAPI 6\fR and later provide \fBHDEPEND\fR as a new means to adjust
+installation into "\fI/\fR" and \fBROOT\fR.
+If \fBEAPI 5\fR and earlier ebuilds are built in the same \fBemerge\fR run as
+\fBEAPI 6\fR and later ebuilds, this option affects only the former.
 .TP
 .BR "\-\-select [ y | n ]"
 Add specified packages to the world set (inverse of
-- 
1.7.12

Re: [gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

[-- Attachment #1: Type: text/plain, Size: 143 bytes --]

Subject should actually read: manpage-hdepend — I'm just not used to writing 
emails on the console using a text-editor alone…

--Dennis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-portage-dev] [PATCH 1/2] Document HDEPEND in ebuild(5)

[Zac Medico]

On 09/23/2012 03:28 PM, Dennis Schridde wrote:
> +This variable is new in \fBEAPI 6\fR and will be installed into the \fIhost\fR
> +system.  (See section \fBCross-compilation\fR for more information.)

It's premature to say anything about EAPI 6. You should refer to
"experimental EAPI 5-hdepend" instead.
-- 
Thanks,
Zac

[gentoo-portage-dev] [PATCH 1/2] Document HDEPEND in ebuild(5)

[Dennis Schridde]

---
 man/ebuild.5 | 46 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/man/ebuild.5 b/man/ebuild.5
index 5bb1afa..a15bf55 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -316,6 +316,36 @@ the user does not specify any of the previous choices.
 Note that if any of the packages listed are already merged, the package manager
 will use that to consider the dependency satisfied.
 
+.SS "Cross-compilation"
+Portage supports cross-compilation into a subdirectory specified by \fBROOT\fR.
+.TP
+.B Host
+\fIHost\fR in this context means the platform hosting the build process, i.e.
+what autotools calls CBUILD.
+Its packages are contained in the root of the filesystem ("\fI/\fR").
+If \fBROOT\fR is "\fI/\fR", all dependency types will be installed there.
+Otherwise, starting from experimental \fBEAPI 5-hdepend\fR, only \fBHDEPEND\fR
+is installed into "\fI/\fR".
+In \fBEAPI 5\fR and earlier, the behaviour is controlled by the
+\fI\-\-root-deps\fR flag to \fBemerge\fR(1), defaulting to install only
+\fBDEPEND\fR into the \fIhost\fR.
+.TP
+.B Target
+\fITarget\fR refers to the platform that the package will later run on, i.e.
+what autotools calls CHOST.
+The directory housing this system is specified by \fBROOT\fR.
+If it is different from "\fI/\fR", i.e. \fIhost\fR and \fItarget\fR are not the
+same, this variable contains the path to the directory housing the \fItarget\fR
+system.
+Starting from experimental \fBEAPI 5-hdepend\fR, \fBDEPEND\fR and \fBRDEPEND\fR
+list the \fItarget\fR dependencies, i.e. those to be installed into \fBROOT\fR.
+In \fBEAPI 5\fR and earlier, the \fBemerge\fR(1) flag \fI\-\-root-deps\fR
+controlled what the package manager installed there, defaulting to only
+\fBRDEPEND\fR.
+.PP
+See section \fBVARIABLES\fR for more information about the \fBDEPEND\fR,
+\fBRDEPEND\fR and \fBHDEPEND\fR variables.
+
 .SH "VARIABLES"
 .TP
 .B Usage Notes
@@ -547,6 +577,11 @@ This should contain a list of all packages that are required for the program
 to compile (aka \fIbuildtime\fR dependencies).  These are usually libraries and
 headers.
 
+Starting from experimental \fBEAPI 5-hdepend\fR, tools should go into the
+\fBHDEPEND\fR variable instead, as \fBDEPEND\fR will only be installed into the
+\fItarget\fR system and hence cannot be executed in a cross\-compile setting.
+(See section \fBCross\-compilation\fR for more information.)
+
 You may use the syntax described above in the \fBDependencies\fR section.
 .TP
 .B RDEPEND
@@ -559,6 +594,17 @@ implicitly set.
 
 You may use the syntax described above in the \fBDependencies\fR section.
 .TP
+.B HDEPEND
+This should contain a list of all packages that are required to be executable
+during compilation of this program (aka \fIhost\fR buildtime dependencies).
+These are usually tools, like interpreters or (cross\-)compilers.
+
+This variable is new in experimental \fBEAPI 5-hdepend\fR and will be installed
+into the \fIhost\fR system.
+(See section \fBCross-compilation\fR for more information.)
+
+You may use the syntax described above in the \fBDependencies\fR section.
+.TP
 .B PDEPEND
 This should contain a list of all packages that should be merged after this
 one (aka \fIpost\fR merge dependencies), but which may be installed by the
-- 
1.7.12