getting started - docbook

getting started - docbook

[David Farning]

I have been going through the getting started wiki and noticed that a
few points are out of date or wrong.

Would you it be useful if I cleaned up the wiki and converted it to
docbook for inclusion in the manual?  The gettingstarted link on
oe.org could then refer to the cannonical gettingstarted instructions
in the manual.

Thanks
David Farning

Re: getting started - docbook

[Koen Kooi]

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

David Farning schreef:
> I have been going through the getting started wiki and noticed that a
> few points are out of date or wrong.
> 
> Would you it be useful if I cleaned up the wiki and converted it to
> docbook for inclusion in the manual? 


Yes! yes! YES!!!!
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iD8DBQFHHE3ZMkyGM64RGpERAqv/AJ0QiyLNVxnQpi4IBxC1nN8rHiHnlACghtjT
A054lwe097v7b6P0+MIY15U=
=xCIE
-----END PGP SIGNATURE-----

Re: getting started - docbook

[Koen Kooi]

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

Koen Kooi schreef:
> David Farning schreef:
>> I have been going through the getting started wiki and noticed that a
>> few points are out of date or wrong.
>
>> Would you it be useful if I cleaned up the wiki and converted it to
>> docbook for inclusion in the manual?
>
>
> Yes! yes! YES!!!!

That means "great idea, please do that", in case someone was wondering :)
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iD8DBQFHHGDLMkyGM64RGpERAkkYAJ98NkXj0pRtIYM2Tmqrj7j1zt15IwCfVK1z
/ZqZv/GV4J1i4MoahWAXLm4=
=j6Dz
-----END PGP SIGNATURE-----

Re: getting started - docbook

[David Farning]

On Mon, Oct 22, 2007 at 09:14:33AM +0200, Koen Kooi wrote:
> > Would you it be useful if I cleaned up the wiki and converted it to
> > docbook for inclusion in the manual? 
> 
> Yes! yes! YES!!!!

Ok, I'll start putting a drop in replacement for the existing getting
started chapter based on my _limited_ experience, the gettingstarted
wiki, and questions frequent questions in the users ML.

Time permitting, I will submit a draft on Monday.  Bob, thanks for the
offer to proof read and test.

I am thinking about going through 4 basic steps
1. install
2. configure
3. build
4. test

I would like to use a concrete example that a user can build and
test on qemu.  Do you have a recommendation for a good machine-distro
combination that builds well and can show a potential user the capabilities of OE?

Thanks
David Farning

Re: getting started - docbook

[Koen Kooi]

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

David Farning schreef:
> On Mon, Oct 22, 2007 at 09:14:33AM +0200, Koen Kooi wrote:
>>> Would you it be useful if I cleaned up the wiki and converted it to
>>> docbook for inclusion in the manual? 
>> Yes! yes! YES!!!!
> 
> Ok, I'll start putting a drop in replacement for the existing getting
> started chapter based on my _limited_ experience, the gettingstarted
> wiki, and questions frequent questions in the users ML.
> 
> Time permitting, I will submit a draft on Monday.  Bob, thanks for the
> offer to proof read and test.
> 
> I am thinking about going through 4 basic steps
> 1. install
> 2. configure
> 3. build
> 4. test
> 
> I would like to use a concrete example that a user can build and
> test on qemu.  Do you have a recommendation for a good machine-distro
> combination that builds well and can show a potential user the capabilities of OE?

the qemuarm, qemux86, spitz and fic-gta01 machines have complete
hardware support in (patched) versions of qemu. DISTRO=angstrom-2007.1
would be the best choice for a distro.

regards,

Koen

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iD8DBQFHHZxUMkyGM64RGpERAg+2AJ9bjviltAefV0KEWACE+lLMNH/lwwCePcTP
jU+fXOkDHM7NtC5/BJyvY0k=
=9tJL
-----END PGP SIGNATURE-----

getting started - docbook

[Filippo Basso]

    I have been going through the getting started wiki and noticed that a

    few points are out of date or wrong.

    Would you it be useful if I cleaned up the wiki and converted it to
    docbook for inclusion in the manual?  The gettingstarted link on
    oe.org could then refer to the cannonical gettingstarted instructions
    in the manual.

    Thanks
    David Farning


I'm writing few notes on a doc just for me, called "OE Journey",
explaining what are basic steps in OE, basic tasks, dependencies graphs,
few examples... now it's just 10 pages, can it be useful? Should I
continue in this ooffice doc or can be more useful to others if I change
format (eg. wiki)???

thank you,
    phy

P.S. also writing a simple .dot-graphviz files manipulator to produce
nice graph dependencies with base packages collapsed... (was trying
patching bitbake, but then it's much more confortable an interactive way
like I'm doing now, in php on my localhost)

Re: getting started - docbook

[David Farning]

> I'm writing few notes on a doc just for me, called "OE Journey",
> explaining what are basic steps in OE, basic tasks, dependencies graphs,
> few examples... now it's just 10 pages, can it be useful? Should I
> continue in this ooffice doc or can be more useful to others if I change
> format (eg. wiki)???
> 
> thank you,
>     phy
> 
> P.S. also writing a simple .dot-graphviz files manipulator to produce
> nice graph dependencies with base packages collapsed... (was trying
> patching bitbake, but then it's much more confortable an interactive way
> like I'm doing now, in php on my localhost)

It would be very helpful to me to see your personal journey.  The
dependancy graph stuff would be very helpful. This evening I was
manually tracing some dependancy graphs.

The biggest challange is deciding on the correct terminology.
I think that I will start creating a glossary so new users can look up
terms and experienced users can use 'approved term' consistently. (to
keep the new users from getting unnecessarily confused) A bitbake
file, a recipe, and a package all seem to be the same thing.  I didn't
realize that they were all the same thing until this afternoon.

Thanks
David Farning

Re: getting started - docbook

[Koen Kooi]

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

David Farning schreef:

> The biggest challange is deciding on the correct terminology.
> I think that I will start creating a glossary so new users can look up
> terms and experienced users can use 'approved term' consistently. (to
> keep the new users from getting unnecessarily confused) A bitbake
> file, a recipe, and a package all seem to be the same thing.  I didn't
> realize that they were all the same thing until this afternoon.

Actually they aren't the same :)

A bitbake file and a recipe are the same thing, but they produces a
package (.ipk, .deb, etc). That's why we have DEPENDS (for the recipe)
and RDEPENDS (for the package).

regards,

Koen
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iD8DBQFHIEfDMkyGM64RGpERAg+XAJ9HxHHjWGDPiW7WGriXKtc+Jkm2/QCfYcR1
0KW9zWTfAWtZucToyHJSyrk=
=TP1Q
-----END PGP SIGNATURE-----

Re: getting started - docbook

[David Farning]

On Thu, Oct 25, 2007 at 09:37:39AM +0200, Koen Kooi wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> David Farning schreef:
> Actually they aren't the same :)
> 
> A bitbake file and a recipe are the same thing, but they produces a
> package (.ipk, .deb, etc). That's why we have DEPENDS (for the recipe)
> and RDEPENDS (for the package).

At least on place in either the bitbake or oe manual, the stuff under
the dev/packages/ is referred to as packages.  

In the bitbake help, the usage is show as $bitbake [option] [package].
How can base-task of gpe-image be a package.

I know this this sounds really picky;)

But I am struggling over what to call the object of a bitebake.  (In
make they are call targets .ie make all, but in the embedded world
target is used to refer to the device for which you are building.)

$bitbake vim
$bitbake task-base
$bitbake gpe-image
$bitbake world

A package, a task, an image, and world?

thanks
David Farning

Re: getting started - docbook

[Cliff Brake]

On 10/25/07, David Farning <dfarning@gmail.com> wrote:
> On Thu, Oct 25, 2007 at 09:37:39AM +0200, Koen Kooi wrote:
> > -----BEGIN PGP SIGNED MESSAGE-----
> > Hash: SHA1
> >
> > David Farning schreef:
> > Actually they aren't the same :)
> >
> > A bitbake file and a recipe are the same thing, but they produces a
> > package (.ipk, .deb, etc). That's why we have DEPENDS (for the recipe)
> > and RDEPENDS (for the package).
>
> At least on place in either the bitbake or oe manual, the stuff under
> the dev/packages/ is referred to as packages.
>
> In the bitbake help, the usage is show as $bitbake [option] [package].
> How can base-task of gpe-image be a package.
>
> I know this this sounds really picky;)

No, we need to be consistent -- this is a good exercise.  Perhaps
<oe>/packages should really be <oe>/recipes.

> But I am struggling over what to call the object of a bitebake.  (In
> make they are call targets .ie make all, but in the embedded world
> target is used to refer to the device for which you are building.)
>
> $bitbake vim
> $bitbake task-base
> $bitbake gpe-image
> $bitbake world
> A package, a task, an image, and world?

I suppose it depends -- saying that I'm "building a packages" is
technically correct as the ipk/deb is the output.  But, "bitbaking a
recipe" is probably more correct.

perhaps recipe -- that way it is very obvious what we are talking about.

Cliff

-- 
=======================
Cliff Brake
http://bec-systems.com

Re: getting started - docbook

[David Farning]

On Thu, Oct 25, 2007 at 01:34:51PM -0400, Cliff Brake wrote:
> 
> I suppose it depends -- saying that I'm "building a packages" is
> technically correct as the ipk/deb is the output.  But, "bitbaking a
> recipe" is probably more correct.
> 
> perhaps recipe -- that way it is very obvious what we are talking about.


Nice, Bitbaking a recipe or informally, baking a recipe, is very obvious.
Once BitBake and recipe have been defined it will be clear what we are
talking about.  Also it will eliminate the [make, build, create, run,
deploy][package, package set, task, target,distro] ambiguity.

Thanks
David Farning  

Re: getting started - docbook

[Tobias Pflug]

hi,

i am jumping into this discussion a bit late as I had not much time
recently. I also recently started working with openembeded at work
as I convinced my boss that it's the best way to go for our embedded
product. 

Now i've spent some good time getting into it and understanding the
use cases / patterns behind it. I am pretty sure that I still don't
get the full picture and partially things are still a bit of a black
box to me. So I am glad to see a discussion coming up about
documentation on this list. I'd very much like to share my point
of view on it and I am also very willing and interested in helping
out with updating and extending the existing documentation. (hi david..)

So to get to the facts - I think there are basically two issues
with the documentation as of now:

(1): big picture
(2): bitbake


on 1: 
with big picture I mean there should be a description of the 
"system" with its main components. Currently i think there is too
little of that, and too many use-cases. ("In order to change xyz,
apply abc to 123").

For starters a diagram would do some good. I did one for a small
report at work which however is rather incomplete. I should polish
that a little. Depicting the interaction between bitbake, the different
config file sets, internet resources, distributions and images. I think
all of this should be presented before even starting to elaborate on
how to build something


on 2:
To me the biggest black box is still bitbake. The documentation
seems somewhat lacking and I have a bad feeling about carrying out tasks
where I don't quite understand what's going on. 

I still don't quite get how the dependency checking works and when
changes to specific files will trigger an automatic rebuild and when
I'll have to trigger that myself with a -crebuild / or maybe even 
by fiddling with timestamps? Although my guts tell me that the latter
is a NO-NO.

David, I gather you are still working on the setup section? Maybe I
could try contributing a "big picture" description, however my
text will certainly require a lot of refinement from those with
more background knowledge. 

David, will you also write on how to set up an OEDEV directory sturcure/
sharing of working directories etc? Personally I am using the structure
that cliff presented on the ml (I think) at some point which I find
comfortable.

best regards and a nice weekend,
Tobi

PS: A little off-topic sidenote to any potential compulab board owners..
do not fiddle around with GPIO commands in armmon. My devboard is
unusable right now and resetting via jumpers does not help ;/

Re: getting started - docbook

[David Farning]

On Sat, Oct 27, 2007 at 01:06:59PM +0200, Tobias Pflug wrote:
> on 1: 
> with big picture I mean there should be a description of the 
> "system" with its main components. Currently i think there is too
> little of that, and too many use-cases. ("In order to change xyz,
> apply abc to 123").

I finished a rough draft of getting started this morning.  I am going
to let it sit for a week before looking at it again.  Then I will
rework as needed and submitte for review.

In the mean time I am starting on a introduction chapter.  This will
be a very high level overview.  Below is a first stab at the outline.

1.1. Linux ................................................
      1.1.1. Linux Overview ...................
      1.1.2. Linux Arctoture ...................
      1.1.3. Linux Development Model..
      1.1.4. Linux Open Source..............
1.2. Embedded Device ............................
      1.2.1. Device Architure..................
      1.2.2. Processor..............................
      1.2.3. Storage.................................
      1.2.4. Device..................................
1.3. Linux Distribution............................
      1.3.1. Kernel ..................................
      1.3.2. Userspace.............................
      1.3.3. File System ..........................
      1.3.4. Updating ..............................
1.4. System startup ..................................
      ...
1.5. Host/Target .......................................
      ...
1.6. Overview ..........................................
1.7. History..............................................

> For starters a diagram would do some good. I did one for a small
> report at work which however is rather incomplete. I should polish
> that a little. Depicting the interaction between bitbake, the different
> config file sets, internet resources, distributions and images. I think
> all of this should be presented before even starting to elaborate on
> how to build something

Diagrams may take awhile;(  I never seem to have the time to learn how
to make them.
 
> on 2:
> To me the biggest black box is still bitbake. The documentation
> seems somewhat lacking and I have a bad feeling about carrying out tasks
> where I don't quite understand what's going on. 
> 
> I still don't quite get how the dependency checking works and when
> changes to specific files will trigger an automatic rebuild and when
> I'll have to trigger that myself with a -crebuild / or maybe even 
> by fiddling with timestamps? Although my guts tell me that the latter
> is a NO-NO.

I have been avoiding these types of details until later sections. 

 
> David, I gather you are still working on the setup section? Maybe I
> could try contributing a "big picture" description, however my
> text will certainly require a lot of refinement from those with
> more background knowledge. 

At this point, what would be most helpful is looking at and tearing
apart the suggestions and drafts I submit;)  Between the introduction
and the getting started we should be able to provide a good big
picture.  Additionally, we can define terms which can be used
consistently through the rest of the documentation.


> David, will you also write on how to set up an OEDEV directory sturcure/
> sharing of working directories etc? Personally I am using the structure
> that cliff presented on the ml (I think) at some point which I find
> comfortable.

Again this will wait to a later chapter.  I think we will have a better
idea of the full outline after the introduction chapter is more filled
in.

Thanks
David Farning

Re: getting started - docbook

[Koen Kooi]

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

David Farning schreef:
> On Sat, Oct 27, 2007 at 01:06:59PM +0200, Tobias Pflug wrote:
>> on 1: 
>> with big picture I mean there should be a description of the 
>> "system" with its main components. Currently i think there is too
>> little of that, and too many use-cases. ("In order to change xyz,
>> apply abc to 123").
> 
> I finished a rough draft of getting started this morning.  I am going
> to let it sit for a week before looking at it again.  Then I will
> rework as needed and submitte for review.
> 
> In the mean time I am starting on a introduction chapter.  This will
> be a very high level overview.  Below is a first stab at the outline.

Even if 99.9% if the people use OE to build linux stuff, it is able to
build nonlinux targets like bare-metal stuff for the msp430
microcontroller and things like arm-wince-pe or arm-apple-darwin.

> 1.1. Linux ................................................
>       1.1.1. Linux Overview ...................
>       1.1.2. Linux Arctoture ...................

^ typo

regards,

Koen

>       1.1.3. Linux Development Model..
>       1.1.4. Linux Open Source..............
> 1.2. Embedded Device ............................
>       1.2.1. Device Architure..................
>       1.2.2. Processor..............................
>       1.2.3. Storage.................................
>       1.2.4. Device..................................
> 1.3. Linux Distribution............................
>       1.3.1. Kernel ..................................
>       1.3.2. Userspace.............................
>       1.3.3. File System ..........................
>       1.3.4. Updating ..............................
> 1.4. System startup ..................................
>       ...
> 1.5. Host/Target .......................................
>       ...
> 1.6. Overview ..........................................
> 1.7. History..............................................
> 
>> For starters a diagram would do some good. I did one for a small
>> report at work which however is rather incomplete. I should polish
>> that a little. Depicting the interaction between bitbake, the different
>> config file sets, internet resources, distributions and images. I think
>> all of this should be presented before even starting to elaborate on
>> how to build something
> 
> Diagrams may take awhile;(  I never seem to have the time to learn how
> to make them.
>  
>> on 2:
>> To me the biggest black box is still bitbake. The documentation
>> seems somewhat lacking and I have a bad feeling about carrying out tasks
>> where I don't quite understand what's going on. 
>>
>> I still don't quite get how the dependency checking works and when
>> changes to specific files will trigger an automatic rebuild and when
>> I'll have to trigger that myself with a -crebuild / or maybe even 
>> by fiddling with timestamps? Although my guts tell me that the latter
>> is a NO-NO.
> 
> I have been avoiding these types of details until later sections. 
> 
>  
>> David, I gather you are still working on the setup section? Maybe I
>> could try contributing a "big picture" description, however my
>> text will certainly require a lot of refinement from those with
>> more background knowledge. 
> 
> At this point, what would be most helpful is looking at and tearing
> apart the suggestions and drafts I submit;)  Between the introduction
> and the getting started we should be able to provide a good big
> picture.  Additionally, we can define terms which can be used
> consistently through the rest of the documentation.
> 
> 
>> David, will you also write on how to set up an OEDEV directory sturcure/
>> sharing of working directories etc? Personally I am using the structure
>> that cliff presented on the ml (I think) at some point which I find
>> comfortable.
> 
> Again this will wait to a later chapter.  I think we will have a better
> idea of the full outline after the introduction chapter is more filled
> in.
> 
> Thanks
> David Farning
> 
> _______________________________________________
> Openembedded-devel mailing list
> Openembedded-devel@lists.openembedded.org
> http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel
> 

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iD8DBQFHI3UJMkyGM64RGpERAgSpAJ9GER7+9ldWT9zP6TaIoC0zHvGsgwCeIvam
zHz0AOpfLC9DRQOAb/0WQzY=
=SeHo
-----END PGP SIGNATURE-----

Re: getting started - docbook

[David Farning]

On Sat, Oct 27, 2007 at 07:27:37PM +0200, Koen Kooi wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> David Farning schreef:
> > On Sat, Oct 27, 2007 at 01:06:59PM +0200, Tobias Pflug wrote:
> >> on 1: 
> >> with big picture I mean there should be a description of the 
> >> "system" with its main components. Currently i think there is too
> >> little of that, and too many use-cases. ("In order to change xyz,
> >> apply abc to 123").
> > 
> > I finished a rough draft of getting started this morning.  I am going
> > to let it sit for a week before looking at it again.  Then I will
> > rework as needed and submitte for review.
> > 
> > In the mean time I am starting on a introduction chapter.  This will
> > be a very high level overview.  Below is a first stab at the outline.
> 
> Even if 99.9% if the people use OE to build linux stuff, it is able to
> build nonlinux targets like bare-metal stuff for the msp430
> microcontroller and things like arm-wince-pe or arm-apple-darwin.

That makes sense.  Nothing special about the Linux kernel.  For the
purposes of documentation would you mind if we:

1 Studied the device - processer, memory, IO, devices....
2 Studied a generic Linux distribution - kernel, libs, apps, packages,
files system....
3 Discussed how to use bb/oe to create a customized distro to run on a
specific device.

Once the user understands how to create a custom linux distro the
theory can be extended to other OSs.

By looking specifically a linux first, the reader has a lot of good, concrete,
 documentation available to them.


> > 1.1. Linux ................................................
> >       1.1.1. Linux Overview ...................
> >       1.1.2. Linux Arctoture ...................
> 
> ^ typo
> 
Sorry you will find lots of typos and sentences out of order until
things start nearing a final draft stage.  I have dyslexia so my
drafts are pretty rough.  For the final draft, I have someone read
each sentence aloud so I can get it right;)

Thanks
David Farning

Re: getting started - docbook

[Tobias Pflug]

On Sat, 2007-10-27 at 16:26 -0500, David Farning wrote:
> On Sat, Oct 27, 2007 at 07:27:37PM +0200, Koen Kooi wrote:
> > -----BEGIN PGP SIGNED MESSAGE-----
> > Hash: SHA1
> > 
> > David Farning schreef:
> > > On Sat, Oct 27, 2007 at 01:06:59PM +0200, Tobias Pflug wrote:
> > >> on 1: 
> > >> with big picture I mean there should be a description of the 
> > >> "system" with its main components. Currently i think there is too
> > >> little of that, and too many use-cases. ("In order to change xyz,
> > >> apply abc to 123").
> > > 
> > > I finished a rough draft of getting started this morning.  I am going
> > > to let it sit for a week before looking at it again.  Then I will
> > > rework as needed and submitte for review.
> > > 
> > > In the mean time I am starting on a introduction chapter.  This will
> > > be a very high level overview.  Below is a first stab at the outline.
> > 
> > Even if 99.9% if the people use OE to build linux stuff, it is able to
> > build nonlinux targets like bare-metal stuff for the msp430
> > microcontroller and things like arm-wince-pe or arm-apple-darwin.
> 
> That makes sense.  Nothing special about the Linux kernel.  For the
> purposes of documentation would you mind if we:
> 
> 1 Studied the device - processer, memory, IO, devices....
> 2 Studied a generic Linux distribution - kernel, libs, apps, packages,
> files system....
> 3 Discussed how to use bb/oe to create a customized distro to run on a
> specific device.

In my humble opinion that is way out of scope for a OE documentation.
The point is to present the workings and functionalities of OpenEmbedded
and not how to get some arbitrary hardware to run linux from 0 to
100% .. ?

At least that is my conception of what the OE documentation should
provide?

regards,
Tobi

Re: getting started - docbook

[Stelios Koroneos]

> In my humble opinion that is way out of scope for a OE documentation.
> The point is to present the workings and functionalities of OpenEmbedded
> and not how to get some arbitrary hardware to run linux from 0 to
> 100% .. ?
>
> At least that is my conception of what the OE documentation should
> provide?


We discussed the documentation matter in OEDEM.
What we "concluded" to is that there can not be a single document to cover
all of OE
The idea was to see how we can get a "Getting started guide" where the basic
functionality of OE is covered and a "Programmers/Developers manual" kind of
thing where all big and little dirty details of OE should go to.

These two documents target different kind of people with different needs.
The people who would like to use OE with an existing device/distro by simply
building an image and/or want to develop/port an application (without
messing too much with the OE internals) and those who need to add a new
device/distro/extend OE in whatever manner they need

IMHO there is a need to get documentation for the larger pool of
"application developers" first and move into the detailed "board/distro
developers" at a second stage, as we are going to see more and more of the
first, as OE gets shipped with more and more devices.
And with the SDK needing some "final touches" to be functional , we are
bound to see more and more people asking questions that are "application
developer" oriented, so we better be prepared for that.



Stelios S. Koroneos

Digital OPSiS - Embedded Intelligence
http://www.digital-opsis.com

Re: getting started - docbook

[Koen Kooi]

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

David Farning schreef:
> On Sat, Oct 27, 2007 at 07:27:37PM +0200, Koen Kooi wrote:
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>>
>> David Farning schreef:
>>> On Sat, Oct 27, 2007 at 01:06:59PM +0200, Tobias Pflug wrote:
>>>> on 1: 
>>>> with big picture I mean there should be a description of the 
>>>> "system" with its main components. Currently i think there is too
>>>> little of that, and too many use-cases. ("In order to change xyz,
>>>> apply abc to 123").
>>> I finished a rough draft of getting started this morning.  I am going
>>> to let it sit for a week before looking at it again.  Then I will
>>> rework as needed and submitte for review.
>>>
>>> In the mean time I am starting on a introduction chapter.  This will
>>> be a very high level overview.  Below is a first stab at the outline.
>> Even if 99.9% if the people use OE to build linux stuff, it is able to
>> build nonlinux targets like bare-metal stuff for the msp430
>> microcontroller and things like arm-wince-pe or arm-apple-darwin.
> 
> That makes sense.  Nothing special about the Linux kernel.  For the
> purposes of documentation would you mind if we:
> 
> 1 Studied the device - processer, memory, IO, devices....
> 2 Studied a generic Linux distribution - kernel, libs, apps, packages,
> files system....
> 3 Discussed how to use bb/oe to create a customized distro to run on a
> specific device.

I don't mind at all, since I said that's what 99% of the people do :)

regards,

Koen
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.5 (Darwin)

iD8DBQFHJEtkMkyGM64RGpERAj1lAJwKnbjzj21rEj9TLZUfqrF0DHDQHwCgulo7
CaUokllIm5bTMLMv/dIg1Ko=
=f5+C
-----END PGP SIGNATURE-----

Re: getting started - docbook

[Detlef Vollmann]

David Farning wrote:
> 1.1. Linux ................................................
>       1.1.1. Linux Overview ...................
>       1.1.2. Linux Arctoture ...................
>       1.1.3. Linux Development Model..
>       1.1.4. Linux Open Source..............
> 1.2. Embedded Device ............................
>       1.2.1. Device Architure..................
>       1.2.2. Processor..............................
>       1.2.3. Storage.................................
>       1.2.4. Device..................................
> 1.3. Linux Distribution............................
>       1.3.1. Kernel ..................................
>       1.3.2. Userspace.............................
>       1.3.3. File System ..........................
>       1.3.4. Updating ..............................
> 1.4. System startup ..................................
>       ...
> 1.5. Host/Target .......................................
>       ...
> 1.6. Overview ..........................................
> 1.7. History..............................................

This looks like a (more or less general) introduction to
"Embedded Linux".
No problems with that, but make sure not to confuse this with
documentation on how to use OpenEmbedded.

I think there are two different targets for documentation:
  1 - How to use OpenEmbedded
  2 - What to build with OpenEmbedded

There's always a need for both, but I think it's helpful
to keep them separate (but probably reference each other).

Your TOC for an introduction looks like documentation for 2.

   Detlef

Re: getting started - docbook

[Tobias Pflug]

On Wed, 2007-10-31 at 13:26 +0100, Detlef Vollmann wrote:
> David Farning wrote:
> > 1.1. Linux ................................................
> >       1.1.1. Linux Overview ...................
> >       1.1.2. Linux Arctoture ...................
> >       1.1.3. Linux Development Model..
> >       1.1.4. Linux Open Source..............
> > 1.2. Embedded Device ............................
> >       1.2.1. Device Architure..................
> >       1.2.2. Processor..............................
> >       1.2.3. Storage.................................
> >       1.2.4. Device..................................
> > 1.3. Linux Distribution............................
> >       1.3.1. Kernel ..................................
> >       1.3.2. Userspace.............................
> >       1.3.3. File System ..........................
> >       1.3.4. Updating ..............................
> > 1.4. System startup ..................................
> >       ...
> > 1.5. Host/Target .......................................
> >       ...
> > 1.6. Overview ..........................................
> > 1.7. History..............................................
> 
> This looks like a (more or less general) introduction to
> "Embedded Linux".
> No problems with that, but make sure not to confuse this with
> documentation on how to use OpenEmbedded.
> 
> I think there are two different targets for documentation:
>   1 - How to use OpenEmbedded
>   2 - What to build with OpenEmbedded
> 
> There's always a need for both, but I think it's helpful
> to keep them separate (but probably reference each other).
> 
> Your TOC for an introduction looks like documentation for 2.
> 
>    Detlef
> 

Now that is /exactly/ what I was trying to say earlier, only you nailed
it better on the spot. This TOC looks like information you can find in
various books on embedded linux practices or linux kernel development in
general.. What's actually lacking is *OE specific* information.

regards,
Tobi

Re: getting started - docbook

[David Farning]

> Now that is /exactly/ what I was trying to say earlier, only you nailed
> it better on the spot. This TOC looks like information you can find in
> various books on embedded linux practices or linux kernel development in
> general.. What's actually lacking is *OE specific* information.
> 
I agree with you both the the OE specific information is what is going
to be the key.  This chapter is going to be pretty brief.

chap 1 intro -15 pages
part 1 embedded device.  Review of the key components.  Will direct
the reader to other resources for more background.

part 2 distribution.  Review to the key components. Will direct the
reader to other resources for more background.

part 3 developing a distribution.  Very general overview of what is
involved in developing a distribution for a device.  Introduction into
how bb/oe can be used to develop a distro.

chap 2 getting started -25 pages
1 install bb
2 install oe
3 configure
4 build
5 test

chap 3 bitbake tutorial - 20 pages

chap 4 Language specific details - ??

chap 5 standard libs/classes

I am still hashing out how to organize chaps 3-5.  A lot of the
information is already available on the wiki or current users manual.
It just needs to be organized and/explained.

For the time being I am thinking a recipes/classes/configs as being
written in the language bb.  This language, like c, is very simple. I
defined variable, tasks(for functions), and a couple of
keywords(inherit, require,...).

Most of the functionality comes from the standard libs(or classes).

I am note sure if this technique will hold or not. It is certainly
helpful while thinking about how different elements of recipes are
written.  I'll let you know in a few days if it seems to be a logical
way of explaining how to write recipes.

I am not sure if you meant to write a new language, but it looks like
you have done so!

Thank
David Farning

Re: getting started - docbook

[Filippo Basso]

> chap 1 intro -15 pages
> part 1 embedded device.  Review of the key components.  Will direct
> the reader to other resources for more background.
>
> part 2 distribution.  Review to the key components. Will direct the
> reader to other resources for more background.
>
> part 3 developing a distribution.  Very general overview of what is
> involved in developing a distribution for a device.  Introduction into
> how bb/oe can be used to develop a distro.
>
> chap 2 getting started -25 pages
> 1 install bb
> 2 install oe
> 3 configure
> 4 build
> 5 test
>
> chap 3 bitbake tutorial - 20 pages
>
> chap 4 Language specific details - ??
>
> chap 5 standard libs/classes
David, great work!!!
your work looks really nice for the opensource community!
I'll send you my .02€ on some points I'm investigating into... now I'm
testing some basic point, independence on host system was a quite not
simple problem for last weeks (about graph(viz)s manipulation still take
some time to finish it...).
phy

Re: getting started - docbook

[Detlef Vollmann]

Cliff Brake wrote:
> On 10/25/07, David Farning <dfarning@gmail.com> wrote:

>>But I am struggling over what to call the object of a bitebake.  (In
>>make they are call targets .ie make all, but in the embedded world
>>target is used to refer to the device for which you are building.)
>>
>>$bitbake vim
>>$bitbake task-base
>>$bitbake gpe-image
>>$bitbake world
>>A package, a task, an image, and world?
> 
> 
> I suppose it depends -- saying that I'm "building a packages" is
> technically correct as the ipk/deb is the output.  But, "bitbaking a
> recipe" is probably more correct.
"bitbaking a recipe" is correct.
But "vim" or "task-base" above are not recipes.
"vim_7.0.bb" or "task-base.bb" are recipes.

I still think "target" (or "build target") would be the
best term for "vim" or "task-base", though I agree that
this might be confused with the "target device".

   Detlef