Gentoo Websites Logo
Go to: Gentoo Home Documentation Forums Lists Bugs Planet Store Wiki Get Gentoo!

Bug 230989

Summary: sys-devel/icecream: Please write some documentation on how to set it up
Product: [OLD] Docs on www.gentoo.org Reporter: Friedrich Oslage (RETIRED) <bluebird>
Component: New DocumentationAssignee: Docs Team <docs-team>
Status: RESOLVED REMIND    
Severity: normal CC: hp-cluster, jacobgodserv, jlec
Priority: High    
Version: unspecified   
Hardware: All   
OS: Linux   
URL: http://dev.gentoo.org/~rane/icecream.xml
Whiteboard:
Package list:
Runtime testing required: ---
Attachments: Cleaned up version

Description Friedrich Oslage (RETIRED) gentoo-dev 2008-07-06 20:59:30 UTC
stop slacking and do it!
Comment 2 Friedrich Oslage (RETIRED) gentoo-dev 2008-07-17 17:02:00 UTC
(In reply to comment #1)
> http://gentoo-wiki.com/HOWTO_Setup_An_ICECREAM_Compile_Cluster
> 
Thanks for the hint, I can use it as a template :)
(Except the part about cross-compiling which is completly incorrect)
Comment 3 Friedrich Oslage (RETIRED) gentoo-dev 2008-08-02 17:30:00 UTC
Hi docs-team,

I finally manage to write some documentation about using icecream, I'd like you to  review it(for typos, stilistic issues) and then add it to www.gentoo.org/doc, so I can remove the (quite verbose) postinst message and just add a link to the documentation.

http://dev.gentoo.org/~bluebird/icecream.xml
http://dev.gentoo.org/~bluebird/icecream.xml?passthru=1

TIA :)
Comment 4 nm (RETIRED) gentoo-dev 2008-08-03 00:55:31 UTC
You need to get sys-devel/icecream stabilized first; we do not document ~arch-only packages.

** Coding style issues **

Please review our GuideXML document at http://www.gentoo.org/doc/en/xml-guide.xml -- it has more in-depth material on how to write well-formatted, valid guideXML, but I'll give you a few changes.

First, with the exception of content in <pre>, everything must be wrapped at 80 columns; you can do this in vim/gvim with ":set textwidth=80".

Next, no tabs. Tabs are forbidden. For <dl> and <ul>, just use two spaces for indenting.

Also, review your spelling and punctuation. There are several typos, missed spaces, etc. -- especially around the ICECC_VERSION sections.

** Content issues **

A better introduction would be nice, something that explains the rationale for actually using icecream on Gentoo. Right now it just says what it is. I suggest you add a paragraph explaining why one should use icecream, especially since established solutions like distcc are already available. (And we already have distcc/cross-compiling with distcc documents, too.) Icecream seems inherently less secure than distcc, so it is puzzling why one would use it rather than distcc.

Anyway, you've got a great start to the guide, so take a look at the things that need some cleanup. 
Comment 5 nm (RETIRED) gentoo-dev 2008-08-03 03:32:20 UTC
Wait a minute. This comes from gentoo-wiki.com?

Uh, this is a problem. The wiki admins have a history of blanket-relicensing everything on that site, without regards to any original licenses the author(s) may have placed it under.

I'm not sure that we'll be able to accept it, even though the wiki claims that if not otherwise specified, the license is public domain.

Several of the blanket relicenses occurred during 2006 and 2007 especially, so it would have affected this document.

docs-team, what do you think?
Comment 6 Friedrich Oslage (RETIRED) gentoo-dev 2008-08-03 09:24:37 UTC
Thanks for the hints, I'll fix them and look into getting icecream stable :)

> Wait a minute. This comes from gentoo-wiki.com?

Hm, not exactly. I did read then gentoo-wiki.com article before writing it but I didn't just copy & paste it. Is it still an issue?
Comment 7 Jan Kundrát (RETIRED) gentoo-dev 2008-08-04 20:11:25 UTC
(In reply to comment #4)
> Also, review your spelling and punctuation. There are several typos, missed
> spaces, etc. -- especially around the ICECC_VERSION sections.

You want to add spaces before each opening parenthesis and don't want to use <br/> because it sucks. There's also one s/don'T/don't/.

"As of 08/2008 portage HAS no explicit" (instead of "as").

> A better introduction would be nice, something that explains the rationale for
> actually using icecream on Gentoo. Right now it just says what it is. I suggest
> you add a paragraph explaining why one should use icecream, especially since
> established solutions like distcc are already available. (And we already have
> distcc/cross-compiling with distcc documents, too.) Icecream seems inherently
> less secure than distcc, so it is puzzling why one would use it rather than
> distcc.

It seems to me that the main reason for this (using binaries provided by box requesting the compilation) is eliminating the need to use exactly same GCC version/flavor on each box.
Comment 8 Łukasz Damentko (RETIRED) gentoo-dev 2009-02-07 03:41:44 UTC
Created attachment 181213 [details]
Cleaned up version

General cleanup. Improved the code to GuideXML standards, fixed a ton of typos, added missing spaces, replaced <br/> crap with more <p>s, fixed what jkt said should be fixed, added some <c>s around variables, removed tabs, fixed lists and did some other stuff I can't remember right now. Enjoy.

Summarising, now it isn't hedious and since icecream is stable now and since gentoo-wiki guide is dead for a while... how about publishing it?
Comment 9 Łukasz Damentko (RETIRED) gentoo-dev 2009-02-07 03:45:23 UTC
hp-cluster people, please review the guide.
Comment 10 Łukasz Damentko (RETIRED) gentoo-dev 2009-02-07 03:47:53 UTC
My version for reviewers: http://dev.gentoo.org/~rane/icecream.xml
Comment 11 Łukasz Damentko (RETIRED) gentoo-dev 2009-03-22 02:01:04 UTC
Bluebird, now that you're back from .away, please review the guide.
Comment 12 Friedrich Oslage (RETIRED) gentoo-dev 2009-03-22 16:06:06 UTC
> Bluebird, now that you're back from .away, please review the guide.

Did that, I fixed some more typos, added "In a nutshell: reasons to use icecream" and added an explanation why there is no FEATURES="icecream" (talked to zmedico about it some time ago).

Uploaded to http://dev.gentoo.org/~bluebird/icecream.xml

Docs-Team: Are we good to publish this?
Comment 13 Justin Lecher (RETIRED) gentoo-dev 2009-07-11 12:28:54 UTC
(In reply to comment #12)
> > Bluebird, now that you're back from .away, please review the guide.
> 
> Did that, I fixed some more typos, added "In a nutshell: reasons to use
> icecream" and added an explanation why there is no FEATURES="icecream" (talked
> to zmedico about it some time ago).
> 
Its not clear why there is no FEATURE="icecream". Don't we need it or is it broken?
Is distcc broken and thats why we have the FEATURE?

Thanks for writing the guide.
Comment 14 Jacob Godserv 2010-07-11 23:25:15 UTC
Stumbled across this bug, so I thought I'd post my documentation:
http://neuvoo.org/wiki/index.php?title=Icecream

It's got a license that's compatible with Gentoo's.
Comment 15 nm (RETIRED) gentoo-dev 2010-07-12 23:04:04 UTC
I think we'll have to close this one as CANTFIX for a few reasons:

1. The original reporter/writer has since retired. The revised version in his devspace is no longer available.
2. We never heard back from the icecream maintainer team (Hp-cluster@), if there still is one.
3. As noted in the last section of rane's version, icecream is a HUGE security risk. I'm not sure why it was ever added to the tree, especially since you have to implement massive hacks to get it working with Portage. A native solution like distcc is a much better idea.
4. While I appreciate Jacob's offer to use the well-written Neuvoo doc, it doesn't cover all the stuff our initial drafts do, and it has additional complicated things like emerge wrappers. Also, it's a huge chore to XMLify the wiki text.

For now I'll close as CANTFIX, but if anyone is willing to try to merge both the draft here/in rane's devspace with the Neuvoo wiki article, under the CC-By-SA 2.5 license, and GuideXMLified . . . please reopen! We will be happy to add that doc to the tree, finally.
Comment 16 Jacob Godserv 2010-07-13 03:10:38 UTC
(In reply to comment #15)
> 1. The original reporter/writer has since retired. The revised version in his
> devspace is no longer available.

Hardly a reason. Just write a new version. Piece of cake. ;)

> 2. We never heard back from the icecream maintainer team (Hp-cluster@), if
> there still is one.

In fact, I have. I had a discussion with him about certain issues I was having. Do you need his attention? I might be able to get it for you.

> 3. As noted in the last section of rane's version, icecream is a HUGE security
> risk. I'm not sure why it was ever added to the tree, especially since you have
> to implement massive hacks to get it working with Portage. A native solution
> like distcc is a much better idea.

Can we document those too? That's what the last bit of documentation did.

> 4. While I appreciate Jacob's offer to use the well-written Neuvoo doc, it
> doesn't cover all the stuff our initial drafts do, and it has additional
> complicated things like emerge wrappers. Also, it's a huge chore to XMLify the
> wiki text.

These are all concerns we can easily address, if you want to actually address them. I, personally, dislike wrappers personally (though I guess not to the point of excluding others' work on them in unofficial docs) which is why I implemented bug 272988.

> For now I'll close as CANTFIX, but if anyone is willing to try to merge both
> the draft here/in rane's devspace with the Neuvoo wiki article, under the
> CC-By-SA 2.5 license, and GuideXMLified . . . please reopen! We will be happy
> to add that doc to the tree, finally.

I won't be able to for quite some time, but I'll certainly put it on my todo list. If someone else can take this, though, please do! This is going to be on the back-burner, as far as I am concerned, for over half a year at least.
Comment 17 Jacob Godserv 2010-07-13 03:18:27 UTC
I apologize for the tone in my last comment. I had just finished reading another doc bug where conversation escalated to flaming, and I carried that over to this bug. I should've slept on "it" before posting.
Comment 18 nm (RETIRED) gentoo-dev 2010-07-13 04:50:10 UTC
(In reply to comment #17)
> I apologize for the tone in my last comment. I had just finished reading
> another doc bug where conversation escalated to flaming, and I carried that
> over to this bug. I should've slept on "it" before posting.
> 

No offense taken, at least from me. I didn't feel like you overstepped any boundaries.

Anyway, I'll change this from CANTFIX to REMIND -- hopefully one of these days we can get the draft fixed up.