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

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

[Dennis Schridde]

Hi!

These patches document HDEPEND and incorporate the suggestions Zac gave on the gentoo-portage-dev mailinglist regarding EAPI 6 vs. EAPI 5-hdepend.

Best regards,
Dennis

[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

[gentoo-portage-dev] [PATCH 2/2] Document 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..5861bb6 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.
+Experimental \fBEAPI 5-hdepend\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 5-hdepend\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-hdepend

[Zac Medico]

On 09/24/2012 05:16 AM, Dennis Schridde wrote:
> Hi!
> 
> These patches document HDEPEND and incorporate the suggestions Zac gave on the gentoo-portage-dev mailinglist regarding EAPI 6 vs. EAPI 5-hdepend.
> 
> Best regards,
> Dennis
> 


Thanks, I've applied your patches. I've also made some changes here:

http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=a2e36694d14cc895592b36ba812e55f5cfdd9923
-- 
Thanks,
Zac

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

[Dennis Schridde]

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

Hi!

Am Montag, 24. September 2012, 14:04:10 schrieb Zac Medico:
> On 09/24/2012 05:16 AM, Dennis Schridde wrote:
> Thanks, I've applied your patches. I've also made some changes here:
Tow comments:
* I tried to use \fI for emphasis, cmdline flags and other "minor" things, and 
\fB for references to variables, sections, manpages, etc. (Re: "\fBdo not\fR", 
"\fBdo\fR")
* Why did you drop "defaulting to only \fBRDEPEND\fR" from the Target 
subsection describing --root-deps? Was it wrong? I tried to give a quick 
overview over how cross-compilation is handled and what behaviour to expect.

--Dennis

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

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

[Dennis Schridde]

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

Am Montag, 24. September 2012, 23:18:59 schrieb Dennis Schridde:
> Am Montag, 24. September 2012, 14:04:10 schrieb Zac Medico:
> * I tried to use \fI for emphasis, cmdline flags and other "minor" things,
> and \fB for references to variables, sections, manpages, etc. (Re: "\fBdo
> not\fR", "\fBdo\fR")
P.S: This seemed to be how sys-apps/man-pages and sys-apps/man-pages-posix do 
it.

P.P.S: Thanks for applying the patches and especially for your comments and 
help with submitting them correctly.

--Dennis

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

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

[Zac Medico]

On 09/24/2012 02:18 PM, Dennis Schridde wrote:
> Hi!
> 
> Am Montag, 24. September 2012, 14:04:10 schrieb Zac Medico:
>> On 09/24/2012 05:16 AM, Dennis Schridde wrote:
>> Thanks, I've applied your patches. I've also made some changes here:
> Tow comments:
> * I tried to use \fI for emphasis, cmdline flags and other "minor" things, and 
> \fB for references to variables, sections, manpages, etc. (Re: "\fBdo not\fR", 
> "\fBdo\fR")

Okay, will change those to italics.

> * Why did you drop "defaulting to only \fBRDEPEND\fR" from the Target 
> subsection describing --root-deps? Was it wrong? I tried to give a quick 
> overview over how cross-compilation is handled and what behaviour to expect.

The default for --root-deps is actually all deps (DEPEND, RDEPEND, and
PDEPEND). For --root-deps=rdeps it's RDEPEND and PDEPEND.
-- 
Thanks,
Zac

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

[Dennis Schridde]

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

Am Montag, 24. September 2012, 14:40:00 schrieb Zac Medico:
> On 09/24/2012 02:18 PM, Dennis Schridde wrote:
> > * Why did you drop "defaulting to only \fBRDEPEND\fR" from the Target
> > subsection describing --root-deps? Was it wrong? I tried to give a quick
> > overview over how cross-compilation is handled and what behaviour to
> > expect.
> The default for --root-deps is actually all deps (DEPEND, RDEPEND, and
> PDEPEND). For --root-deps=rdeps it's RDEPEND and PDEPEND.
I just noticed, the description was to be easily misunderstood. What I tried 
to express was: By default emerge will install RDEPEND (and PDEPEND — forgot 
about that). I'll retry and send another patch.

--Dennis

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

[gentoo-portage-dev] Please review: manpage-hdepend improvements

[Dennis Schridde]

Hello!

Here come a few patches to improve the HDEPEND documentation:
* Minor formatting change
* Description of behaviour without --root-deps
* Description of targetroot useflag

Best regards,
Dennis

[gentoo-portage-dev] [PATCH 1/3] Put lengthy install-location documentation into an own paragraph for cross-compile docs in ebuild(5)

[Dennis Schridde]

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

diff --git a/man/ebuild.5 b/man/ebuild.5
index fc06eee..3c2200c 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -323,6 +323,7 @@ Portage supports cross-compilation into a subdirectory specified by \fBROOT\fR.
 \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, for EAPIs that support \fBHDEPEND\fR (experimental
 \fBEAPI 5-hdepend\fR), only \fBHDEPEND\fR is installed into "\fI/\fR".
@@ -337,6 +338,7 @@ 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.
+
 For EAPIs that support \fBHDEPEND\fR (experimental \fBEAPI 5-hdepend\fR),
 \fBDEPEND\fR, \fBRDEPEND\fR, and \fBPDEPEND\fR
 list the \fItarget\fR dependencies, i.e. those to be installed into \fBROOT\fR.
-- 
1.7.12

[gentoo-portage-dev] [PATCH 2/3] Document default behaviour without --root-deps for EAPI 5- in ebuild(5)

[Dennis Schridde]

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

diff --git a/man/ebuild.5 b/man/ebuild.5
index 3c2200c..2652f89 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -344,6 +344,8 @@ For EAPIs that support \fBHDEPEND\fR (experimental \fBEAPI 5-hdepend\fR),
 list the \fItarget\fR dependencies, i.e. those to be installed into \fBROOT\fR.
 For EAPIs that do not support \fBHDEPEND\fR, the \fBemerge\fR(1) flag
 \fI\-\-root-deps\fR controls what the package manager installs there.
+Without it, \fBemerge\fR defaults to install only runtime dependencies (i.e.
+\fBRDEPEND\fR and \fBPDEPEND\fR) into \fBROOT\fR.
 .PP
 See section \fBVARIABLES\fR for more information about the \fBDEPEND\fR,
 \fBRDEPEND\fR and \fBHDEPEND\fR variables.
-- 
1.7.12

[gentoo-portage-dev] [PATCH 3/3] Document targetroot useflag in ebuild(5)

[Dennis Schridde]

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

diff --git a/man/ebuild.5 b/man/ebuild.5
index 2652f89..0d5e448 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -349,6 +349,15 @@ Without it, \fBemerge\fR defaults to install only runtime dependencies (i.e.
 .PP
 See section \fBVARIABLES\fR for more information about the \fBDEPEND\fR,
 \fBRDEPEND\fR and \fBHDEPEND\fR variables.
+.TP
+.B The targetroot USE flag
+For EAPIs that support the "\fItargetroot\fR" USE flag, that flag is
+automatically enabled by the package manager if \fIhost\fR and \fItarget\fR
+system are not the same, i.e. if the \fBROOT\fR is not "\fI/\fR".
+This is necessary where the package to be built needs an executable copy of
+itself during the build process.
+A known example is dev-lang/python, which needs to run a Python interpreter
+during compilation.
 
 .SH "VARIABLES"
 .TP
-- 
1.7.12

Re: [gentoo-portage-dev] Please review: manpage-hdepend improvements

[Zac Medico]

On 09/25/2012 06:58 AM, Dennis Schridde wrote:
> Hello!
> 
> Here come a few patches to improve the HDEPEND documentation:
> * Minor formatting change
> * Description of behaviour without --root-deps
> * Description of targetroot useflag

Thanks, I've applied all 3 patches.
-- 
Thanks,
Zac

[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

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