[gentoo-osx] Documentation Update

[gentoo-osx] Documentation Update

[Hasan Khalil]

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

To all interested:

I've gone through and reworked[1] significant portions of the 'Gentoo  
For Mac OS X Installation and Usage Guide' -- for those not familiar,  
that's our official guide[2] available in the gentoo.org docs  
section. I have also made a patch[3] as well as the full source[4] of  
the updated XML available.

Please provide any feedback you may have, so that I can make any  
corrections and then submit to the official gentoo documentation team  
(of which I am certainly not a member by any means).

Please note that there's probably a good deal more documentation work  
to be done, but I feel that it's probably smarter to get the updates  
published in stages rather than all at once. At the very least, it  
allows for better QA analysis of each revision.

Kito: I apologize in advance if I butchered the description of the  
progressive profile. Please feel free to slap me with a very large,  
very freshly-dead herring, and submit corrections as necessary.

Translators: You might want to hold off on this until we have a  
finalized draft submitted to the official docs team. Wouldn't want to  
cause you unnecessary work.

Thanks,
     Hasan

[1] http://dev.gentoo.org/~gongloo/macos/doc
[2] http://www.gentoo.org/doc/en/macos-guide.xml
[3] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml.diff
[4] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Documentation Update

[Grobian]

Two small things that I don't know for sure:

| Warning: Using any shell besides bash is currenly unsupported and most
| likely won't work. You should change your default shell in Terminal by
| clicking on Terminal->Preferences (in the menu bar), chosing the
| "Execute this command" option, and entering /bin/bash.

How likely is this?  Of course I ignored this warning when installing my 
Gentoo, because I feel hopelessly lost in bash.  On the one hand, is it 
known what causes trouble? and on the other hand, considering the 
default shell is bash from 10.3 (at least 10.4) also for the root 
account, and everything is done using "sudo su", how likely is it the 
user will use a different shell for the root user than the system 
provided one?  On top of this, whenever the whole emerge system is 
getting into action a bash shell is forked from python I think, so what 
relevance is the parent shell to that?

| Note: With each emerge --sync, the /usr/portage directory is wiped of
| any user changes. Be sure to keep a log of your development efforts
| and report your findings to the Gentoo for Mac OS X team.

Ehm, is this really true?  I vaguely remember in my first days doing 
this thinking a sync would wipe out my mess, then coming to the 
conclusion it didn't.  I don't know exactly how rsync is being called, 
but if a file is newer on the target host, than on the server, is it 
overwritten?  I thought rsync is able to optimise by only beaming over 
the changed files on the server side, preventing copying all of the 
files (550MB currently).  Somebody slap me with the man page and the 
massive number of options supplied to rsync when running emerge sync if 
I see ghosts here...


Hasan Khalil wrote:
> To all interested:
> 
> I've gone through and reworked[1] significant portions of the 'Gentoo 
> For Mac OS X Installation and Usage Guide' -- for those not familiar, 
> that's our official guide[2] available in the gentoo.org docs section. I 
> have also made a patch[3] as well as the full source[4] of the updated 
> XML available.
> 
> Please provide any feedback you may have, so that I can make any 
> corrections and then submit to the official gentoo documentation team 
> (of which I am certainly not a member by any means).
> 
> Please note that there's probably a good deal more documentation work to 
> be done, but I feel that it's probably smarter to get the updates 
> published in stages rather than all at once. At the very least, it 
> allows for better QA analysis of each revision.
> 
> Kito: I apologize in advance if I butchered the description of the 
> progressive profile. Please feel free to slap me with a very large, very 
> freshly-dead herring, and submit corrections as necessary.
> 
> Translators: You might want to hold off on this until we have a 
> finalized draft submitted to the official docs team. Wouldn't want to 
> cause you unnecessary work.
> 
> Thanks,
>     Hasan
> 
> [1] http://dev.gentoo.org/~gongloo/macos/doc
> [2] http://www.gentoo.org/doc/en/macos-guide.xml
> [3] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml.diff
> [4] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml
> 
> -- 
> 
> Hasan Khalil
> eBuild and Porting Co-Lead
> Gentoo for Mac OS X
> 

-- 
Fabian Groffen
eBuild && Porting
Gentoo for Mac OS X
-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Documentation Update

[Kito]

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

On Aug 10, 2005, at 12:42 AM, Grobian wrote:

> Two small things that I don't know for sure:
>
> | Warning: Using any shell besides bash is currenly unsupported and  
> most
> | likely won't work. You should change your default shell in  
> Terminal by
> | clicking on Terminal->Preferences (in the menu bar), chosing the
> | "Execute this command" option, and entering /bin/bash.
>
> How likely is this?  Of course I ignored this warning when  
> installing my Gentoo, because I feel hopelessly lost in bash.  On  
> the one hand, is it known what causes trouble? and on the other  
> hand, considering the default shell is bash from 10.3 (at least  
> 10.4) also for the root account, and everything is done using "sudo  
> su", how likely is it the user will use a different shell for the  
> root user than the system provided one?  On top of this, whenever  
> the whole emerge system is getting into action a bash shell is  
> forked from python I think, so what relevance is the parent shell  
> to that?

Yeah, I've always used zsh myself, with no problems to speak of.

>
>> Please note that there's probably a good deal more documentation  
>> work to be done, but I feel that it's probably smarter to get the  
>> updates published in stages rather than all at once. At the very  
>> least, it allows for better QA analysis of each revision.
>> Kito: I apologize in advance if I butchered the description of the  
>> progressive profile. Please feel free to slap me with a very  
>> large, very freshly-dead herring, and submit corrections as  
>> necessary.

Attached is a rough description of the progressive profile.

I would suggest getting rid of the section telling users to keyword  
ebuilds directly, and instead point them to the /etc/portage/* files.  
As more of the base-system packages get the ~ppc-macos keyword for  
the progressive profile, I suspect users will be confused when they  
see an ebuild with the ~ppc-macos keyword but still being unable to  
emerge as a result of it being masked for file collisions on the  
standard profiles.

We should probably also mention the fact that the installer has the  
bug of portage not knowing its installed, so probably just tell them  
to `FEATURES="-collision-protect" sudo emerge --nodeps portage` to  
avoid the endless dup bugs being filed and the same question being  
asked in #-osx.

Thanks for doing this much-needed update!



[-- Attachment #2: progressive.txt --]
[-- Type: text/plain, Size: 1253 bytes --]

The progressive profile provides a customized Mac OS X environment via the  portage packae manager.
Many of the default OS X system commands, libraries, drivers, and development tools  may be replaced 
with their open source counterparts while leaving closed-source proprietary utilities and frameworks, 
such as Quicktime, Quartz, and Aqua in tact.

This allows users and developers to take full advantage of the latest software from a wide range 
of open source resources such as Darwin/OpenDarwin, FreeBSD, NetBSD, Linux, and of course Gentoo, 
while still enjoying the benefits of the beautiful operating system we've all come to 
know and love...The best of both worlds indeed!

Who would want to use this? As Gentoo for OS X is still in its infancy (dare we say alpha?), so 
is the progressive profile. Currently it is probably best suited for developers and advanced users.
There are a number of reasons people use this profile - to install Apple system headers and libraries
not included with OS X (to facilitate Darwin development), security updates, custom kernels, etc.

Will it break your OS X install? probably not...but as previously stated, this is alpha software,
so one can never be sure. Use at your own risk. Now go tame that Tiger!


[-- Attachment #3: Type: text/plain, Size: 2 bytes --]

[gentoo-osx] xephem emerges (for those of us who are astronomers)

[P.A.A.]

Hi,

For those of us who are astronomers, I successfully emerged xephem by 
using the keywords

"ppc-macos ~ppc-macos ppc ~ppc"

Cheers,
Patrick

Alessandra & Assoc. Intl.
Dallas * Ft. Worth, Texas  U.S.A.
(214) 335-0278
http://homepage.mac.com/adijedi/

-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] xephem emerges (for those of us who are astronomers)

[Hasan Khalil]

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


On Aug 10, 2005, at 11:04, P.A.A. wrote:

> Hi,
>
> For those of us who are astronomers, I successfully emerged xephem  
> by using the keywords
>
> "ppc-macos ~ppc-macos ppc ~ppc"
>
> Cheers,
> Patrick
>
> Alessandra & Assoc. Intl.
> Dallas * Ft. Worth, Texas  U.S.A.
> (214) 335-0278
> http://homepage.mac.com/adijedi/

Patrick,

Great!

This sort of message should not be addressed to gentoo-osx@, but  
should rather be reported via https://bugs.gentoo.org.

Thanks,
     Hasan

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Documentation Update

[Hasan Khalil]

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


On Aug 10, 2005, at 24:42, Grobian wrote:

> | Note: With each emerge --sync, the /usr/portage directory is  
> wiped of
> | any user changes. Be sure to keep a log of your development efforts
> | and report your findings to the Gentoo for Mac OS X team.
>
> Ehm, is this really true?  I vaguely remember in my first days  
> doing this thinking a sync would wipe out my mess, then coming to  
> the conclusion it didn't.  I don't know exactly how rsync is being  
> called, but if a file is newer on the target host, than on the  
> server, is it overwritten?  I thought rsync is able to optimise by  
> only beaming over the changed files on the server side, preventing  
> copying all of the files (550MB currently).  Somebody slap me with  
> the man page and the massive number of options supplied to rsync  
> when running emerge sync if I see ghosts here...

AFAIK, yes. Any time I've made changes to /usr/portage and then did a  
sync, regardless of whether or not there was an actual update to that  
file in the meanwhile, my changes were overwritten.

Feel free to attack me with a medium-sized herring if I'm completely  
wrong in throwing in said <note>. I just thought that note would be a  
nice thing to have in there for anyone who was confused at this  
functionality. If anyone feels as though it shouldn't be there,  
please let me know and I'd be glad to remove it.

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Documentation Update

[Hasan Khalil]

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


On Aug 10, 2005, at 10:50, Kito wrote:

> On Aug 10, 2005, at 12:42 AM, Grobian wrote:
>
>
>> Two small things that I don't know for sure:
>>
>> | Warning: Using any shell besides bash is currenly unsupported  
>> and most
>> | likely won't work. You should change your default shell in  
>> Terminal by
>> | clicking on Terminal->Preferences (in the menu bar), chosing the
>> | "Execute this command" option, and entering /bin/bash.
>>
>> How likely is this?  Of course I ignored this warning when  
>> installing my Gentoo, because I feel hopelessly lost in bash.  On  
>> the one hand, is it known what causes trouble? and on the other  
>> hand, considering the default shell is bash from 10.3 (at least  
>> 10.4) also for the root account, and everything is done using  
>> "sudo su", how likely is it the user will use a different shell  
>> for the root user than the system provided one?  On top of this,  
>> whenever the whole emerge system is getting into action a bash  
>> shell is forked from python I think, so what relevance is the  
>> parent shell to that?
>>
>
> Yeah, I've always used zsh myself, with no problems to speak of.

The note has been deleted in the latest revision. Thanks Kito and  
Fabian for pointing this out.

>>> Please note that there's probably a good deal more documentation  
>>> work to be done, but I feel that it's probably smarter to get the  
>>> updates published in stages rather than all at once. At the very  
>>> least, it allows for better QA analysis of each revision.
>>> Kito: I apologize in advance if I butchered the description of  
>>> the progressive profile. Please feel free to slap me with a very  
>>> large, very freshly-dead herring, and submit corrections as  
>>> necessary.
>
> Attached is a rough description of the progressive profile.

Okay, looks like you wrote a good deal there, and I like it. I had  
originally planned on having at least one separate section (possibly  
one per profile) on just what the different profiles were all about,  
but I felt it would be better to implement the changes in phases.  
That being said, I think it's wise to hold off on it and just provide  
a short description for now. Is the short description on there  
unacceptable, even as it's temporary?

Furthermore, I'm not sure that the installation/usage guide, at least  
in its current form, would be a good place for this information. What  
I'd like to see is for the guide to be expanded into a proper book  
with separate pages on each important detail (for now, I see at least  
4 pages: Project/Installation Notes, Installation Guide, Usage Guide,  
Troubleshooting/Known Issues/Whatever). Before doing anything of the  
sort, I'll consult this mailing list, of course. :)

> I would suggest getting rid of the section telling users to keyword  
> ebuilds directly, and instead point them to the /etc/portage/*  
> files. As more of the base-system packages get the ~ppc-macos  
> keyword for the progressive profile, I suspect users will be  
> confused when they see an ebuild with the ~ppc-macos keyword but  
> still being unable to emerge as a result of it being masked for  
> file collisions on the standard profiles.

I completely agree. I'd really like to ditch the whole section in  
exchange for a paragraph and a link to some already existing  
resource, if some such pertinent resource already exists (maybe just  
refer them to `man portage`?). I don't plan on changing it with this  
release, though; I'd really like to get this through the door as  
quickly as possible since there are some important alterations there.

> We should probably also mention the fact that the installer has the  
> bug of portage not knowing its installed, so probably just tell  
> them to `FEATURES="-collision-protect" sudo emerge --nodeps  
> portage` to avoid the endless dup bugs being filed and the same  
> question being asked in #-osx.

Absolutely. I'll add this Real Soon Now(tm).

Thanks all for your feedback. Any other issues?

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Documentation Update

[Kito]

On Aug 10, 2005, at 11:58 AM, Hasan Khalil wrote:


>>>> Please note that there's probably a good deal more documentation  
>>>> work to be done, but I feel that it's probably smarter to get  
>>>> the updates published in stages rather than all at once. At the  
>>>> very least, it allows for better QA analysis of each revision.
>>>> Kito: I apologize in advance if I butchered the description of  
>>>> the progressive profile. Please feel free to slap me with a very  
>>>> large, very freshly-dead herring, and submit corrections as  
>>>> necessary.
>>>>
>>
>> Attached is a rough description of the progressive profile.
>>
>
> Okay, looks like you wrote a good deal there, and I like it. I had  
> originally planned on having at least one separate section  
> (possibly one per profile) on just what the different profiles were  
> all about, but I felt it would be better to implement the changes  
> in phases. That being said, I think it's wise to hold off on it and  
> just provide a short description for now. Is the short description  
> on there unacceptable, even as it's temporary?
>
> Furthermore, I'm not sure that the installation/usage guide, at  
> least in its current form, would be a good place for this  
> information. What I'd like to see is for the guide to be expanded  
> into a proper book with separate pages on each important detail  
> (for now, I see at least 4 pages: Project/Installation Notes,  
> Installation Guide, Usage Guide, Troubleshooting/Known Issues/ 
> Whatever). Before doing anything of the sort, I'll consult this  
> mailing list, of course. :)
>

Hmmm, not sure I agree... Since the profile is something that should  
be decided during bootstrap.... Since this is what we have, why not  
put it on there now? Sure when this page gets obscenely verbose, we  
can start splitting it up, but I think it would be fine to have  
descriptions there for now...

>
>> I would suggest getting rid of the section telling users to  
>> keyword ebuilds directly, and instead point them to the /etc/ 
>> portage/* files. As more of the base-system packages get the ~ppc- 
>> macos keyword for the progressive profile, I suspect users will be  
>> confused when they see an ebuild with the ~ppc-macos keyword but  
>> still being unable to emerge as a result of it being masked for  
>> file collisions on the standard profiles.
>>
>
> I completely agree. I'd really like to ditch the whole section in  
> exchange for a paragraph and a link to some already existing  
> resource, if some such pertinent resource already exists (maybe  
> just refer them to `man portage`?). I don't plan on changing it  
> with this release, though; I'd really like to get this through the  
> door as quickly as possible since there are some important  
> alterations there.
>

Why the big hurry? seems if we are going through the trouble now,  
might as well kill all the birds we can with this rock ;)

>
>> We should probably also mention the fact that the installer has  
>> the bug of portage not knowing its installed, so probably just  
>> tell them to `FEATURES="-collision-protect" sudo emerge --nodeps  
>> portage` to avoid the endless dup bugs being filed and the same  
>> question being asked in #-osx.
>>
>
> Absolutely. I'll add this Real Soon Now(tm).
>
> Thanks all for your feedback. Any other issues?
>
> --
>
> Hasan Khalil
> eBuild and Porting Co-Lead
> Gentoo for Mac OS X
>
>

-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Documentation Update

[Grobian]

Hasan Khalil wrote:
> 
> On Aug 10, 2005, at 24:42, Grobian wrote:
> 
>> | Note: With each emerge --sync, the /usr/portage directory is wiped of
>> | any user changes. Be sure to keep a log of your development efforts
>> | and report your findings to the Gentoo for Mac OS X team.
>>
>> Ehm, is this really true?  I vaguely remember in my first days doing 
>> this thinking a sync would wipe out my mess, then coming to the 
>> conclusion it didn't.  I don't know exactly how rsync is being called, 
>> but if a file is newer on the target host, than on the server, is it 
>> overwritten?  I thought rsync is able to optimise by only beaming over 
>> the changed files on the server side, preventing copying all of the 
>> files (550MB currently).  Somebody slap me with the man page and the 
>> massive number of options supplied to rsync when running emerge sync 
>> if I see ghosts here...
> 
> AFAIK, yes. Any time I've made changes to /usr/portage and then did a 
> sync, regardless of whether or not there was an actual update to that 
> file in the meanwhile, my changes were overwritten.
> 
> Feel free to attack me with a medium-sized herring if I'm completely 
> wrong in throwing in said <note>. I just thought that note would be a 
> nice thing to have in there for anyone who was confused at this 
> functionality. If anyone feels as though it shouldn't be there, please 
> let me know and I'd be glad to remove it.

I'm just unsure about it.  It think it would be best to anyhow 
disencourage people to mess with their /usr/portage/ (shoot no, auto 
completion here ;)).  I learnt it somehow the hard way that it is not 
'handy' to hack that tree ;)
/me mumbles something about lost sources, etc...


-- 
Fabian Groffen
eBuild && Porting
Gentoo for Mac OS X
-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Documentation Update

[Grobian]

Hasan Khalil wrote:
> Thanks all for your feedback. Any other issues?

yes, maybe a little bit off topic, but could we put somewhere that 
people please, please, please write the full name of a package in a bug 
instead of "package X compiles"?  It takes too long to do an emerge -p X 
to find out where in the tree it is.  Having dev-foo/X would be so much 
nicer!

Ok, probably noone is going to do it, so I had some evil thoughts of 
hooking MonetDB up for the job in evilish raw MIL mode... or even MAL if 
the startup time still is too big.  These are big evil plans, and I need 
a holiday for it, I think, just to get rid of some personal frustration ;)


-- 
Fabian Groffen
eBuild && Porting
Gentoo for Mac OS X
-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Documentation Update

[Hasan Khalil]

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


On Aug 10, 2005, at 12:18, Kito wrote:

> Sure when this page gets obscenely verbose, we can start splitting  
> it up, but I think it would be fine to have descriptions there for  
> now...

You're right. Done. I tried to condense things while taking advantage  
of guide XML formatting as much as possible. Throw down a herring  
where you feel that my editing was unjust, and I'll see about fixing  
things up to everyone's satisfaction.

>> I'd really like to ditch the whole section in exchange for a  
>> paragraph and a link to some already existing resource, if some  
>> such pertinent resource already exists (maybe just refer them to  
>> `man portage`?). I don't plan on changing it with this release,  
>> though; I'd really like to get this through the door as quickly as  
>> possible since there are some important alterations there.

Also done.

Let me know if you (the collective 'you', here) think changes need to  
be made, specifically to these areas but anywhere else in the  
document as well.

Thanks for your feedback thus far.

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Documentation Update

[Joseph Jezak]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

> yes, maybe a little bit off topic, but could we put somewhere that
> people please, please, please write the full name of a package in a bug
> instead of "package X compiles"?  It takes too long to do an emerge -p X
> to find out where in the tree it is.  Having dev-foo/X would be so much
> nicer!

Make the shell do your work for you!

cd /usr/portage/*/X works 99% of the time. :)

- -Joe
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFC+0PQwGq7BLLARfoRAvQeAKCyeLTrWNi3OvQ8n5FO424KcM5c7gCguISe
MJH4nbt+ABJ4jqbj9SiLaTY=
=MjAf
-----END PGP SIGNATURE-----
-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Documentation Update

[Grobian]

On Thu, August 11, 2005 14:25, Joseph Jezak wrote:
>> yes, maybe a little bit off topic, but could we put somewhere that
>> people please, please, please write the full name of a package in a bug
>> instead of "package X compiles"?  It takes too long to do an emerge -p X
>> to find out where in the tree it is.  Having dev-foo/X would be so much
>> nicer!
>
> Make the shell do your work for you!
>
> cd /usr/portage/*/X works 99% of the time. :)

Hmmm, never thought of that one!  Thanks!

-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Documentation Update

[Hasan Khalil]

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


On Aug 10, 2005, at 13:09, Grobian wrote:

> could we put somewhere that people please, please, please write the  
> full name of a package in a bug instead of "package X compiles"?

Added last night, and figured I'd give it a bit more thought before  
announcing it, but then realized that it'd be better to hold off on  
my own thoughts and get the feedback of the team instead/first.

Please revise and see if there are any other entries to the table in  
section 2.3 that should be there but aren't. I kept it pretty simple  
for now, since that sort of information should really be covered in a  
policy page and not the installation/usage guide. Yet another plea  
for book-format documentation (let's avoid feature creep for now,  
though). :)

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

[gentoo-osx] Re: Documentation Update

[Hasan Khalil]

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


On Aug 9, 2005, at 22:10, Hasan Khalil wrote:

> To all interested:
>
> I've gone through and reworked[1] significant portions of the  
> 'Gentoo For Mac OS X Installation and Usage Guide' -- for those not  
> familiar, that's our official guide[2] available in the gentoo.org  
> docs section. I have also made a patch[3] as well as the full source 
> [4] of the updated XML available.

...

> [1] http://dev.gentoo.org/~gongloo/macos/doc
> [2] http://www.gentoo.org/doc/en/macos-guide.xml
> [3] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml.diff
> [4] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml

Thanks for all your feedback, corrections, and additions, everybody.  
All of the discussed changes should be reflected in the latest HTML/ 
XML/diff by now (same locations as above). Please let me know if I've  
missed something, or if anyone has anything extra to add before we  
send in this revision (version 1.7) to the official Gentoo  
documentation team.

Thanks again for all your help; couldn't do it without you.

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Re: Documentation Update

[Grobian]

Sorry to start from scratch again... but:

Section 3 (Using CVS)
Although this section itself is ok, it some sort of comes out of the blue.
 Why the hell whould I want to use CVS?  What is CVS anyway?  I feel it
needs a little introduction like:

>>> begin
It is possible to use a CVS version of the portage tree.  This is not
recommended for average users, and only required for developers.
<<< end
Where the hell is this necessary for anyway?  A developer will know (s)he
needs CVS in order to do something, right?  I feel developer information
is somehow misplaced on a end-user document.  Perhaps we better move it
into a page on the wiki.

By the way, I remember that I first checked out the tree on my
/Volumes/Scratch partition which is HFS+.  I never experienced any problem
with it...



On Fri, August 12, 2005 04:42, Hasan Khalil wrote:
>
> On Aug 9, 2005, at 22:10, Hasan Khalil wrote:
>
>> To all interested:
>>
>> I've gone through and reworked[1] significant portions of the
>> 'Gentoo For Mac OS X Installation and Usage Guide' -- for those not
>> familiar, that's our official guide[2] available in the gentoo.org
>> docs section. I have also made a patch[3] as well as the full source
>> [4] of the updated XML available.
>
> ...
>
>> [1] http://dev.gentoo.org/~gongloo/macos/doc
>> [2] http://www.gentoo.org/doc/en/macos-guide.xml
>> [3] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml.diff
>> [4] http://dev.gentoo.org/~gongloo/macos/doc/macos-guide.xml
>
> Thanks for all your feedback, corrections, and additions, everybody.
> All of the discussed changes should be reflected in the latest HTML/
> XML/diff by now (same locations as above). Please let me know if I've
> missed something, or if anyone has anything extra to add before we
> send in this revision (version 1.7) to the official Gentoo
> documentation team.
>
> Thanks again for all your help; couldn't do it without you.
>
> --
>
> Hasan Khalil
> eBuild and Porting Co-Lead
> Gentoo for Mac OS X
>
>


-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Re: Documentation Update

[Hasan Khalil]

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


On Aug 12, 2005, at 02:59, Grobian wrote:

> Sorry to start from scratch again... but:

Don't apologize; this was my intention. :)

> Section 3 (Using CVS)

...

> I feel developer information
> is somehow misplaced on a end-user document.

I agree. Once we have a proper 'book'-formatted documentation, there  
will be a chapter (at least one) on developer documentation for  
Gentoo for Mac OS X.

Said section has been in the documentation before and I didn't remove  
it. CVS isn't even available to non-developers, except via the web- 
based front-end.

I completely agree with you on this point, so:

Done.

Anything else? Keep it coming. :)

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Re: Documentation Update

[Grobian]

Hasan Khalil wrote:
> Anything else? Keep it coming. :)

Yes:

|In order to install Gentoo for Mac OS X, you must have the following 
|software already installed:
|
|    * Mac OS 10.3 or later
|    * XCode Tools 1.2 or later

I've been messing with my Panther and came to the conclusion that XCode 
1.0 shipped with the installation CD misses a lot of tools.  Hence I 
would propose to require the latest and greatest for both supported 
platforms:

* Mac OS 10.3 (Panther)
* XCode Tools 1.5

or

* Mac OS 10.4 (Tiger)
* XCode Tools 2.1

Reason for requiring 2.1 is that some linker bugs are solved in 2.1 that 
are apparent in 2.0, and gcc-4 is upstream compatible.  Requiring XCode 
1.5 on Panther is good for getting ant 1.6.1 which is fairly decent IMHO.


-- 
Fabian Groffen
eBuild && Porting
Gentoo for Mac OS X
-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Re: Documentation Update

[Hasan Khalil]

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


On Aug 21, 2005, at 07:11, Grobian wrote:

> I would propose to require the latest and greatest for both  
> supported platforms

Done. Thanks for pointing this out.

--

Hasan Khalil
eBuild and Porting Co-Lead
Gentoo for Mac OS X


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

Re: [gentoo-osx] Re: Documentation Update

[Grobian]

On Sun, August 21, 2005 18:56, Hasan Khalil wrote:
>
> On Aug 21, 2005, at 07:11, Grobian wrote:
>
>> I would propose to require the latest and greatest for both
>> supported platforms
>
> Done. Thanks for pointing this out.
>

Another thing that crossed my mind when going to work this morning:

When people submit bugs for working/new packages, they usually tell it
works fine, or in some cases that they applied a little patch to get it
working.  However, before even thinking of keywording, I want to know
whether the package reasonably works.  That means, I want to do some small
sanity check, or just functional check that the application or library
appears to work as expected.  I think you cannot expect any dev to know
every package in portage, let alone being common with using it.  So I'd
propose to add a little note on the "reporting bugs" section that asks the
users to -- if they can come up with it:
1) in case of an application tell us how you can test it works: example,
streamripper, do streamripper http://some.host.com/music path/to/bla.mp3,
listen to the mp3, it appears to work fine
2) in case of a library tell us what application can be used to test it,
preferable small and direct: example, libpcre, emerge mp with USE flag
pcre, start mp on a file, press Ctrl-a navigate in the menu to search,
type a regular expression search like .(build|merge|keyword)+, check it
matches an appropriate string

-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Re: Documentation Update

[Mike Z.]

On 25/08/2005, at 3:36 PM, Grobian wrote:

>>
>>
>
> Another thing that crossed my mind when going to work this morning:
>
> When people submit bugs for working/new packages, they usually tell it
> works fine, or in some cases that they applied a little patch to  
> get it
> working.  However, before even thinking of keywording, I want to know
> whether the package reasonably works.  That means, I want to do  
> some small
> sanity check, or just functional check that the application or library
> appears to work as expected.  I think you cannot expect any dev to  
> know
> every package in portage, let alone being common with using it.  So  
> I'd
> propose to add a little note on the "reporting bugs" section that  
> asks the
> users to -- if they can come up with it:
> 1) in case of an application tell us how you can test it works:  
> example,
> streamripper, do streamripper http://some.host.com/music path/to/ 
> bla.mp3,
> listen to the mp3, it appears to work fine
> 2) in case of a library tell us what application can be used to  
> test it,
> preferable small and direct: example, libpcre, emerge mp with USE flag
> pcre, start mp on a file, press Ctrl-a navigate in the menu to search,
> type a regular expression search like .(build|merge|keyword)+,  
> check it
> matches an appropriate string
>

Definitely, compilation is fine, but you need to have some sort of  
runtime testing as well. On the note of libraries, I would think,  
rather than keywording libraries that compile, we should wait until  
an application that requires them also needs to be keyworded. This  
will probably depend on which library it is, but it'd mean that we  
have a full deptree for each application, as well as a useful real- 
world test case.

Mike Z. [shootingstar]


-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Re: Documentation Update

[Grobian]

Mike Z. wrote:
> Definitely, compilation is fine, but you need to have some sort of 
> runtime testing as well. On the note of libraries, I would think, rather 
> than keywording libraries that compile, we should wait until an 
> application that requires them also needs to be keyworded. This will 
> probably depend on which library it is, but it'd mean that we have a 
> full deptree for each application, as well as a useful real-world test 
> case.

This is in general the case.  We cannot keyword a library without having 
it tested.  My keyword for mp (the editor) was an example of this, I 
needed something small to test libpcre.  I think when people report a 
library working/compiling, they use the library in some application. 
Maybe that application is not in portage, or so big that it isn't an 
appropriate test case, but I'd still like to keyword (unstable) 
libraries before a separate bug for an application using the library is 
there, because it's enormously annoying to have to keyword a whole tree 
of dependencies to figure out the 6th level dependency does not and will 
never compile.


-- 
Fabian Groffen
Gentoo for Mac OS X
-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Re: Documentation Update

[Mike Z.]

On 26/08/2005, at 1:31 PM, Grobian wrote:

>
>
> Mike Z. wrote:
>
>> Definitely, compilation is fine, but you need to have some sort of  
>> runtime testing as well. On the note of libraries, I would think,  
>> rather than keywording libraries that compile, we should wait  
>> until an application that requires them also needs to be  
>> keyworded. This will probably depend on which library it is, but  
>> it'd mean that we have a full deptree for each application, as  
>> well as a useful real-world test case.
>>
>
> This is in general the case.  We cannot keyword a library without  
> having it tested.  My keyword for mp (the editor) was an example of  
> this, I needed something small to test libpcre.  I think when  
> people report a library working/compiling, they use the library in  
> some application. Maybe that application is not in portage, or so  
> big that it isn't an appropriate test case,

It's a good point, that's why I mentioned that libraries would need  
to be assessed on a case-by-case basis, (although applications  
outside of portage are outside our scope).

> but I'd still like to keyword (unstable) libraries before a  
> separate bug for an application using the library is there, because  
> it's enormously annoying to have to keyword a whole tree of  
> dependencies to figure out the 6th level dependency does not and  
> will never compile.

That wasn't exactly my point, my point was that we should hold off  
keywording libraries until they will actually be used by an  
application that is keyworded, and hence properly tested.

With libraries it's important to consider what will actually be  
compiled against them (the reverse deptree) - ie, the library might  
compile, but how do we know applications will compile/run against it?

Well in that case, we have to test them... and if we've tested them  
(assuming they pass, or are modified to pass), then we can keyword them.

I'm only suggesting that it makes more sense to test/keyword  
libraries with applications, rather than on their own.

Mike Z. [shootingstar]



-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Re: Documentation Update

[Grobian]

On Fri, August 26, 2005 08:04, Mike Z. wrote:
> That wasn't exactly my point, my point was that we should hold off
> keywording libraries until they will actually be used by an
> application that is keyworded, and hence properly tested.

eh, yes

> With libraries it's important to consider what will actually be
> compiled against them (the reverse deptree) - ie, the library might
> compile, but how do we know applications will compile/run against it?

eh, yes, currently we require at least one application to compile/run
against the library (we call it 'testing' I think)

> Well in that case, we have to test them... and if we've tested them
> (assuming they pass, or are modified to pass), then we can keyword them.

which is what we do

> I'm only suggesting that it makes more sense to test/keyword
> libraries with applications, rather than on their own.

We (at least I) don't keyword a library that has no application which uses
the library, to be sure there is at least one program that was happy when
using the library.  It's impossible to do an exhaustive test of all
applications using the library.  That's where my testing proposal was for.

I get your concerns, but I don't think they are valid, as I think we deal
with libraries as you propose.  That's why keywording libraries suck, you
need to do at least two things: 1) getting the library to compile/install
and 2) finding/testing with an application that uses the library (which
may not be that obvious like pcre).

I think that whenever we keyword a library, it usually is part of a larger
tree of packages depending upon each other.  Since the dependencies should
be keyworded before the depending package (portage policy), and we don't
want the dependency around before the package that depends on it
(testing), we end up in an 'atomic' commit where both library and
application are keyworded at once.

-- 
gentoo-osx@gentoo.org mailing list

Re: [gentoo-osx] Re: Documentation Update

[Grobian]

any news/update on this?  I believe the changes never made CVS, which is 
a pity.


Hasan Khalil wrote:
> 
> On Aug 21, 2005, at 07:11, Grobian wrote:
> 
>> I would propose to require the latest and greatest for both supported 
>> platforms
> 
> Done. Thanks for pointing this out.
> 
> -- 
> 
> Hasan Khalil
> eBuild and Porting Co-Lead
> Gentoo for Mac OS X
> 

-- 
Fabian Groffen
Gentoo for Mac OS X Project -- Interim Lead
-- 
gentoo-osx@gentoo.org mailing list