Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!
Bug 142225 - document handling of blockers in handbook
Summary: document handling of blockers in handbook
Status: RESOLVED FIXED
Alias: None
Product: [OLD] Docs on www.gentoo.org
Classification: Unclassified
Component: Other documents (show other bugs)
Hardware: All Linux
: High normal (vote)
Assignee: Docs Team
URL: http://www.gentoo.org/doc/en/handbook...
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2006-07-30 14:42 UTC by BORGULYA Gábor
Modified: 2006-08-03 01:03 UTC (History)
1 user (show)

See Also:
Package list:
Runtime testing required: ---


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description BORGULYA Gábor 2006-07-30 14:42:09 UTC
This documentation bug report is a fork of bug#142212. The short history is
that I run `emerge --ask --verbose --update world', but two kinds of error
messages appeared, 
1) "Packages for the following atoms are either all masked or don't exist" and
2) "<=x11-base/xorg-x11-6.9 (is blocking x11-proto/xextproto-7.0.2)" or 
   "dev-python/f2py (is blocking dev-python/numpy-0.9.8)",
and the emerge failed.
After reading `emerge --help', `emerge --help world' and `man emerge' - which
should be sufficient as a start - I still did not know how to handle the situation and how to make emerge update the system.

I was suggested (in the above mentioned bug report)
- to read the changelogs of the packages involved
- to read the "Migrating to Modular X HOWTO"
  (http://www.gentoo.org/proj/en/desktop/x/x11/modular-x-howto.xml)
- to read /usr/portage/profiles/package.mask.
I found the 
- handbook part 3 chapter 3 
  (http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=3)
  useful, too.

I think the manpage of emerge should explain what to do if packages
block each other. A general way of handling blocking packages should
be described. If it is complicated to explain how to handle blocking packages
a new HOWTO could be created. In this case it would be essential that the
emerge manpage contained a link to this HOWTO.

I think the HOWTO should give explanation to the situation when a working
system can not be updated with `emerge world' because of blocking and masked
packages - it is not straitforward why stable, working packages get masked;
and not straitforward why coexisting packages installed without difficulties
are reported to be blocking each other during an update.
Comment 1 Jakub Moc (RETIRED) gentoo-dev 2006-07-30 14:58:54 UTC
Should be IMHO documented in 'Working with portage' part of handbook, a special howto sounds kinda strange. ;)

> Packages for the following atoms are either all masked or don't exist

This is unrelated and it's no error either and doesn't block anything, already tried to explain a couple of times in the other bug.
Comment 2 Łukasz Damentko (RETIRED) gentoo-dev 2006-07-30 15:22:29 UTC
Thank you for the suggestion but it's already covered in the Handbook blocking [1], masking [2]. 
If a package needs a separate howto, this howto is published in the project space by people maintaining this package and announced in the GWN. So i see no point in creating a separate doc on something as simple as emerge -C, emerge.

http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=1&sect4#doc_chap4_sect2

http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=1&sect4#doc_chap4_sect3
Comment 3 BORGULYA Gábor 2006-07-30 16:33:55 UTC
I agree that the Handbook is the best place to describe how to handle blocking 
packages.

> Thank you for the suggestion but it's already covered in the Handbook
> blocking [1], masking [2].
Thank you for the links, I read them thoroughly and they were useful for me. 

There are, however topics not covered in the sections you refered to:
- The masking section should mention that the reason of masking may be looked 
up in the changelog of the package. The location of changelogs has to be 
included, too.
- The masking section should mention that the
/usr/portage/profiles/package.mask file may contain useful information if we
encounter a masked package. If there are other useful files they should be 
mentioned, too. These files may give a hint which package to install instead.
- The masking section should mention that a package that used to be marked 
stable may go "package.mask" as in the case of net-print/hpoj: "deprecated - 
please use net-print/hplip now". And how to find this information.
- The section about blocking contains a sentence which I do not understand: 
"When one of these dependencies explicitly marks a package or virtual as 
being not compatible, it triggers a blockage." I am sorry if it is the 
weakness of my English, but I couldn't figure out the meaning. Could you 
please use a simpler sentence or a longer explanation?
- The section about blocking doesn't mention the "Migrating to Modular X 
HOWTO" (http://www.gentoo.org/proj/en/desktop/x/x11/modular-x-howto.xml)
although an `emerge --update world' nowadays probaly leads to pages of 
blocking errors.
- In my case I got "dev-python/f2py (is blocking dev-python/numpy-0.9.8)".
You say that the soultion is simple: if I want numpy I have to unmerge f2py. 
But I don't know why f2py is there at all. It is not part of my world file, 
it must have been installed as a depencency of an other software. I am afraid 
of unmerging it, because I fear that this other software will fail to work. 
If it would fail to work, I prefered not to upgrade the packages at all. The 
section should tell how to determine which was the software needing f2py, and 
how to determine if the updated version will be able to live without the f2py 
package. I.e. if I can safely unmerge f2py (that used to be necessary) or 
not.
- As I wrote earlier it is not straitforward why coexisting packages once 
installed without difficulties may be reported to be blocking each other 
during an update. This is the case with numpy and the other software that is 
depending on f2py. The blocking section should give an explanation to this 
(if it is not a rare exception).

The above are the topics I would like to see in the handbook.
But in my eyes the Handbook would not be sufficient solution - let's take my 
case:
1. I encountered the problem of blocking recently when I issued
`emerge --ask --verbose --update world'. 
2. I didn't understand the problem, so I read `emerge --help', `emerge --help 
world' and `man emerge'.
3. As the problem was not explained there I filed a bug report.

I think I did it right, but the best solution would be if I found the answer 
in the documentation. So the text of `emerge --help' or `man emerge' should 
be extended to point to the Handbook sections blocking and masking to spare 
the efforts of writing and answering bug reports.
Comment 4 Jakub Moc (RETIRED) gentoo-dev 2006-07-30 16:52:13 UTC
(In reply to comment #3)
> - In my case I got "dev-python/f2py (is blocking dev-python/numpy-0.9.8)".
> You say that the soultion is simple: if I want numpy I have to unmerge f2py. 
> But I don't know why f2py is there at all. It is not part of my world file, 
> it must have been installed as a depencency of an other software. I am afraid 
> of unmerging it, because I fear that this other software will fail to work.

I've already told you a couple of times that _nothing_ depends on it. If you don't believe me, then run 'equery d -all dev-python/f2py' to check for yourself.

> - As I wrote earlier it is not straitforward why coexisting packages once 
> installed without difficulties may be reported to be blocking each other 
> during an update.

Because they conflict, fex (see Bug 131833). 
Comment 5 Jakub Moc (RETIRED) gentoo-dev 2006-07-30 16:53:58 UTC
(In reply to comment #4)
> then run 'equery d -all dev-python/f2py' to check for yourself.

equery d -a dev-python/f2py actually...
Comment 6 Jan Kundrát (RETIRED) gentoo-dev 2006-07-30 16:54:39 UTC
Portage folks, could you please link to [1] in case an error message about blockers is printed?

[1] http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=1#blocked
Comment 7 Jan Kundrát (RETIRED) gentoo-dev 2006-07-30 17:03:44 UTC
(In reply to comment #3)
> - The masking section should mention that the reason of masking may be looked 
> up in the changelog of the package. The location of changelogs has to be 
> included, too.
> - The masking section should mention that the
> /usr/portage/profiles/package.mask file may contain useful information if we
> encounter a masked package. If there are other useful files they should be 
> mentioned, too. These files may give a hint which package to install instead.

[cut here]
These are the packages that would be merged, in order:

Calculating dependencies
!!! All ebuilds that could satisfy ">gcc-4.0" have been masked.
!!! One of the following masked packages is required to complete your request:
- sys-devel/gcc-4.1.0-r1 (masked by: ~x86 keyword)
- sys-devel/gcc-4.1.1 (masked by: ~x86 keyword)
- sys-devel/gcc-4.2.0_alpha20060715 (masked by: package.mask, missing keyword)
# Mark Loeser <halcy0n@gentoo.org> (11 Apr 2006)
# GCC 4.2 snapshots; use with extreme care and only report bugs if you have
# a patch

- sys-devel/gcc-4.0.2-r3 (masked by: missing keyword)
- sys-devel/gcc-4.0.3 (masked by: missing keyword)

For more information, see MASKED PACKAGES section in the emerge man page or
refer to the Gentoo Handbook.
[/cut here]

So, emerge already tells you. No point in documenting it once again, IMHO.

> - The masking section should mention that a package that used to be marked 
> stable may go "package.mask" as in the case of net-print/hpoj: "deprecated - 
> please use net-print/hplip now". And how to find this information.

Ask the guy who masked the package in question. Nothing that GDP/Portage can do.

> - The section about blocking contains a sentence which I do not understand: 
> "When one of these dependencies explicitly marks a package or virtual as 
> being not compatible, it triggers a blockage." I am sorry if it is the 
> weakness of my English, but I couldn't figure out the meaning. Could you 
> please use a simpler sentence or a longer explanation?

"A dep of some package says that it can't co-exist with some other package."

> - The section about blocking doesn't mention the "Migrating to Modular X 
> HOWTO" (http://www.gentoo.org/proj/en/desktop/x/x11/modular-x-howto.xml)
> although an `emerge --update world' nowadays probaly leads to pages of 
> blocking errors.

Unfortunately we can't do anything about that. It doesn't fit the Handbook and Portage can't know that such block is explained at that URL.

> - In my case I got "dev-python/f2py (is blocking dev-python/numpy-0.9.8)".
> You say that the soultion is simple: if I want numpy I have to unmerge f2py. 
> But I don't know why f2py is there at all. It is not part of my world file, 
> it must have been installed as a depencency of an other software. I am afraid 
> of unmerging it, because I fear that this other software will fail to work. 
> If it would fail to work, I prefered not to upgrade the packages at all. The 
> section should tell how to determine which was the software needing f2py, and 
> how to determine if the updated version will be able to live without the f2py 
> package. I.e. if I can safely unmerge f2py (that used to be necessary) or 
> not.

This one needs a reaction.

> - As I wrote earlier it is not straitforward why coexisting packages once 
> installed without difficulties may be reported to be blocking each other 
> during an update. This is the case with numpy and the other software that is 
> depending on f2py. The blocking section should give an explanation to this 
> (if it is not a rare exception).

Explained by jakub, IMHO.

> The above are the topics I would like to see in the handbook.
> But in my eyes the Handbook would not be sufficient solution - let's take my 
> case:
> 1. I encountered the problem of blocking recently when I issued
> `emerge --ask --verbose --update world'. 
> 2. I didn't understand the problem, so I read `emerge --help', `emerge --help 
> world' and `man emerge'.
> 3. As the problem was not explained there I filed a bug report.
> 
> I think I did it right, but the best solution would be if I found the answer 
> in the documentation. So the text of `emerge --help' or `man emerge' should 
> be extended to point to the Handbook sections blocking and masking to spare 
> the efforts of writing and answering bug reports.

Or Portage should have redirected you to the Handbook as I've requested several minutes ago.
Comment 8 BORGULYA Gábor 2006-07-30 17:18:30 UTC
(In reply to comment #4)
> > - In my case I got "dev-python/f2py (is blocking
> > dev-python/numpy-0.9.8)". You say that the soultion is simple: if I want
> > numpy I have to unmerge f2py. But I don't know why f2py is there at all.
> > It is not part of my world file, it must have been installed as a
> > depencency of an other software. I am afraid of unmerging it, because I
> > fear that this other software will fail to work.
>
> I've already told you a couple of times that _nothing_ depends on it. If
> you don't believe me, then run 'equery d -all dev-python/f2py' to check for
> yourself.

Thanks for showing the way how to decide which packages depend on a given package. True, nothing depends on f2py.

But how come then that f2py used to be a dependency of some software and is not a dependency any more? 
Is this usual or exceptional?
Is it possible to know which software needed f2py when f2py was installed

And can I generally safely unmerge any blocker without fearing of loosing functionality? Or do you advice to run `equery d -a ...' in such cases?

Sorry for my ignorance and fear. 
Comment 9 Zac Medico gentoo-dev 2006-07-30 20:05:18 UTC
(In reply to comment #6)
> Portage folks, could you please link to [1] in case an error message about
> blockers is printed?

It's now in svn r4053.
Comment 10 Jason Stubbs (RETIRED) gentoo-dev 2006-07-31 04:06:23 UTC
(In reply to comment #6)
> Portage folks, could you please link to [1] in case an error message about
> blockers is printed?
> 
> [1]
> http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=1#blocked

This was done before after which the handbook layout changed. Even if you can guarantee that the above URL is never going to change again, I'm already waiting for the AMD64 user filing a bug re recommending the wrong handbook...
Comment 11 Jan Kundrát (RETIRED) gentoo-dev 2006-07-31 04:20:14 UTC
(In reply to comment #10)
> This was done before after which the handbook layout changed. Even if you can
> guarantee that the above URL is never going to change again, I'm already
> waiting for the AMD64 user filing a bug re recommending the wrong handbook...

You can link to [2] instead but then the end users won't see links pointing to another chapters of the Handbook.

[2] http://www.gentoo.org/doc/en/handbook/hb-working-portage.xml#blocked
Comment 12 Xavier Neys (RETIRED) gentoo-dev 2006-07-31 16:04:56 UTC
(In reply to comment #10)
> (In reply to comment #6)
> > http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=2&chap=1#blocked
> 
> This was done before after which the handbook layout changed. Even if you can
> guarantee that the above URL is never going to change again, I'm already
> waiting for the AMD64 user filing a bug re recommending the wrong handbook...

First part is guaranteed to cover the installation, chapters and any other part can be shuffled any time. Linking to a full handbook will always work.
http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1#blocked
is guaranteed to work.


(In reply to comment #11)
> You can link to [2] instead but then the end users won't see links pointing to
> another chapters of the Handbook.
> 
> [2] http://www.gentoo.org/doc/en/handbook/hb-working-portage.xml#blocked

Linking directly to handbook files is not supported. It works now with some limitations. It used to give error 500 and I made it render some html.
Please don't rely too much on it.
Comment 13 Zac Medico gentoo-dev 2006-08-02 00:16:43 UTC
(In reply to comment #10)
> waiting for the AMD64 user filing a bug re recommending the wrong handbook...

I've added a note that the architechture is irrelevant.

(In reply to comment #12)
> can be shuffled any time. Linking to a full handbook will always work.
> http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?full=1#blocked

I've also updated to link to point to the full handbook.  Both changes are in svn r4087.
Comment 14 Xavier Neys (RETIRED) gentoo-dev 2006-08-03 01:03:08 UTC
As far as GDP is concerned, this bug is fixed.
Thanks.