Mailing List Archive

On Saturday 09 October 2004 22:20, Sven Vermeulen wrote:
> The documents are online at
> http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml

It's good to finally have something to help dispel a lot of the myths that run
rampart on #gentoo. ;)

Only a few issues to bring up. Apologies in advance if I'm too strict.

>A profile contains architecture-specific information for Portage, such as a
>list of core packages, packages that don't work or are masked-out by Gentoo
>developers.

... core packages and packages that either don't work or ...

>The PKGDIR variable defaults to ${PORTDIR}/packages which means that, if you
>alter the PORTDIR variable, the prebuilt binaries location is changed with
>it.

>The DISTDIR variable defaults to ${PORTDIR}/distfiles which means that, if
>you alter the PORTDIR variable, the source code location is changed with it.

>The BUILD_PREFIX variable defaults to ${PORTAGE_TMPDIR}/portage which means
>that, when you alter the PORTAGE_TMPDIR variable, the BUILD_PREFIX location
>changes with it.

These three all have the same issue. The defaults are defined in make.globals,
which is parsed independently of make.conf. This means that even if PORTDIR
is changed in make.conf, the expansion of ${PORTDIR} used in make.globals is
still set to the default.

>Portage' temporary files are stored in /var/tmp by default.

>Portage' Protected Locations

Missing an "s"..

>By default Portage installs all files on your life filesystem (/). This is
>defined by the ROOT variable and should only be used as an environment
>variable for creating new build images.

ROOT in fact can only be defined in the environment. Portage will ignore it if
is defined in a configuration file (but will still pass it down to ebuilds).

>When the requested information or data is not available on your system,
>Portage will retrieve it from the Internet.

The SYNC variable is defined just after this, which implies that portage will
automatically make use of rsync.

>Make sure that your FETCHCOMMAND and RESUMECOMMAND stores the source code
>referenced by the ${URI} variable inside ${DISTDIR}.

I find this to be a little unclear. However it's phrased though, it is
important that the backslash is not excluded. ie. ${URI} -> \${URI}

>If you want to use a specific software version from the testing branch but
>you don't want Portage to use the testing branch for subsequent versions, you
>can add in the version in the package.keywords file. You can also enter a
>version range using the <=, <, > or >= operators.

As Marius mentioned earlier, "=" is missing from the list of operators. Also,
it would be helpful to say that specifying a version requires the use of an
operator and vice-versa.

>etc-update is a tool that aids in merging the ._cfg0000_<name> files.

Might be good to refer to CONFIG_PROTECT here so that the reader immediately
connects the two.

>Tricking Portage

I really don't like the use of the word "tricking" here. It implies that it is
okay to tell portage that things are installed that actually aren't. The
original name used was package.injected but the name was changed because the
common improper usage of --inject.

This file should only ever be used to tell portage of software that is
installed that should not be maintained by portage. From a users perspective,
it should be used when they wish to manually maintain a kernel, nvidia
drivers or whatever else.

>To run these configuration steps, which are enlisted in the ebuild's
>(optional) config() function.

This is not a complete sentence..

Well, that's about it. Hope I wasn't too harsh. Everything else is superb. :)

Regards,
Jason Stubbs

--
gentoo-doc@gentoo.org mailing list

On Sun, Oct 10, 2004 at 12:03:16AM +0900, Jason Stubbs wrote:
> >A profile contains architecture-specific information for Portage, such as a
> >list of core packages, packages that don't work or are masked-out by Gentoo
> >developers.
>
> ... core packages and packages that either don't work or ...

Actually I was referring to the list of core packages (the packages that are
in the profile's system) and then to the packages that are masked out.

For instance, the uclibc profile maskes out glibc.

> >The PKGDIR variable defaults to ${PORTDIR}/packages which means that, if you
> >alter the PORTDIR variable, the prebuilt binaries location is changed with
> >it.
>
> >The DISTDIR variable defaults to ${PORTDIR}/distfiles which means that, if
> >you alter the PORTDIR variable, the source code location is changed with it.
>
> >The BUILD_PREFIX variable defaults to ${PORTAGE_TMPDIR}/portage which means
> >that, when you alter the PORTAGE_TMPDIR variable, the BUILD_PREFIX location
> >changes with it.
>
> These three all have the same issue. The defaults are defined in make.globals,
> which is parsed independently of make.conf. This means that even if PORTDIR
> is changed in make.conf, the expansion of ${PORTDIR} used in make.globals is
> still set to the default.

Is this a bug in Portage, a design flaw or a feature? I mean, will this be
resolved in subsequent Portage versions or do I have to inform users about
this (this documentation will probably go live with .51)?

> >When the requested information or data is not available on your system,
> >Portage will retrieve it from the Internet.
>
> The SYNC variable is defined just after this, which implies that portage will
> automatically make use of rsync.

I don't understand your feedback here. The SYNC variable is the third
definition after this sentence, what is the issue here?

Do you mean that the SYNC definition should inform the reader that rsync is
used?

I've updated all the rest; it might take an hour before it's visible online
though. You might want to retake a look at the injecting explanation at
http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml?part=3&chap=5#doc_chap3

The title's now "Non-Portage Maintained Software", I'm open for other
suggestions.

Wkr,
Sven Vermeulen

--
Documentation & PR project leader

The Gentoo Project <<< http://www.gentoo.org >>>

On Sunday 10 October 2004 20:34, Sven Vermeulen wrote:
> On Sun, Oct 10, 2004 at 12:03:16AM +0900, Jason Stubbs wrote:
> > >A profile contains architecture-specific information for Portage, such
> > > as a list of core packages, packages that don't work or are masked-out
> > > by Gentoo developers.
> >
> > ... core packages and packages that either don't work or ...
>
> Actually I was referring to the list of core packages (the packages that
> are in the profile's system) and then to the packages that are masked out.
>
> For instance, the uclibc profile maskes out glibc.

Yep, I understood that. The grammar is slightly wrong is all - not that my
usage of grammar is the best ;) I can't explain it well but you have a list
of two items that are only separated by a comma. The second list contains an
or which makes it a little difficult to read, as the second part of the or
could apply to the second list item or it could indicate a third list item.
That explanation sucks but I hope you get what I mean.

> > >The PKGDIR variable defaults to ${PORTDIR}/packages which means that, if
> > > you alter the PORTDIR variable, the prebuilt binaries location is
> > > changed with it.
> > >
> > >The DISTDIR variable defaults to ${PORTDIR}/distfiles which means that,
> > > if you alter the PORTDIR variable, the source code location is changed
> > > with it.
> > >
> > >The BUILD_PREFIX variable defaults to ${PORTAGE_TMPDIR}/portage which
> > > means that, when you alter the PORTAGE_TMPDIR variable, the
> > > BUILD_PREFIX location changes with it.
> >
> > These three all have the same issue. The defaults are defined in
> > make.globals, which is parsed independently of make.conf. This means that
> > even if PORTDIR is changed in make.conf, the expansion of ${PORTDIR} used
> > in make.globals is still set to the default.
>
> Is this a bug in Portage, a design flaw or a feature? I mean, will this be
> resolved in subsequent Portage versions or do I have to inform users about
> this (this documentation will probably go live with .51)?

Well, I wouldn't call it a bug but I wouldn't call it a feature either. I'd
describe it as an artifact of the implementation, which I guess could be
called a design flaw. You'd need to talk to Nick about whether it can be
changed.

> > >When the requested information or data is not available on your system,
> > >Portage will retrieve it from the Internet.
> >
> > The SYNC variable is defined just after this, which implies that portage
> > will automatically make use of rsync.
>
> I don't understand your feedback here. The SYNC variable is the third
> definition after this sentence, what is the issue here?
>
> Do you mean that the SYNC definition should inform the reader that rsync is
> used?

Having SYNC directly following the above paragraph implies that the above
paragraph applies to the SYNC variable. For completess, I'll include the
whole lot.

>When the requested information or data is not available on your system,
>Portage will retrieve it from the Internet. The server locations for the
>various information and data channels are defined by the following variables:
>* GENTOO_MIRRORS defines a list of server locations which contain source code
> (distfiles)
>* PORTAGE_BINHOST defines a particular server location containing prebuilt
> packages for your system
>* SYNC defines a particular server which Portage uses to fetch the Portage
> tree from

The meaning I interpret from this is:

When the requested information is not available Portage will retrieve it. The
server locations are defined by: GENTOO_MIRRORS, PORTAGE_BINHOST, SYNC.

However, portage does not retrieve any information from the SYNC server unless
explictly told to.

> I've updated all the rest; it might take an hour before it's visible online
> though. You might want to retake a look at the injecting explanation at
> http://www.gentoo.org/doc/en/handbook/draft/handbook-x86.xml?part=3&chap=5#
>doc_chap3
>
> The title's now "Non-Portage Maintained Software", I'm open for other
> suggestions.

Thanks for that. I hope I didn't come across bad on this point. I will look at
it soon. Later on, I might make a small tool to help manage /etc/portage to
encourage it's correct usage. :)

Regards,
Jason Stubbs

--
gentoo-doc@gentoo.org mailing list

On Sun, Oct 10, 2004 at 09:15:35PM +0900, Jason Stubbs wrote:
> Yep, I understood that. The grammar is slightly wrong is all - not that my
> usage of grammar is the best ;) I can't explain it well but you have a list
> of two items that are only separated by a comma. The second list contains an
> or which makes it a little difficult to read, as the second part of the or
> could apply to the second list item or it could indicate a third list item.
> That explanation sucks but I hope you get what I mean.

I've tried to make it less sucky; I understand your concern but I'm having
difficulties fixing it without going to list every single aspect of a
profile (which is imho beyond the scope of that paragraph).

Any suggestions are greatly appreciated :)

> Well, I wouldn't call it a bug but I wouldn't call it a feature either. I'd
> describe it as an artifact of the implementation, which I guess could be
> called a design flaw. You'd need to talk to Nick about whether it can be
> changed.

I've updated the descriptions. When talking about PORTDIR and PORTAGE_TMPDIR
I've added the instructions that users might want to change the depending
variables (RPMDIR, PKGDIR, DISTDIR, BUILD_PREFIX) as well.

> >When the requested information or data is not available on your system,
> >Portage will retrieve it from the Internet. The server locations for the
> >various information and data channels are defined by the following variables:
> >* GENTOO_MIRRORS defines a list of server locations which contain source code
> > (distfiles)
> >* PORTAGE_BINHOST defines a particular server location containing prebuilt
> > packages for your system
> >* SYNC defines a particular server which Portage uses to fetch the Portage
> > tree from
>
> The meaning I interpret from this is:
>
> When the requested information is not available Portage will retrieve it. The
> server locations are defined by: GENTOO_MIRRORS, PORTAGE_BINHOST, SYNC.
>
> However, portage does not retrieve any information from the SYNC server unless
> explictly told to.

Ah, yes, now I get it :) I've changed the wording a little.

> Thanks for that. I hope I didn't come across bad on this point.

Of course not; I rather have it in correct shape before than after the
official release :)

> Later on, I might make a small tool to help manage /etc/portage to
> encourage it's correct usage. :)

Don't make it too userfriendly, otherwise users might use it without
understanding what they're doing. That's the exact reason why I've moved out
/etc/portage to the third part of the Gentoo Handbook, forcing users to read
more and understand the consequences.

Wkr,
Sven Vermeulen

--
Documentation & PR project leader

The Gentoo Project <<< http://www.gentoo.org >>>