[gentoo-doc] Re: Toolchain guide?

[Marc Blumentritt]

Mike Frysinger schrieb:
> On Friday 28 July 2006 04:30, Marc Blumentritt wrote:
 >> I suspected this, but you confirmed it
>> and for me this is one more reason for a guide to the toolchain! Perhaps
>> it should be part of the Gentoo Handbook, since this is already arch
>> specific?
>
> i dont really understand what it is you're trying to document or what you
> think you're trying to document

I suggest to document the toolchain in two steps:
1.) Some general information about the toolchain. I switched to Gentoo,
because just from using it I learn a lot about Linux. The fisrt section
should be for learning. Before Gentoo I never heard about the toolchain,
because I just downloaded binaries and used them. Now I download the
source and build them, so I would like to now more about this process,
because I want to learn. I know a little bit about programming (mostly
scripting), but the first time I used a compiler was during my studies
on a windows machine, not really knowing, what this thing is doing (was
during my study). So this is not really a Gentoo topic, but Gentoo
provides very good docs and I hope to get the toolchain explained in one
of these wonderful Gentoo docs.

2.) After general information I put the Gentoo related stuff... (of
course, for learning, too, but in a more Gentooish way.)

>
>> 0) Introduction
>> Binaries vs. scripts? Why binaries?
>
> this question is answered in other Gentoo documents ... normally referred to
> as "why from source" or "source vs binaries"
I wanted to say here: A script is a list of commands, which can be
executed in some kind of runtime environment (like bash or python).
Syntax errors are found during runtime. Binaries are checked during
compilation, which translates lists of commands in computer language, so
that the computer can execute them much faster...

something like this. I did not want to compare source vs binary, yet.
>
>> What are libs and what is dynamic
>> linking vs. static linking (this is important for rebuilding your
>> system)?
>
> static vs dynamic libs is not related to Gentoo at all ... all operating
> systems deal with this question

I added this point, because of this scenario: I build a package foo,
which depends on lib bar dynamically. I rebuild foo with a newer version
of gcc but I do not rebuild lib bar. Does this break linkage? What with
a static build lib? Just wanted to point out a source of problems, which
I want to learn more about. You are of course right, that this is agian
general stuff.
>
>> Why is Gentoo source based? Why is this so cool compared to
>> binary based?
>
> same questions as what you posted first in this section
This is the part, where I wanted to compare source vs binary and you are
right, that this is already addressed in other docs, but since this is
closly connected to the toolchain, I thought to add it here. If it is
already written, than it is just copy/paste or a link to a doc.
>
>> 1) What is the toolchain aka how to build binaries?
>> <snip>
>> Put these programs in the correct order for the build process. If you
>> <snip>
>
> again, not Gentoo specific ... but might be useful i think

Yes, again learning part 1. And more important, which programs are
included in the toolchain? This is the heart of a source based distro
(in case of Gentoo Portage is the brain ;) ).

>
>> Helper programs
>> Why are they needed
>
> a better question: *what* helper programs ?

gcc depends on some programs (e.g. sed). This is what I termed helper
program. Which programs are required by the toolchain and why?

>
>> Arch-Specific
>> Why is the toolchain different from arch to arch?
>
> i dont understand this at all ... of course the toolchain will be different as
> no cpu is the same so generating code for a powerpc cpu will not work on an
> amd64
>
>> List of arch specific programs
>
> there are none
OK, so the toolchain packages (sources) of all arches are the same, but
of course the binaries are not.
>
>> 2) How does Gentoo handle the Toolchain?
>> Short discription of portage (ebuild (the script), emerge, ebuilds (the
>> build instructions), eclasses, USE-flags, ...). Perhaps something about
>> the new alternatives to emerge (or was it portage)?
>
> a high level view might be useful, but getting into the ebuild guts would not
> cater to the general user at all ... plus we toolchain guys like to rewrite
> things all the time and updating the docs for people outside of the toolchain
> herd would be a waste of our time ... if someone felt like just doing that
> though, that would be useful

Yes, I wanted a high level view here and not a replacement for the dev
handbook. Just telling the people: "Good news everybody! While handling
the toolchain on your own is quite complex, we give you this tool called
emerge, which is doing everything for you. It uses [...] And you can
configure all builds with these neat USE-flags!" This is of course
written about, but this is now the toolchain guide, so you have to write
about this.

There are also some USE-flags like "nptl", which are perhaps more
special than "gnome". They could be addressed here (or perhaps they
should be addressed in the knowledge base?).

>
>> What about compilation options (CHOST, CFLAGS and CXXFLAGS)? What to do,
>> if you want to change these? Not a complete list of options (that's
>> gnu.org for), but the general way, how Gentoo handles these, sane
>> compilation options. What to do, if you change these and why could this
>> be critical for your system? How to rebuild your system (twice? world?)?
>
> i think we already have a section touching on these topics

Um, yes, but the handbook just says "edit these and be carefull", while
the x86 Quick Install guide says "edit these, be carefull, and rebuild
your system twice to get full merrit (even if small) from these
changes". I'm looking for something final.

>
>> 3) How does Portage handle updates of Toolchain packages?
>
> people shouldnt care ... it should always "just work"

Yes, should, but I broke my system switching from gcc3.3 to gcc3.4. Of
course there is the gcc upgrade guide, which I should have read, but I
did not realize at that time, how problematic a toolchain upgrade can
be. Does this only concern gcc? Are there other packages, which could
break your system with major updates? I'm a little bit touchy (me cry
baby ;) ) since this and beside the wish to learn more about the
toolchain this topic is my most important reason for asking for a
toolchain guide: how to address correctly toolchain updates? Should I
rebuild the system? If yes, why and how (twice, ...?)? If no, why not?
Gain vs loss?

Regards
Marc
-- 
gentoo-doc@g.o mailing list