some preliminary questions about bitbake manual

some preliminary questions about bitbake manual

[Robert P. J. Day]

  i'm about to write some tutorials on OE/bitbake/poky/yocto (from a
position of moderate ignorance, hoping that will change), so a couple
questions/observations before i get started.

  at risk of repetition, i already noted that if you google on
"bitbake user manual", you end up here:

  http://bitbake.berlios.de/manual/

which is *way* out of date, so perhaps a link to something newer would
be useful.

  next, is it fair to say that the current version of the bitbake
manual is the one that's part of bitbake itself, in the doc/
directory?  so if i want to submit some patches, i'd post them to this
list and those patches would always be relative to my current "git
pull" of bitbake?

  finally (for now), over at yocto, here's a quick tutorial on getting
started with oe-core:

  https://wiki.yoctoproject.org/wiki/OpenEmbedded-Core

it all looks reasonable but what you end up with in the oe-core
directory is two "bitbake.conf" files:

$ find . -name bitbake.conf
./meta/conf/bitbake.conf
./bitbake/conf/bitbake.conf
$

  i'm assuming that's by design and there are no weird conflicts
between the two files, right?

  more soon.  real soon.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: some preliminary questions about bitbake manual

[Paul Eggleton]

On Monday 19 March 2012 07:49:59 Robert P. J. Day wrote:
>   i'm about to write some tutorials on OE/bitbake/poky/yocto (from a
> position of moderate ignorance, hoping that will change), so a couple
> questions/observations before i get started.
> 
>   at risk of repetition, i already noted that if you google on
> "bitbake user manual", you end up here:
> 
>   http://bitbake.berlios.de/manual/
> 
> which is *way* out of date, so perhaps a link to something newer would
> be useful.

Yes, we acknowledge it is quite out of date. The problem with the BitBake 
manual is it must cover only BitBake generically, and not OE. Of course 
there's a lot that could be added to it, but having complete documentation 
there is less important than documenting OE. That's not to say we won't 
welcome patches though ;)

>   next, is it fair to say that the current version of the bitbake
> manual is the one that's part of bitbake itself, in the doc/
> directory?  so if i want to submit some patches, i'd post them to this
> list and those patches would always be relative to my current "git
> pull" of bitbake?

Yes, that's correct.
 
>   finally (for now), over at yocto, here's a quick tutorial on getting
> started with oe-core:
> 
>   https://wiki.yoctoproject.org/wiki/OpenEmbedded-Core
> 
> it all looks reasonable but what you end up with in the oe-core
> directory is two "bitbake.conf" files:
> 
> $ find . -name bitbake.conf
> ./meta/conf/bitbake.conf
> ./bitbake/conf/bitbake.conf
> $
> 
>   i'm assuming that's by design and there are no weird conflicts
> between the two files, right?

Sort of - the last one is actually an example config and since it never ends up 
in BBPATH it will never be used. Now that you mention it, Richard mentioned to 
me recently that it should probably be renamed to bitbake.conf.sample to avoid 
confusion.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: some preliminary questions about bitbake manual

[Robert P. J. Day]

On Mon, 19 Mar 2012, Paul Eggleton wrote:

> On Monday 19 March 2012 07:49:59 Robert P. J. Day wrote:
> >   i'm about to write some tutorials on OE/bitbake/poky/yocto (from a
> > position of moderate ignorance, hoping that will change), so a couple
> > questions/observations before i get started.
> >
> >   at risk of repetition, i already noted that if you google on
> > "bitbake user manual", you end up here:
> >
> >   http://bitbake.berlios.de/manual/
> >
> > which is *way* out of date, so perhaps a link to something newer would
> > be useful.
>
> Yes, we acknowledge it is quite out of date. The problem with the
> BitBake manual is it must cover only BitBake generically, and not
> OE. Of course there's a lot that could be added to it, but having
> complete documentation there is less important than documenting OE.
> That's not to say we won't welcome patches though ;)

  yes, i can see the problem.  but rather than try to be a purist, why
not just accept that the best way to document bitbake is to do it
within the context of oe-core?  that's the approach i'm going to take
with what i'm writing.

> >   finally (for now), over at yocto, here's a quick tutorial on getting
> > started with oe-core:
> >
> >   https://wiki.yoctoproject.org/wiki/OpenEmbedded-Core
> >
> > it all looks reasonable but what you end up with in the oe-core
> > directory is two "bitbake.conf" files:
> >
> > $ find . -name bitbake.conf
> > ./meta/conf/bitbake.conf
> > ./bitbake/conf/bitbake.conf
> > $
> >
> >   i'm assuming that's by design and there are no weird conflicts
> > between the two files, right?
>
> Sort of - the last one is actually an example config and since it
> never ends up in BBPATH it will never be used. Now that you mention
> it, Richard mentioned to me recently that it should probably be
> renamed to bitbake.conf.sample to avoid confusion.

  ah, i should have noticed that.  yes, it would be helpful if it were
renamed to ".sample" to make that more obvious.  what would also be
useful is to point out that the "OVERRIDES =" directive doesn't occur
all that frequently.

  personally, when i'm reading docs, i like to have the source tree at
hand so i can search for examples of whatever i'm reading about, and
what i notice is that "OVERRIDES =" appears only in a .conf file.  a
reader might want to know that sort of thing to know that he/she needs
to examine only a single .conf file to see all of the current
OVERRIDES settings.

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================

Re: some preliminary questions about bitbake manual

[Paul Eggleton]

On Monday 19 March 2012 08:15:32 Robert P. J. Day wrote:
> > Yes, we acknowledge it is quite out of date. The problem with the
> > BitBake manual is it must cover only BitBake generically, and not
> > OE. Of course there's a lot that could be added to it, but having
> > complete documentation there is less important than documenting OE.
> > That's not to say we won't welcome patches though ;)
> 
>   yes, i can see the problem.  but rather than try to be a purist

The thing is, BitBake was originally separated out of OE years ago so that it 
could be kept as a fairly pure task executor. If the code is to remain that 
way then the documentation should continue to reflect that.

> why not just accept that the best way to document bitbake is to do it
> within the context of oe-core?  that's the approach i'm going to take
> with what i'm writing.

Why not just document OE then (which will include documenting those aspects of 
BitBake that are important in OE in the appropriate context)?

> what would also be useful is to point out that the "OVERRIDES =" directive
> doesn't occur all that frequently.

Perhaps. It's a key advantage of how BitBake works though. Again, if you're 
starting from the point of view of BitBake being a generic tool you need to 
know about OVERRIDES. In fact you should probably have a basic understanding 
of how OVERRIDES works within OE, even though you will almost never need to 
set or refer to it directly.

>   personally, when i'm reading docs, i like to have the source tree at
> hand so i can search for examples of whatever i'm reading about, and
> what i notice is that "OVERRIDES =" appears only in a .conf file.  a
> reader might want to know that sort of thing to know that he/she needs
> to examine only a single .conf file to see all of the current
> OVERRIDES settings.

From BitBake's perspective, OVERRIDES can have anything in it - it's just a 
list of switches. The power comes when you put the value of some other 
significant variable into it (e.g. MACHINE, in the context of OE) and then make 
use of values of that variable in overrides elsewhere.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: some preliminary questions about bitbake manual

[Robert P. J. Day]

On Mon, 19 Mar 2012, Paul Eggleton wrote:

> On Monday 19 March 2012 08:15:32 Robert P. J. Day wrote:
> > > Yes, we acknowledge it is quite out of date. The problem with
> > > the BitBake manual is it must cover only BitBake generically,
> > > and not OE. Of course there's a lot that could be added to it,
> > > but having complete documentation there is less important than
> > > documenting OE. That's not to say we won't welcome patches
> > > though ;)
> >
> >   yes, i can see the problem.  but rather than try to be a purist
>
> The thing is, BitBake was originally separated out of OE years ago
> so that it could be kept as a fairly pure task executor. If the code
> is to remain that way then the documentation should continue to
> reflect that.

  fair enough ... i'll ponder on how i want to do this.  since i'm
writing my own tutorial, i don't need to try to restructure the
current bitbake manual -- i'll just send in patches that really
reflect fixes to the bitbake manual.

> > why not just accept that the best way to document bitbake is to do
> > it within the context of oe-core?  that's the approach i'm going
> > to take with what i'm writing.
>
> Why not just document OE then (which will include documenting those
> aspects of BitBake that are important in OE in the appropriate
> context)?

  i'm pretty sure that's the approach i'm going to use, since it's so
much easier to explain things by using examples pulled straight out of
oe-core.  i'm already designing a newbie's guide to oe-core which will
mix bitbake explanations in there.

  anyway, back to proofreading ...

rday

-- 

========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================