Skip to contentSkip to conversation

filling in the "missing" entries in the ref manual variable glossary

DISCUSSION Robert P. J. Day 4 participants 7 messages Oct 24, 2013 – Nov 5, 2013

lore
Share & tools
lore
#0 lore raw

expecting the standard reaction to be, "hey, feel free to submit a
patch :-)", i've noticed that there are (unsurprisingly) quite a number of variables missing from the variable glossary in the ref manual.

just related to u-boot (which i've been messing with this morning),
here's the current situation:

http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-U

and what seems to be missing is:

* UBOOT_ARCH
* UBOOT_SUFFIX
* UBOOT_BINARY
* UBOOT_IMAGE
* UBOOT_MAKE_TARGET
* UBOOT_SYMLINK

short of submitting full patches for things like this, is there at least a list we can keep track of this stuff on? i'm not sure i have the time to submit full explanatory patches for everything i run across, but i can at least report what's missing if that's useful.

rday

Signature · 7 lines
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
#1 lore raw

Hey Robert,

You don't need to submit full patches and explanations for these. Noting that they are missing and need documenting is perfect. If you do have time when you point out a missing variable, providing a brief explanation would help. And... reporting what is missing is extremely useful. It has been (and will continue to be) an ongoing process of fully documenting variables in the reference manual.

Thanks,
Scott

Quoted 50 lines

-----Original Message-----
From: [email protected] [mailto:yocto- [email protected]] On Behalf Of Robert P. J. Day
Sent: Thursday, October 24, 2013 8:40 AM
To: Yocto discussion list
Subject: [yocto] filling in the "missing" entries in the ref manual variable glossary

expecting the standard reaction to be, "hey, feel free to submit a patch :-)",
i've noticed that there are (unsurprisingly) quite a number of variables missing from the variable glossary in the ref manual.

just related to u-boot (which i've been messing with this morning), here's the
current situation:

http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-
U

and what seems to be missing is:

* UBOOT_ARCH
* UBOOT_SUFFIX
* UBOOT_BINARY
* UBOOT_IMAGE
* UBOOT_MAKE_TARGET
* UBOOT_SYMLINK

short of submitting full patches for things like this, is there at least a list we can keep track of this stuff on? i'm not sure i have the time to submit full explanatory patches for everything i run across, but i can at least report what's missing if that's useful.

rday

--

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

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

===========================================================
=============
_______________________________________________
yocto mailing list
[email protected]
https://lists.yoctoproject.org/listinfo/yocto

#2 lore raw
Quoted 11 lines · Scott M

Hey Robert,

You don't need to submit full patches and explanations for these. Noting that they are missing and need documenting is perfect. If you do have time when you point out a missing variable, providing a brief explanation would help. And... reporting what is missing is extremely useful. It has been (and will continue to be) an ongoing process of fully documenting variables in the reference manual.

Thanks,
Scott

for better or worse, here's what i've decided to do. for my own
teaching purposes so i can quickly refer to all the variables related to a single subject in front of a class, i started a wiki page which will be an OE variable glossary broken into sections and grouping related variables. here's the initial result for nothing more than variables related to u-boot:

http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary#U-Boot_variables

that entire section took about 10 minutes to write and i now have what i *think* is a list of every OE variable related to u-boot in the following format:

* if a variable is already documented in the ref manual, i just link
to it and leave it at that
* if a variable isn't documented, i add it to the list but
(obviously) without a link

and since i also want to see the usage of these things, i do a quick
"grep" for each one, which showed me that nothing seems to be using the documented "UBOOT_TARGET" variable, but it seems that what *should* be documented is "UBOOT_MAKE_TARGET" instead. and also, none of the SPL-related variables are mentioned in the reference manual so i list them as well. as i said, that section took all of about 10 minutes to write so it's not all that time-consuming.

this is what i'm going to be working on over the next several days,
so if scott (or anyone else) wants to play along, that page will certainly point out what variables are missing from the ref manual, as well as any oddities i run across and someone else can submit patches for the ref manual -- there's just no way i have the time to create all the patches, but i can certainly at least point out what needs patching.

thoughts?

rday

Signature · 7 lines
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
#3 lore raw

This will be useful for me... thanks Robert.

Scott

Quoted 70 lines

-----Original Message-----
From: Robert P. J. Day [mailto:[email protected]]
Sent: Friday, November 01, 2013 6:46 AM
To: Rifenbark, Scott M
Cc: Yocto discussion list
Subject: RE: [yocto] filling in the "missing" entries in the ref manual variable glossary

Quoted 11 lines · Scott M

Hey Robert,

You don't need to submit full patches and explanations for these. Noting that they are missing and need documenting is perfect. If you do have time when you point out a missing variable, providing a brief explanation would help. And... reporting what is missing is extremely useful. It has been (and will continue to be) an ongoing process of fully documenting variables in the reference manual.

Thanks,
Scott

for better or worse, here's what i've decided to do. for my own teaching
purposes so i can quickly refer to all the variables related to a single subject in front of a class, i started a wiki page which will be an OE variable glossary broken into sections and grouping related variables. here's the initial result for nothing more than variables related to u-boot:

http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary#U-
Boot_variables

that entire section took about 10 minutes to write and i now have what i *think* is a list of every OE variable related to u-boot in the following format:

* if a variable is already documented in the ref manual, i just link to it and leave it at that
* if a variable isn't documented, i add it to the list but (obviously) without a link

and since i also want to see the usage of these things, i do a quick "grep" for each one, which showed me that nothing seems to be using the documented "UBOOT_TARGET" variable, but it seems that what
*should* be documented is "UBOOT_MAKE_TARGET" instead. and also, none of the SPL-related variables are mentioned in the reference manual so i list them as well. as i said, that section took all of about 10 minutes to write so it's not all that time-consuming.

this is what i'm going to be working on over the next several days, so if scott (or anyone else) wants to play along, that page will certainly point out what variables are missing from the ref manual, as well as any oddities i run across and someone else can submit patches for the ref manual -- there's just no way i have the time to create all the patches, but i can certainly at least point out what needs patching.

thoughts?

rday

--

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

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

===========================================================
=============

#4 lore raw
Quoted 1 line · Scott M

This will be useful for me... thanks Robert.

i'm about halfway through the categorized variable glossary:

http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary

and a few variables that caught my eye:

* BUGTRACKER (not mentioned)
* TUNE_ARCH (not mentioned)
* TUNE_FEATURES (not mentioned)
* CLASSOVERRIDE (not mentioned)
* UBOOT_TARGET (mentioned, but replaced by UBOOT_MAKE_TARGET?)

and a number of UBOOT-related variables aren't mentioned. not clear if any of these *should* be added -- there's obviously a limit to how many variables you should explain -- but you can decide if any should be added to the ref manual.

rday

Signature · 7 lines
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================
#5 lore raw

Hi Robert,

Quoted 15 lines · On Tuesday 05 November 2013 01:34:56 Robert P. J. Day wrote:
Quoted 1 line · Scott M

This will be useful for me... thanks Robert.

i'm about halfway through the categorized variable glossary:

http://www.crashcourse.ca/wiki/index.php/OE_variable_glossary

and a few variables that caught my eye:

* BUGTRACKER (not mentioned)
* TUNE_ARCH (not mentioned)
* TUNE_FEATURES (not mentioned)
* CLASSOVERRIDE (not mentioned)
* UBOOT_TARGET (mentioned, but replaced by UBOOT_MAKE_TARGET?)

Quoted 4 lines

and a number of UBOOT-related variables aren't mentioned. not clear if any of these *should* be added -- there's obviously a limit to how many variables you should explain -- but you can decide if any should be added to the ref manual.

I think a variable should be documented if anyone will ever need to know what it does - and that probably includes almost all variables. I have talked with Scott in the past about some kind of labelling system for the variable glossary so you can see at a glance where the variable is supposed to be used and (hopefully, if we can come up with sane categorisation) when it's appropriate to modify.

IMO, all of those you listed should be documented. I've just entered a bug about documenting the tune files / variables at least:

https://bugzilla.yoctoproject.org/show_bug.cgi?id=5463

Cheers,
Paul

Signature · 2 lines
Paul Eggleton
Intel Open Source Technology Centre
#6 lore raw
In reply to Robert P. J. Day
Quoted 5 lines · Robert P. J. Day

expecting the standard reaction to be, "hey, feel free to submit a
patch :-)", i've noticed that there are (unsurprisingly) quite a number of variables missing from the variable glossary in the ref manual.

well I have a different response as alternative file a bug in YP bugzilla :)

Quoted 35 lines

just related to u-boot (which i've been messing with this morning),
here's the current situation:

http://www.yoctoproject.org/docs/latest/ref-manual/ref-manual.html#var-U

and what seems to be missing is:

* UBOOT_ARCH
* UBOOT_SUFFIX
* UBOOT_BINARY
* UBOOT_IMAGE
* UBOOT_MAKE_TARGET
* UBOOT_SYMLINK

short of submitting full patches for things like this, is there at least a list we can keep track of this stuff on? i'm not sure i have the time to submit full explanatory patches for everything i run across, but i can at least report what's missing if that's useful.

rday

--

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

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

========================================================================
_______________________________________________
yocto mailing list
[email protected]
https://lists.yoctoproject.org/listinfo/yocto