[gentoo-dev] Unofficial Development Guide

[gentoo-dev] Unofficial Development Guide

[Ciaran McCreesh]

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

... also known in its former lives as the "Bash Guide" and "The Doc".

Ok, I think I've held off announcing this for long enough now. It's not
complete, and there's a lot of stuff I'd like to rewrite, but I've been
persuaded to announce this anyway on the grounds that some people find
it useful and would like to be able to refer to it, even in its
unfinished state. Apparently I'm supposed to "release early, release
often".

What this is:

An attempt to document existing Gentoo development practice. The focus
is upon 'main tree' things, since that's what I know. The target
audience is existing developers and potential recruits -- an existing
knowledge of Gentoo from the user perspective is assumed.

What this is not:

This is not a list of hard rules like, say, the Debian Policy Manual. I
personally don't think that that style of hard policy would work for
Gentoo. There are exceptions to most rules -- I'm hoping that by
explaining the reason behind these rules, rather than just stating "thou
shalt not", the reader can get a better idea of when to break the rules
and how to do so safely.

This is not an official Gentoo thing. It may not mirror Gentoo Policy or
the official party line. In some places this is intentional, in others
it's a mistake.

How it is presented:

I'm aiming for a practical approach as far as possible. I've also tried
to keep individual sections reasonably separate but with relevant
references to other sections. I've tried to use realistic (even real
where possible) examples. However, there aren't many nice simple ebuilds
in the tree that don't have at least one weird part that would take a
lot of irrelevant explanation, so sometimes I've used cut down or made
up examples.

What still needs doing:

Lots. You *will* come across TODO sections, things that aren't well
explained, things that need rewriting, things that aren't properly
formatted and things that are incorrect. Most sections are about half as
big as they need to be to cover everything properly. If you don't like
that kind of thing, don't read this.

How to contribute:

For now, the best way to contribute is to send me text. If you know RST,
diffs against the source (link in the page footers) are good. Otherwise,
plain text is fine too. I do reserve the right to modify any
submissions, but I will of course discuss them with you first if it's
anything other than small formatting or wording changes. I might also
tell you to go away, but that's fairly unlikely and hasn't happened so
far.

If you're working on a section or thinking about working on a section,
it's probably a good idea to give me a prod first just in case anyone
else had the same idea. Sections that already have tentative authors
have been marked.

Don't ask for the Makefile. Trust me, it's scary, unreliable and you
don't want to see it. If I get it to the point where it'll parallel
build and work with <bash-3 and <vim-7, I'll post it somewhere.

Who to thank:

I'd like to thank g2boojum, ka0ttic, rac and slarti for big chunks of
content, and agriffis, seemant, azarah, superlag, dmwaters, swift,
weeve, jstubbs, ferringb and genone for miscellaneous help along the way
(even if some of them didn't realise what they were doing at the time).
Also thanks to the various people who have read over parts of it and
found some of the many typos and screwups. I've probably forgotten
several people -- sorry guys, I'm getting forgetful in my old age. Also
thanks to all those people whose ebuilds I nicked.

Who not to thank:

Uh, you all already know that.

Where it is:

Obviously, this isn't on Gentoo hardware. For now, it's at the link
below. I think the box it's on can cope with serving up static HTML
content and a few images (yes, we have images! four of them!), but if
not I'll blag some free webspace off someone (probably Berlios) and post
an updated URL.

    http://www.firedrop.org.uk/devmanual/

Sorry, there's no single page version yet. It's something that I could
do easily enough with the backend I'm using, but I'm more interested in
content for now.

Anyway, if you don't like it, feel free to ignore it. Or better yet,
post whiny Elmo bitchfest emails about it -- if they're good, I'll print
them out and hang them on my wall.


-- 
Ciaran McCreesh : Gentoo Developer (Vim, Fluxbox, shell tools)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Unofficial Development Guide

[Donnie Berkholz]

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

Ciaran McCreesh wrote:
>     http://www.firedrop.org.uk/devmanual/

Before I read the whole thing, were you able to take anything from the
existing handbook or need to rewrite everything from scratch?

Thanks,
Donnie
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFCdYJ1XVaO67S1rtsRAvqPAJ0b9ErRaOXegnkbxcfmvr/Z5WxwhwCgpI8Z
tFUNUR/Z3Xb+ZU3s6k85WMw=
=8R+M
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Unofficial Development Guide

[Daniel Goller]

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

Ciaran McCreesh wrote:
| ... also known in its former lives as the "Bash Guide" and "The Doc".
|
| Ok, I think I've held off announcing this for long enough now. It's not
| complete, and there's a lot of stuff I'd like to rewrite, but I've been
| persuaded to announce this anyway on the grounds that some people find
| it useful and would like to be able to refer to it, even in its
| unfinished state. Apparently I'm supposed to "release early, release
| often".
|
| What this is:
|
| An attempt to document existing Gentoo development practice. The focus
| is upon 'main tree' things, since that's what I know. The target
| audience is existing developers and potential recruits -- an existing
| knowledge of Gentoo from the user perspective is assumed.
|
| What this is not:
|
| This is not a list of hard rules like, say, the Debian Policy Manual. I
| personally don't think that that style of hard policy would work for
| Gentoo. There are exceptions to most rules -- I'm hoping that by
| explaining the reason behind these rules, rather than just stating "thou
| shalt not", the reader can get a better idea of when to break the rules
| and how to do so safely.
|
| This is not an official Gentoo thing. It may not mirror Gentoo Policy or
| the official party line. In some places this is intentional, in others
| it's a mistake.
|
| How it is presented:
|
| I'm aiming for a practical approach as far as possible. I've also tried
| to keep individual sections reasonably separate but with relevant
| references to other sections. I've tried to use realistic (even real
| where possible) examples. However, there aren't many nice simple ebuilds
| in the tree that don't have at least one weird part that would take a
| lot of irrelevant explanation, so sometimes I've used cut down or made
| up examples.
|
| What still needs doing:
|
| Lots. You *will* come across TODO sections, things that aren't well
| explained, things that need rewriting, things that aren't properly
| formatted and things that are incorrect. Most sections are about half as
| big as they need to be to cover everything properly. If you don't like
| that kind of thing, don't read this.
|
| How to contribute:
|
| For now, the best way to contribute is to send me text. If you know RST,
| diffs against the source (link in the page footers) are good. Otherwise,
| plain text is fine too. I do reserve the right to modify any
| submissions, but I will of course discuss them with you first if it's
| anything other than small formatting or wording changes. I might also
| tell you to go away, but that's fairly unlikely and hasn't happened so
| far.
|
| If you're working on a section or thinking about working on a section,
| it's probably a good idea to give me a prod first just in case anyone
| else had the same idea. Sections that already have tentative authors
| have been marked.
|
| Don't ask for the Makefile. Trust me, it's scary, unreliable and you
| don't want to see it. If I get it to the point where it'll parallel
| build and work with <bash-3 and <vim-7, I'll post it somewhere.
|
| Who to thank:
|
| I'd like to thank g2boojum, ka0ttic, rac and slarti for big chunks of
| content, and agriffis, seemant, azarah, superlag, dmwaters, swift,
| weeve, jstubbs, ferringb and genone for miscellaneous help along the way
| (even if some of them didn't realise what they were doing at the time).
| Also thanks to the various people who have read over parts of it and
| found some of the many typos and screwups. I've probably forgotten
| several people -- sorry guys, I'm getting forgetful in my old age. Also
| thanks to all those people whose ebuilds I nicked.
|
| Who not to thank:
|
| Uh, you all already know that.
|
| Where it is:
|
| Obviously, this isn't on Gentoo hardware. For now, it's at the link
| below. I think the box it's on can cope with serving up static HTML
| content and a few images (yes, we have images! four of them!), but if
| not I'll blag some free webspace off someone (probably Berlios) and post
| an updated URL.
|
|     http://www.firedrop.org.uk/devmanual/
|
| Sorry, there's no single page version yet. It's something that I could
| do easily enough with the backend I'm using, but I'm more interested in
| content for now.
|
| Anyway, if you don't like it, feel free to ignore it. Or better yet,
| post whiny Elmo bitchfest emails about it -- if they're good, I'll print
| them out and hang them on my wall.
|
|
Thanks
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFCdYQxUpKYMelfdYERAjk1AJ9OVwP8spjKyHO6v8jrROKu4Y/H4wCeK3N0
yP6dg1xrgO8MgFG+hWRRxhc=
=LrjB
-----END PGP SIGNATURE-----
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Unofficial Development Guide

[Ciaran McCreesh]

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

On Sun, 01 May 2005 18:29:25 -0700 Donnie Berkholz
<spyderous@gentoo.org> wrote:
| Ciaran McCreesh wrote:
| >     http://www.firedrop.org.uk/devmanual/
| 
| Before I read the whole thing, were you able to take anything from the
| existing handbook or need to rewrite everything from scratch?

Most of it is from scratch. There're bits that resemble parts of the old
docs (mostly stuff that I wrote for those too) but not much. Easier to
rewrite than to adapt...

-- 
Ciaran McCreesh : Gentoo Developer (Vim, Fluxbox, shell tools)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]

Re: [gentoo-dev] Unofficial Development Guide

[Luca Barbato]

Ciaran McCreesh wrote:
> ... also known in its former lives as the "Bash Guide" and "The Doc".

I read few pages and I think quite are nice, good job.

lu

-- 

Luca Barbato

Gentoo/linux Developer		Gentoo/PPC Operational Manager
http://dev.gentoo.org/~lu_zero

-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Unofficial Development Guide

[Francesco Riosa]

there is a small typo in
http://www.firedrop.org.uk/devmanual/eclass-writing/

[ Export Functions ]
... say we had fnord.eclass

ECLASS="fnord"
INHERITED="$INHERITED $ECLASS"
EXPORT_FUNCTIONS src_compile

foo_src_compile() {
    do_stuff || die
}

Then an ebuild could do this:

inherit foo.eclass

src_compile() {
    do_pre_stuff || die
    foo_src_compile
    do_post_stuff || die
}


the eclass should be called "foo" everywhere
-- 
gentoo-dev@gentoo.org mailing list

Re: [gentoo-dev] Unofficial Development Guide

[Ciaran McCreesh]

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

On Wed, 11 May 2005 22:12:08 +0200 Francesco Riosa
<francesco@pnpitalia.it> wrote:
| there is a small typo in
| http://www.firedrop.org.uk/devmanual/eclass-writing/

Oops, too many metasyntactic variables... One mistake down, hundreds
more to go :)

Cheers,
-- 
Ciaran McCreesh : Gentoo Developer (Vim, Shell tools, Fluxbox, Cron)
Mail            : ciaranm at gentoo.org
Web             : http://dev.gentoo.org/~ciaranm


[-- Attachment #2: Type: application/pgp-signature, Size: 189 bytes --]