Difference between revisions of "Styleguide"

From Openembedded.org
Jump to: navigation, search
(New page: = Version policy for OE recipes = There is general confusion about what a correct PV string should look like. This page attempts to define a standard for packages in OpenEmbedded to follow...)
 
(Explicitly link to Versioning Policy page)
(31 intermediate revisions by 10 users not shown)
Line 1: Line 1:
= Version policy for OE recipes =
+
= Motivation =
There is general confusion about what a correct PV string should look like. This page attempts to define a standard for packages in OpenEmbedded to follow. Whilst not mandatory, it is strongly recommended.
 
 
OE's versioning policy aims to follow that of Debian (and is hence compatible with ipkg).
 
 
Debian's PV policy can be viewed at [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version]
 
  
One key phrase to note is "The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters." This means characters like + and - have a higher priority than alphanumeric characters.
+
As with most style guides, the idea here is to have a consistent format and look so that when someone new comes to the scene they can learn quickly and get involved. This also helps reviewers and maintainers understand what changes are being made by contributors.
If in doubt, experiment with the ipkg-compare-versions program from ipkg-utils.
 
  
'''NOTE''': this page was based on a [http://handhelds.org/hypermail/oe/42/4249.html email-thread] from [http://lists.openembedded.org/pipermail/openembedded-devel/ openembedded-devel@lists.openembedded.org] and subsequent dicussions.
+
= Naming Conventions =
  
== Hyphens ==
+
* Generally, name recipes <packagename>_<version>.bb
+
* See also [[Versioning Policy]]
Our current policy is:
 
  
* PN may contain hypens
+
= Format Guidelines =
* PV should avoid containing hypens
 
* PR '''must not''' contain hyphens
 
  
It is a common misconception that hyphens are not allowed in PV. Looking at packages/linux shows they can be used but extreme caution is recommended (see pitfalls below). They wouldn't be allowed under Debian rules if PR wasn't specificed but since OE always sets PR by default, hyphens are allowed by default.
+
<ul>
             
+
<li>The correct spacing for a variable assignment is FOO = "BAR".</li>
== Date based packages ==
+
<li>Use quotes on the right hand side of assignments: FOO = "BAR"</li>
 +
<li>No spaces are allowed behind the line continuation symbol (\)</li>
 +
<li>Comments are allowed using the '#' character at the beginning of a line, but you cannot use a comment within a continuation.</li>
 +
<li>Use spaces for indentation as developers tends to use different amount of spaces per one tab.</li>
 +
<li>Python functions must be four space indented - no tabs.</li>
 +
<li>Shell functions in OE-Core usually use tabs for indentation, but other layers usually use consistent indentation with 4 spaces (in shell functions, python functions and for indentation of multi-line variables)</li>
 +
<li>Splitting of long list values (such as SRC_URI) over multiple lines, and indenting the second line onwards is desirable:<ul>
 +
  <li>For values split over multiple lines, indent successive lines up to the level of the start of the value on the first line, and have the final closing quote on its own line:<pre>
 +
FOO = "\
 +
      bar \
 +
      done \
 +
      "</pre></li>
 +
  <li>Some layers prefer to use four-space indentation on sucessive lines and prefer the closing quote as the first character:<pre>
 +
FOO = "\
 +
    bar \
 +
    done \
 +
"</pre></li></ul>
 +
</li>
 +
</ul>
  
The current policy is to use the format PV = "1.2+scmYYYYMMDD".
+
= Style Guidelines =
  
* cvs packages should use <latest released version>+cvs<date>, e.g. foo_1.3+cvs20051106
+
== Additional Metadata ==
* svn packages should use <latest released version>+svn<date>, e.g. foo_1.3+svn20051106
 
  
== Pitfalls ==
+
All recipes should aim to specify the following fields where possible:
  
Prerelease packages such as
+
* '''SUMMARY''': should give an 80 character/one line maximum short summary of the description.
 +
* '''DESCRIPTION''': should give an extended (possibly multi-line) description of what recipe provides. Note that by default, DESCRIPTION is set to the value of SUMMARY, so if you only have a short description to use, just set SUMMARY.
 +
* '''HOMEPAGE''': upstream website
 +
* '''BUGTRACKER''': upstream bug tracker URL if available
 +
* '''LICENSE''': must be accurate and list all applicable licenses.
 +
* '''LIC_FILES_CHKSUM''': should if at all possible point to one or more files within the upstream source in order to detect changes on upgrade
  
* foo_2.4.4rc2
+
For details on how to set LICENSE and LIC_FILES_CHKSUM, see [[Recipe License Fields]].
* foo_2.4.4b1
 
* foo_2.4.4-git5
 
* foo_2.4.4-pre1
 
  
cause a lot of trouble with package managers when ''foo_2.4.4'' gets released. So we should use the following:
+
== do_install ==
  
* foo_2.4.3+2.4.4rc2
+
* Use <code>oe_runmake install</code> (which runs <code>make install</code>) where at all possible
 +
* Don't use ''cp'' to put files into staging or destination directories, use ''install'' instead.
 +
* Don't use ''mkdir'' to create destination directories, use ''install -d'' instead.
 +
* Modify files after installing them, not before (to ensure do_install can be re-executed)
 +
* Use rm -f to avoid failure in case do_install is re-executed
 +
 
 +
== Ordering and grouping ==
 +
 
 +
* Put the ''inherit'' declaration after the initial variables are set up and before any custom ''do_'' routines. This is flexible as ordering is often important.
 +
* If you define custom ''do_'' routines, keep them in the order of the tasks being executed, that is:
 +
** do_fetch
 +
** do_unpack
 +
** do_patch
 +
** do_configure
 +
** do_compile
 +
** do_install
 +
** do_populate_sysroot
 +
** do_package
 +
 
 +
* Recipes should follow a roughly standard variable / function order, based on the logical order fields are needed and tasks are executed:
 +
** SUMMARY
 +
** DESCRIPTION
 +
** AUTHOR
 +
** HOMEPAGE
 +
** SECTION
 +
** LICENSE
 +
** LIC_FILES_CHKSUM
 +
** DEPENDS
 +
** PROVIDES
 +
** PV
 +
** SRC_URI
 +
** SRCREV
 +
** S
 +
** inherit ...
 +
** build class specific variables, i.e. EXTRA_QMAKEVARS_POST
 +
** task overrides, i.e. do_configure
 +
** PACKAGE_ARCH
 +
** PACKAGES
 +
** FILES
 +
** RDEPENDS
 +
** RRECOMMENDS
 +
** RSUGGESTS
 +
** RPROVIDES
 +
** RCONFLICTS
 +
 
 +
* Package related variables for a given package are often grouped together for clarity.
 +
 
 +
== Version fields ==
 +
 
 +
* Handling PR (revision):
 +
** Remove PR when PV (i.e. the recipe version) increases
 +
** Preserve existing PR values otherwise (or the overall version will decrease which is not desirable)
 +
** Do not specify PR in new recipes
 +
** No need to increase existing values of PR unless there is a change that would not otherwise trigger the appropriate rebuild/re-execution (very rare)
 +
* If the PV changes in such a way that it does not increase with respect to the previous value, you need to increase PE (or set it to "1" if not already set) to ensure package managers will upgrade it correctly
 +
 
 +
See also [[Versioning Policy]]
 +
 
 +
== Patches ==
 +
 
 +
Patches (i.e. patch files which are referred to in SRC_URI within recipes) should have a header containing information about where they came from and why they are required. This makes examining patches in future and sending appropriate ones upstream much easier.
 +
 
 +
For further information on patch header formatting, see [[Commit Patch Message Guidelines]].
 +
 
 +
== Misc ==
 +
 
 +
* Use BBCLASSEXTEND where possible instead of separate -native and -nativesdk recipes
 +
* Avoid custom do_configure for autotooled projects - the default provided by autotools.bbclass should work for almost all cases
 +
* pkgconfig .pc files should be correct and not need manual mangling
 +
 
 +
= Style Checking tools =
 +
 
 +
You can run contrib/oe-stylize.py from meta-oe on your recipes before submitting them; however it is not necessarily up-to-date with all current style conventions. This page should be considered the canonical reference.
 +
 
 +
= Example Recipe =
 +
 
 +
<pre>
 +
SUMMARY = "X11 Code Viewer"
 +
DESCRIPTION = "Allow viewing of X11 code in a fancy way which allows easier \
 +
              and more productive X11 programming"
 +
AUTHOR = "John Bazz <john.bazz@example.org>"
 +
HOMEPAGE = "http://www.example.org/xcv/"
 +
SECTION = "x11/applications"
 +
LICENSE = "GPL-2.0"
 +
DEPENDS = "libsm libx11 libxext libxaw"
 +
PV = "0.9+git${SRCPV}"
 +
 
 +
# upstream does not yet publish any release so we have to fetch last working version from GIT
 +
SRCREV = "6a5e79ae8a0f4a273a603b2df1742972510d3d8f"
 +
SRC_URI = "git://xcv.example.org/xcv;protocol=http \
 +
          file://toolbar-resize-fix.patch"
 +
 
 +
S = "${WORKDIR}/xcv/"
 +
 
 +
inherit autotools
 +
 
 +
do_configure_prepend() {
 +
    rm ${S}/aclocal.m4
 +
}
 +
 
 +
do_install() {
 +
    install -d ${D}${bindir}
 +
    install -d ${D}${mandir}/man1
 +
 
 +
    install -m 0755 xcv ${D}${bindir}/ 
 +
    install -m 0644 xcv.1.gz ${D}${mandir}/man1/
 +
}
 +
 
 +
RDEPENDS_${PN} = "shared-mime-info"
 +
RRECOMMENDS_${PN} = "ctags"
 +
RCONFLICTS_${PN} = "xcv2"
 +
</pre>
  
 
[[Category:Policy]]
 
[[Category:Policy]]

Revision as of 12:59, 5 June 2014

Motivation

As with most style guides, the idea here is to have a consistent format and look so that when someone new comes to the scene they can learn quickly and get involved. This also helps reviewers and maintainers understand what changes are being made by contributors.

Naming Conventions

Format Guidelines

  • The correct spacing for a variable assignment is FOO = "BAR".
  • Use quotes on the right hand side of assignments: FOO = "BAR"
  • No spaces are allowed behind the line continuation symbol (\)
  • Comments are allowed using the '#' character at the beginning of a line, but you cannot use a comment within a continuation.
  • Use spaces for indentation as developers tends to use different amount of spaces per one tab.
  • Python functions must be four space indented - no tabs.
  • Shell functions in OE-Core usually use tabs for indentation, but other layers usually use consistent indentation with 4 spaces (in shell functions, python functions and for indentation of multi-line variables)
  • Splitting of long list values (such as SRC_URI) over multiple lines, and indenting the second line onwards is desirable:
    • For values split over multiple lines, indent successive lines up to the level of the start of the value on the first line, and have the final closing quote on its own line:
      FOO = "\
             bar \
             done \
             "
    • Some layers prefer to use four-space indentation on sucessive lines and prefer the closing quote as the first character:
      FOO = "\
          bar \
          done \
      "

Style Guidelines

Additional Metadata

All recipes should aim to specify the following fields where possible:

  • SUMMARY: should give an 80 character/one line maximum short summary of the description.
  • DESCRIPTION: should give an extended (possibly multi-line) description of what recipe provides. Note that by default, DESCRIPTION is set to the value of SUMMARY, so if you only have a short description to use, just set SUMMARY.
  • HOMEPAGE: upstream website
  • BUGTRACKER: upstream bug tracker URL if available
  • LICENSE: must be accurate and list all applicable licenses.
  • LIC_FILES_CHKSUM: should if at all possible point to one or more files within the upstream source in order to detect changes on upgrade

For details on how to set LICENSE and LIC_FILES_CHKSUM, see Recipe License Fields.

do_install

  • Use oe_runmake install (which runs make install) where at all possible
  • Don't use cp to put files into staging or destination directories, use install instead.
  • Don't use mkdir to create destination directories, use install -d instead.
  • Modify files after installing them, not before (to ensure do_install can be re-executed)
  • Use rm -f to avoid failure in case do_install is re-executed

Ordering and grouping

  • Put the inherit declaration after the initial variables are set up and before any custom do_ routines. This is flexible as ordering is often important.
  • If you define custom do_ routines, keep them in the order of the tasks being executed, that is:
    • do_fetch
    • do_unpack
    • do_patch
    • do_configure
    • do_compile
    • do_install
    • do_populate_sysroot
    • do_package
  • Recipes should follow a roughly standard variable / function order, based on the logical order fields are needed and tasks are executed:
    • SUMMARY
    • DESCRIPTION
    • AUTHOR
    • HOMEPAGE
    • SECTION
    • LICENSE
    • LIC_FILES_CHKSUM
    • DEPENDS
    • PROVIDES
    • PV
    • SRC_URI
    • SRCREV
    • S
    • inherit ...
    • build class specific variables, i.e. EXTRA_QMAKEVARS_POST
    • task overrides, i.e. do_configure
    • PACKAGE_ARCH
    • PACKAGES
    • FILES
    • RDEPENDS
    • RRECOMMENDS
    • RSUGGESTS
    • RPROVIDES
    • RCONFLICTS
  • Package related variables for a given package are often grouped together for clarity.

Version fields

  • Handling PR (revision):
    • Remove PR when PV (i.e. the recipe version) increases
    • Preserve existing PR values otherwise (or the overall version will decrease which is not desirable)
    • Do not specify PR in new recipes
    • No need to increase existing values of PR unless there is a change that would not otherwise trigger the appropriate rebuild/re-execution (very rare)
  • If the PV changes in such a way that it does not increase with respect to the previous value, you need to increase PE (or set it to "1" if not already set) to ensure package managers will upgrade it correctly

See also Versioning Policy

Patches

Patches (i.e. patch files which are referred to in SRC_URI within recipes) should have a header containing information about where they came from and why they are required. This makes examining patches in future and sending appropriate ones upstream much easier.

For further information on patch header formatting, see Commit Patch Message Guidelines.

Misc

  • Use BBCLASSEXTEND where possible instead of separate -native and -nativesdk recipes
  • Avoid custom do_configure for autotooled projects - the default provided by autotools.bbclass should work for almost all cases
  • pkgconfig .pc files should be correct and not need manual mangling

Style Checking tools

You can run contrib/oe-stylize.py from meta-oe on your recipes before submitting them; however it is not necessarily up-to-date with all current style conventions. This page should be considered the canonical reference.

Example Recipe

SUMMARY = "X11 Code Viewer"
DESCRIPTION = "Allow viewing of X11 code in a fancy way which allows easier \
               and more productive X11 programming"
AUTHOR = "John Bazz <john.bazz@example.org>"
HOMEPAGE = "http://www.example.org/xcv/"
SECTION = "x11/applications"
LICENSE = "GPL-2.0"
DEPENDS = "libsm libx11 libxext libxaw"
PV = "0.9+git${SRCPV}"

# upstream does not yet publish any release so we have to fetch last working version from GIT
SRCREV = "6a5e79ae8a0f4a273a603b2df1742972510d3d8f"
SRC_URI = "git://xcv.example.org/xcv;protocol=http \
           file://toolbar-resize-fix.patch"

S = "${WORKDIR}/xcv/"

inherit autotools

do_configure_prepend() {
    rm ${S}/aclocal.m4
}

do_install() {
    install -d ${D}${bindir}
    install -d ${D}${mandir}/man1

    install -m 0755 xcv ${D}${bindir}/   
    install -m 0644 xcv.1.gz ${D}${mandir}/man1/
}

RDEPENDS_${PN} = "shared-mime-info"
RRECOMMENDS_${PN} = "ctags"
RCONFLICTS_${PN} = "xcv2"