Bug 10196

Version 2 (minor rewording, fixed a typo):

  3.2. Exporting Variables to the Environment
  
    Variables can be exported to the environment of running tasks by using the
    'export' keyword. For example, in the following snippet, the do_foo task
    prints "value from the environment" when run:
    
      export ENV_VARIABLE
      ENV_VARIABLE = "value from the environment"
    
      do_foo() {
          bbplain "$ENV_VARIABLE"
      }

    Note that $ENV_VARIABLE is not expanded by BitBake in this case, because it
    lacks the obligatory {}. Rather, it is expanded by the shell.

    It does not matter whether 'export ENV_VARIABLE' appears before or after
    assignments to ENV_VARIABLE.
    
    It is also possible to combine 'export' with setting a value for the
    variable, like in the following example:
    
      export ENV_VARIABLE = "value from environment"

    In the output of 'bitbake -e', variables that are exported to the
    environment are preceded by "export".
    
    Important variables exported to the environment include e.g. CC and CFLAGS,
    which are picked up by many build systems.

Ulf, 

I worked this section a bit so read it over.  Also, I am concerned about the very last paragraph where we note the CC and CCFLAGS variables as being exported.  These are variables specific to the YP?  I know they don't exist in the BB manual glossary.  Recall that one thing we don't do is link from the BB manual directly into the YP docs.  In this case, it is not a link but sort of an indirect reference back into the YP project.  

I also opted for "Notable" rather than "Important" as I felt "Important" implied not all variables are important.

Let me know what you think.

Scott

http://www.yoctoproject.org/docs/2.2/bitbake-user-manual/bitbake-user-manual.html#exporting-variables-to-the-environment

Looks fine except a small nit. Did the comma disappear here?

  BitBake does not expand $ENV_VARIABLE in this case<,> because it lacks the
  obligatory {}.

Re. CC and CFLAGS, maybe it could be rewritten like this to not make it sound like they are always exported:

  Variables commonly exported to the environment include e.g. CC and CFLAGS,
  which are picked up by many build systems.

Ulf

Another tiny nit. Why is "variable-value" in italics here?

  export ENV_VARIABLE = "variable-value"

I guess it could be "variable value" as well, to make it clear that spaces are no problem (even though it's probably obvious :P).

Hmm... I think I see the thinking behind having it in italics now, so I'm fine with it. It's consistent with having "recipe" in italics in the MLPREFIX entry.

I guess I was assuming this was a place holder where the user would put in some variable value.  Is that not right?  Should it be literally "variable value"?

In places in the manual where I have example code that has syntax where a user needs to provide something like a recipe name, I use the DocBook tags to italicize that:

  X = <replaceable>value</replaceable>

If that is not the case here I can change it back.

Scott

Collided :)

Ok - thanks.

Yup, the comma is the only nit I have left. :)

Here's a version that avoids a mid-sentence "e.g." re. CC and CFLAGS. Maybe it reads a bit better.

  Among the variables commonly exported to the environment are CC
  and CFLAGS, which are picked up by many build systems.

I fixed that last paragraph.

Question of the comma is an interesting one....  The simple answer on whether you need a comma before "because" is that you don't.  However, there are cases where you want it if the sentence could be ambiguous without the comma.    

Here is an example:

  He didn’t run because he was afraid.

Without a comma, you don’t know whether the writer means that the reason the man didn’t run was that he was afraid or whether the writer means there was some different reason the man ran.

If you put a comma before because (He didn’t run, because he was afraid), it’s clear that the part after the comma is extra information: the reason the man didn’t run—because he was afraid.

If you leave out the comma, you should probably add clarifying information to the end of the sentence. For example, you could write

He didn’t run because he was afraid; he ran because the fire made his hiding place too hot.

That little example is what they use from the "Chicago Manual of Style".

The way I wrote it the "in this case" acts like a comma.  It basically acting to separate out this particular reason for not expanding the variable.  It implies there are other possible reasons why it would not get expanded.  So, can non-expansion occur for other reasons?  

This shit is probably boring you but I find it extremely interesting :)

We could say the following:

 "In the previous example, BitBake does not expand $ENV_VARIABLE, because it lacks the obligatory {}. Rather, $ENV_VARIABLE is expanded by the shell."

That version implies other reasons for non-expansion exist.  This one here does not imply other reasons for non-expansion exist:

 "In the previous example, BitBake does not expand $ENV_VARIABLE because it lacks the obligatory {}. Rather, $ENV_VARIABLE is expanded by the shell.

Yeah, I was thinking of a similar example:

  I don't like shrimp because of the texture.

That sentence makes it sound like there should be a "but because ..." following it, like below:

  I don't like shrimp because of the texture, but because of the taste.

If you put in a comma, then it becomes clear:

  I don't like shrimp, because of the texture.

(I like shrimp. I just come up with crap example sentences. :P)

It's clear in context regardless though, so it's not super important. I'm fine with the existing version. :)

Cheers,
Ulf

Haha... it is awesome that you even thought about it :)

Great working with someone that can write!

Setting to RESOLVED and putting the doc flag to "done."

Thanks