recipe whitespace style questions

This maybe opens a can of worms, but:

A recent comment on a patch raised the issue of how to do whitespace indentation on multiple-line continuations: specifically, how many spaces should be used. This is not addressed in the current style-guide and is something I've been confused about too.

I don't know that I particularly care which way it's done, but I would like guidance to help me be consistent for recipes I create.

Would a patch to update the style guide with clarifications be acceptable? The intent of the proposed text below is to recommend:

SRC_URI = "file://skeleton \
           file://skeleton_test.c \
           file://COPYRIGHT \
           "

which should be displayed in a fixed-width font with the "file" words all aligned.

Next: I can find no documented recommendation in whether the closing quote is indented or not. In addition to above (which in my display has the closing quote aligned with the letter 'f' of "file"; call this style "content aligned"), I've also seen:

SRC_URI = "file://skeleton \
           file://skeleton_test.c \
           file://COPYRIGHT \
          "

which I'll call "quote aligned", and:

SRC_URI = "file://skeleton \
           file://skeleton_test.c \
           file://COPYRIGHT \

"

which I'll call "none", and;

SRC_URI = "file://skeleton \
           file://skeleton_test.c \
           file://COPYRIGHT"

which I'll call "joined".

Again, for consistency's sake it would be nice to have a recommendation. I personally prefer "none", which matches the closing bracket style for functions.

Next: I've also seen:

SRC_URI = " \
    file://skeleton \
    file://skeleton_test.c \
    file://COPYRIGHT \

"

which generalizes the Python 4-space indentation rule and is a nice option when the variable name is so long the content would go beyond 80 characters if it appeared on the first line.

Finally, the use of tabs for shell functions is not preserved by meta-openembedded/contrib/oe-stylize. Do any of the core developers recommend using that script, and if so does it need to be updated? Do Yocto project coding standards apply to meta-openembedded? And what about whitespace for multiple-line continuations within a shell function: one tab level?

If we can reach some level of consensus (or fiat) I'll prepare a patch for the style guide. I think the following captures the proposed clarifications:

* Multiple-line continuations should be indented to the level of the content following the introductory quote symbol on the first line.

* Alternatively, the first line of a multi-line value may be continued after a single space following the introductory quote symbol and all subsequent content lines indented four spaces (or one tab if within a shell function)

*Any closing quote of a multiple-line continuation should be placed at the indentation level of the first continued line.

If you feel this is all too nit-picky just ignore it.

Peter

I prefer this one (especially for longer variables or entries) or "none", because with "none" it's easier to see where multiline variable ends.

Worst is IMHO "joined" because when appending one more line you have to edit 2 lines to move '"' so the diff for review is longer and harder to read than just one added line.

Martin 'JaMa' Jansa     jabber: [email protected]

I'd agree on both counts.

Christopher Larson

To close this out: that's three votes for the style named "none" or the one with separated lines. No objections raised.

I'd thought the style guide was part of the Yocto documentation so I could prepare a patch to it, but it appears to only exist (independently) on the Yocto (https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide) and OpenEmbedded (http://www.openembedded.org/wiki/Styleguide) wiki sites.

In lieu of my applying for accounts on those sites and updating them I'll leave it that I think these additions would document the conclusions of this discussion, and are what I'll try to follow in my own Yocto-based recipe development:

* Multiple-line continuations should be indented to the level of the content following the introductory quote symbol on the first line.

* Alternatively, the first line of a multi-line value may be continued after the introductory quote symbol, with all subsequent content lines indented four spaces (or one tab if within a shell function)

* Any closing quote of a multiple-line continuation should be placed at the indentation level of the first continued line.

Peter