Bug 10093 - Suggested fleshing out of the anonymous function documentation
Summary: Suggested fleshing out of the anonymous function documentation
Status: RESOLVED FIXED
Alias: None
Product: BitBake User Manual
Classification: Documentation
Component: bitbake-manual (show other bugs)
Version: 2.2
Hardware: x86 Multiple
: Undecided normal
Target Milestone: 2.2 M4
Assignee: Scott Rifenbark
QA Contact:
URL:
Whiteboard: 08 August 2016: RESOLVED
Depends on:
Blocks:
 
Reported: 2016-08-05 02:45 UTC by ulfalizer
Modified: 2016-08-08 20:42 UTC (History)
2 users (show)

See Also:
OS type for building Yocto: ---
Type of Regression: ---
Verified:
Documentation change: Done (doc changes complete)


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description ulfalizer 2016-08-05 02:45:00 UTC
The documentation on anonymous Python functions doesn't have much detail at the
moment. The following two changes try to make it clearer when anonymous
functions run, how their effects are seen, and how they act in corner cases:

Rewrite '3.4.4. Anonymous Python Functions' as follows:

  Sometimes it is useful to set variables or perform other operations
  programmatically during parsing. To do this, you can define special Python
  functions, called anonymous Python functions, that run at the end of parsing.
  Here is an example that conditionally sets a variable based on the value of
  another variable:
  
       python () {
           if d.getVar('SOMEVAR', True) == 'value':
               d.setVar('ANOTHERVAR', 'value2')
       }
  
  An equivalent way to mark a function as an anonymous function is to give it
  the name "__anonymous", rather than no name.
  
  Anonymous Python functions always run at the end of parsing, regardless of
  where they are defined. If a recipe contains many anonymous functions, they
  run in the same order as they are defined within the recipe. As an example,
  consider the following snippet:
  
      python () {
          d.setVar('FOO', 'foo 2')
      }
  
      FOO = "foo 1"
  
      python () {
          d.appendVar('BAR', ' bar 2')
      }
  
      BAR = "bar 1"
  
  This is conceptually equivalent to the following snippet:
  
      FOO = "foo 1"
      BAR = "bar 1"
      FOO = "foo 2"
      BAR += "bar 2"
  
  FOO ends up with the value "foo 2", and BAR with the value "bar 1 bar 2". Just
  as in the second snippet, the values set for the variables within the anonymous
  functions become available to tasks, which always run after parsing.
  
  Overrides and override-style operators such as "_append" are applied before
  anonymous functions run. In the following example, FOO ends up with the value
  "foo from anonymous".
  
      FOO = "foo"
      FOO_append = " from outside"
  
      python () {
          d.setVar("FOO", "foo from anonymous")
      }
  
  See [3.10. Accessing Datastore Variables Using Python] for some methods you can
  use within anonymous Python functions.
  
  For a different method to run Python code during parsing, see
  [3.1.12. Inline Python Variable Expansion].


Add this to the end of '3.1.12. Inline Python Variable Expansion':

  For a different way to set variables with Python code during parsing, see
  [3.4.4. Anonymous Python Functions].


Cheers,
Ulf
Comment 1 Scott Rifenbark 2016-08-08 15:53:26 UTC
Ulf, 

See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#anonymous-python-functions for the re-write of the "Anonymous Python Functions" section.

See http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#inline-python-variable-expansion for the additional cross-reference in the "Inline Python Variable Expansion" section.

Thanks, 
Scott
Comment 2 ulfalizer 2016-08-08 19:24:02 UTC
Looks good to me.

Thanks,
Ulf
Comment 3 Scott Rifenbark 2016-08-08 20:42:33 UTC
Thanks - setting to RESOLVED and putting doc flag to "done."

Scott
Comment 4 Scott Rifenbark 2016-08-08 20:42:52 UTC
Forgot the flag.. reset to "done"