Variable reference (was: Documentation update about machine conf files)

Variable reference (was: Documentation update about machine conf files)

[Steffen Sledz]

[start new thread because of the more common subject]

>> I would be really happy about an index of all variables usable in the
>> recipes together with a desciption or a reference to it. I would
>> prefer such an index in the wiki, but manual or documentation.conf
>> would be fine too.
> 
> Something like that you mean?
> 
> http://pokylinux.org/doc/poky-handbook.html#ref-variables-glossary

Yes.

Would be nice if it is not a glossary only but contains additional info (e.g. exact usage, restrictions, dependencies, examples). This may be realized by references to an own (wiki) page for each variable which needs more than a one liner.

What's the community opinion? Should we start such an index in the wiki?

Steffen

Re: Variable reference (was: Documentation update about machine conf files)

[Holger Hans Peter Freyther]

On Friday 21 August 2009 08:11:50 Steffen Sledz wrote:
> [start new thread because of the more common subject]
>
> >> I would be really happy about an index of all variables usable in the
> >> recipes together with a desciption or a reference to it. I would
> >> prefer such an index in the wiki, but manual or documentation.conf
> >> would be fine too.
> >
> > Something like that you mean?
> >
> > http://pokylinux.org/doc/poky-handbook.html#ref-variables-glossary
>
> Yes.
>
> Would be nice if it is not a glossary only but contains additional info
> (e.g. exact usage, restrictions, dependencies, examples). This may be
> realized by references to an own (wiki) page for each variable which needs
> more than a one liner.
>
> What's the community opinion? Should we start such an index in the wiki?

Long time ago, I created conf/documentation.conf. For every variable back then 
we have used VAR[doc] = "Documentation" to describe the semantic of this 
variable. A utility like bitdoc spit out a HTML page...

I would like to see this updated.

z.

Re: Variable reference (was: Documentation update about machine conf files)

[Steffen Sledz]

>> Would be nice if it is not a glossary only but contains additional info
>> (e.g. exact usage, restrictions, dependencies, examples). This may be
>> realized by references to an own (wiki) page for each variable which needs
>> more than a one liner.
>>
>> What's the community opinion? Should we start such an index in the wiki?
> 
> Long time ago, I created conf/documentation.conf. For every variable back then 
> we have used VAR[doc] = "Documentation" to describe the semantic of this 
> variable. A utility like bitdoc spit out a HTML page...
> 
> I would like to see this updated.

It's a good starting point. But it has one drawback: It allows a short one liner docu only. Often it would be great to have some more info, e.g. a list of supported image file system types for IMAGE_FSTYPES.

Steffen

Re: Variable reference (was: Documentation update about machine conf files)

[Holger Hans Peter Freyther]

On Monday 24 August 2009 17:00:47 Steffen Sledz wrote:
> >> Would be nice if it is not a glossary only but contains additional info
> >> (e.g. exact usage, restrictions, dependencies, examples). This may be
> >> realized by references to an own (wiki) page for each variable which
> >> needs more than a one liner.
> >>
> >> What's the community opinion? Should we start such an index in the wiki?
> >
> > Long time ago, I created conf/documentation.conf. For every variable back
> > then we have used VAR[doc] = "Documentation" to describe the semantic of
> > this variable. A utility like bitdoc spit out a HTML page...
> >
> > I would like to see this updated.
>
> It's a good starting point. But it has one drawback: It allows a short one
> liner docu only. Often it would be great to have some more info, e.g. a
> list of supported image file system types for IMAGE_FSTYPES.

Why do you think so?

Re: Variable reference (was: Documentation update about machine conf files)

[Steffen Sledz]

Holger Hans Peter Freyther wrote:
>> It's a good starting point. But it has one drawback: It allows a short one
>> liner docu only. Often it would be great to have some more info, e.g. a
>> list of supported image file system types for IMAGE_FSTYPES.
> 
> Why do you think so?

When i had a look into conf/documentation.conf it occurred to me that the documentation field may only be a simple string. It seems not to be possible to use e.g. tables or lists there. Sorry, if i'm wrong here.

Steffen

Re: Variable reference (was: Documentation update about machine conf files)

[Holger Hans Peter Freyther]

On Tuesday 25 August 2009 12:45:15 Steffen Sledz wrote:
> Holger Hans Peter Freyther wrote:
> >> It's a good starting point. But it has one drawback: It allows a short
> >> one liner docu only. Often it would be great to have some more info,
> >> e.g. a list of supported image file system types for IMAGE_FSTYPES.
> >
> > Why do you think so?
>
> When i had a look into conf/documentation.conf it occurred to me that the
> documentation field may only be a simple string. It seems not to be
> possible to use e.g. tables or lists there. Sorry, if i'm wrong here.

Ah okay, it certainly is possible to embed HTML, it might not be so pleasant.

z.

Re: Variable reference (was: Documentation update about machine conf files)

[Christian Gagneraud]

Steffen Sledz wrote:
> Holger Hans Peter Freyther wrote:
>>> It's a good starting point. But it has one drawback: It allows a short one
>>> liner docu only. Often it would be great to have some more info, e.g. a
>>> list of supported image file system types for IMAGE_FSTYPES.
>> Why do you think so?
> 
> When i had a look into conf/documentation.conf it occurred to me
> that the documentation field may only be a simple string. It seems not
> to be possible to use e.g. tables or lists there. Sorry, if i'm wrong
> here.

Hi,

Actually i was thinking as well to have a document presented as a 
matrix that will show quickly when and where this variables are 
intended to be used or not, ie:

For each variable, there could be a:
- one line documentation
- default value
- Used by (see below)
- Used in (see below)

For "Used by" and "Used in", it could be nice to specify yes, no or 
maybe (with default to no) for the following:
   - bitbake itself
   - <file>.bbclass
   - <package>.bb
   - <meta>.bb
   - <image>.bb
   - bitbake.conf
   - <distro>.conf
   - <machine>.conf
   - local.conf
   - any other interesting things...

For the difference between used by and used in, here is an example:
CMDLINE is used in <machine>.conf or local.conf, and is used by linux.inc

I'm not (yet) familiar with bitbake and bbclass, but I guess that it 
is possible to extract all these information and generate say an xml 
file that can be in turn transformed into anything people like.


By greping/seding into all the bb, bbclass, inc and conf file, one (I) 
can set-up a list of all variable currently in use in OE, post it here 
on oedev mailing list and then people can help to sort out which ones 
are worth documenting.

Currently greping is the way I am doing to learn OE (as well as 
reading documentation and ML archive of course! ;)), but I found it a 
bit painful...

Here is an example of what i did recently to find out what variables 
was used in the various machine config file and who was using them:
$ sed -ne 's,^[[:blank:]]*\([[:alnum:]_/]\+[[:blank:]]\)=.*$,\1,gp' 
conf/machine/*.conf |sort|uniq > var-used-in-machine
$ cat var-used-in-machine
BASE_PACKAGE_ARCH
BOOTSTRAP_EXTRA_RDEPENDS
ERASEBLOCK_SIZE
EXTRA_IMAGECMD
EXTRA_IMAGECMD_h1910_jffs2
EXTRA_IMAGECMD_jffs2
[...]
module_autoload_pxa27x_udc
module_conf_acx
module_conf_g_ether
udevdir
$ for v in $(cat var-used-in-machine); do echo " * $v:"; grep -l $v 
classes/* recipes/*/*; done > var-used-in-machine-are-used-by
$ cat var-used-in-machine-are-used-by
[...]
  * PCMCIA_MANAGER:
packages/tasks/task-base.bb
[...]
  * TARGET_PREFIX:
classes/base.bbclass
classes/icecc.bbclass
classes/kernel.bbclass
classes/module-base.bbclass
classes/native.bbclass
classes/srec.bbclass
[...]

This is far from perfect and can be improved. It doesn't take into 
account overrides and virtual for example, as well in that case I made 
the assumption that the vars are used in <machine>.conf and are used 
by recipes/* which is not really true... Anyway this gave me a first 
hint at where to look at.

Regards,
Chris

> 
> Steffen
> 
> 
> 
> _______________________________________________
> Openembedded-devel mailing list
> Openembedded-devel@lists.openembedded.org
> http://lists.linuxtogo.org/cgi-bin/mailman/listinfo/openembedded-devel

Re: Variable reference (was: Documentation update about machine conf files)

[Steffen Sledz]

Christian Gagneraud wrote:
> Actually i was thinking as well to have a document presented as a matrix
> that will show quickly when and where this variables are intended to be
> used or not, ie:
> 
> For each variable, there could be a:
> - one line documentation
> - default value
> - Used by (see below)
> - Used in (see below)
> 
> For "Used by" and "Used in", it could be nice to specify yes, no or
> maybe (with default to no) for the following:
>   - bitbake itself
>   - <file>.bbclass
>   - <package>.bb
>   - <meta>.bb
>   - <image>.bb
>   - bitbake.conf
>   - <distro>.conf
>   - <machine>.conf
>   - local.conf
>   - any other interesting things...
> 
> For the difference between used by and used in, here is an example:
> CMDLINE is used in <machine>.conf or local.conf, and is used by linux.inc
> 
> I'm not (yet) familiar with bitbake and bbclass, but I guess that it is
> possible to extract all these information and generate say an xml file
> that can be in turn transformed into anything people like.
> ...

This sounds really good.

If this can done be automatically may be the best place for it could be a generated appendix to the user manual.

Steffen