Difference between revisions of "Styleguide"

From Openembedded.org
Jump to: navigation, search
m (Version policy for OE recipes)
(Example Recipe)
(14 intermediate revisions by 8 users not shown)
Line 1: Line 1:
= Version policy for OE recipes =
+
= Naming Conventions =
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 from [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version Debian] (and is hence compatible with ipkg).  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.
 
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.
+
[[Versioning Policy|Use $packagename_$version.bb]]
  
== Hyphens ==
+
= Format Guidelines =
 
Our current policy is:
 
  
* PN may contain hypens
+
* No spaces are allowed behind the line continuation symbol
* PV should avoid containing hypens
+
* The correct spacing for a variable is FOO = "BAR".
* PR '''must not''' contain hyphens
+
* Use quotes on the right hand side of assignments: FOO = "BAR"
 +
* Comments inside bb files are allowed using the '#' character at the beginning of a line.
 +
* Use spaces for indentation as developers tends to use different amount of spaces per one tab.
 +
* Indentation of multiline variables such as SRC_URI is desireable.
 +
* Python functions should be four space indented, no tabs.
 +
* Shell functions are usually tab character indented.
  
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.
+
= Style Checking tools =
             
 
== Date based packages ==
 
  
The current policy is to use the format PV = "1.2+scmYYYYMMDD".
+
Please run ./contrib/oe-stylize.py on your recipes before submitting them.
  
* cvs packages should use <latest released version>+cvs<date>, e.g. foo_1.3+cvs20051106
+
= Style Guidelines =
* svn packages should use <latest released version>+svn<date>, e.g. foo_1.3+svn20051106
 
  
== Pitfalls ==
+
* 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
  
Prerelease packages such as
+
* 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.
  
* foo_2.4.4rc2
+
* There is a standard set of variables often found in a .bb file and the preferred order (to make the file easily readable to seasoned developers) is
* foo_2.4.4b1
+
** DESCRIPTION
* foo_2.4.4-git5
+
** AUTHOR
* foo_2.4.4-pre1
+
** HOMEPAGE
 +
** SECTION
 +
** PRIORITY
 +
** LICENSE
 +
** DEPENDS
 +
** RDEPENDS
 +
** RRECOMMENDS
 +
** RSUGGESTS
 +
** PROVIDES
 +
** RPROVIDES
 +
** RCONFLICTS
 +
** SRCDATE
 +
** PV
 +
** PR
 +
** SRC_URI
 +
** S
 +
** inherit ...
 +
** build class specific variables, i.e. EXTRA_QMAKEVARS_POST
 +
** task overrides, i.e. do_configure
 +
** PACKAGE_ARCH
 +
** PACKAGES
 +
** FILES
  
cause a lot of trouble with package managers when ''foo_2.4.4'' gets released. So we should use the following:
+
* Package related variables for a given package are often grouped together for clarity.
  
* foo_2.4.3+2.4.4rc2
+
= 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>
 +
 +
= PR variables with recipes that use INC files =
 +
When recipe include files are used, the PR handling gets kind of messy.  Its a pain to have to audit the PR in all the dependent recipes when you change something in an INC file.  We usually use the following solution:
 +
 +
<pre>
 +
recipe: PR = "${INC_PR}.1"
 +
 +
inc file: INC_PR = "r1"
 +
</pre>
 +
 +
When converting existing recipes to use INC_PR, set the initial INC_PR to the maximum of the current PRs.
 
[[Category:Policy]]
 
[[Category:Policy]]
 +
 +
Also see https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide

Revision as of 19:42, 14 May 2013

Naming Conventions

Use $packagename_$version.bb

Format Guidelines

  • No spaces are allowed behind the line continuation symbol
  • The correct spacing for a variable is FOO = "BAR".
  • Use quotes on the right hand side of assignments: FOO = "BAR"
  • Comments inside bb files are allowed using the '#' character at the beginning of a line.
  • Use spaces for indentation as developers tends to use different amount of spaces per one tab.
  • Indentation of multiline variables such as SRC_URI is desireable.
  • Python functions should be four space indented, no tabs.
  • Shell functions are usually tab character indented.

Style Checking tools

Please run ./contrib/oe-stylize.py on your recipes before submitting them.

Style Guidelines

  • 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
  • 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.
  • There is a standard set of variables often found in a .bb file and the preferred order (to make the file easily readable to seasoned developers) is
    • DESCRIPTION
    • AUTHOR
    • HOMEPAGE
    • SECTION
    • PRIORITY
    • LICENSE
    • DEPENDS
    • RDEPENDS
    • RRECOMMENDS
    • RSUGGESTS
    • PROVIDES
    • RPROVIDES
    • RCONFLICTS
    • SRCDATE
    • PV
    • PR
    • SRC_URI
    • S
    • inherit ...
    • build class specific variables, i.e. EXTRA_QMAKEVARS_POST
    • task overrides, i.e. do_configure
    • PACKAGE_ARCH
    • PACKAGES
    • FILES
  • Package related variables for a given package are often grouped together for clarity.

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"

PR variables with recipes that use INC files

When recipe include files are used, the PR handling gets kind of messy. Its a pain to have to audit the PR in all the dependent recipes when you change something in an INC file. We usually use the following solution:

recipe: PR = "${INC_PR}.1"

inc file: INC_PR = "r1"

When converting existing recipes to use INC_PR, set the initial INC_PR to the maximum of the current PRs.

Also see https://wiki.yoctoproject.org/wiki/Recipe_%26_Patch_Style_Guide