Difference between revisions of "Styleguide"

From Openembedded.org
Jump to: navigation, search
(PR variables with recipes that use INC files)
(PR variables with recipes that use INC files)
(10 intermediate revisions by 6 users not shown)
Line 6: Line 6:
  
 
* No spaces are allowed behind the line continuation symbol
 
* 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"
 
* 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.
 
* Comments inside bb files are allowed using the '#' character at the beginning of a line.
* Use either tabs '''or''' spaces for indentation, but don't mix the two in the same file
+
* Use spaces for indentation as developers tends to use different amount of spaces per one tab.
* The correct spacing for a variable is FOO = "BAR".
+
 
* Indentation of multiline variables such as SRC_URI is desireable.
 
* Indentation of multiline variables such as SRC_URI is desireable.
 +
* Python functions should be four space indented, no tabs.
 +
* Shell functions in OE-Core are usually using tabs for indentation, but other layers usually use consistent indentation with 4 spaces (in shell task, python tasks and for indentation of multi-line variables)
 +
* Closing quote for multiline variables is preferably first character on its own line, when the first line is long, then it's better to start with "\ and put first value on 2nd line
 +
  FOO = "\
 +
      bar \
 +
      done \
 +
  "
  
 
= Style Checking tools =
 
= Style Checking tools =
 +
 
Please run ./contrib/oe-stylize.py on your recipes before submitting them.
 
Please run ./contrib/oe-stylize.py on your recipes before submitting them.
  
Line 18: Line 26:
  
 
* 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.
 
* 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:
 
* If you define custom ''do_'' routines, keep them in the order of the tasks being executed, that is:
 
** do_fetch
 
** do_fetch
Line 26: Line 33:
 
** do_compile
 
** do_compile
 
** do_install
 
** do_install
 +
** do_populate_sysroot
 
** do_package
 
** do_package
** do_stage
 
  
 
* Don't use ''cp'' to put files into staging or destination directories, use ''install'' instead.
 
* Don't use ''cp'' to put files into staging or destination directories, use ''install'' instead.
Line 37: Line 44:
 
** HOMEPAGE
 
** HOMEPAGE
 
** SECTION
 
** SECTION
** PRIORITY
 
 
** LICENSE
 
** LICENSE
 
** DEPENDS
 
** DEPENDS
Line 57: Line 63:
 
** PACKAGES
 
** PACKAGES
 
** FILES
 
** FILES
 +
 +
* Package related variables for a given package are often grouped together for clarity.
  
 
= Example Recipe =
 
= Example Recipe =
  
 
<pre>
 
<pre>
DESCRIPTION = "X11 Code Viewer"
+
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>"
 
AUTHOR = "John Bazz <john.bazz@example.org>"
 
HOMEPAGE = "http://www.example.org/xcv/"
 
HOMEPAGE = "http://www.example.org/xcv/"
 
SECTION = "x11/applications"
 
SECTION = "x11/applications"
PRIORITY = "optional"
+
LICENSE = "GPL-2.0"
LICENSE = "GPLv2"
+
 
DEPENDS = "libsm libx11 libxext libxaw"
 
DEPENDS = "libsm libx11 libxext libxaw"
RDEPENDS = "shared-mime-info"
+
PV = "0.9+git${SRCPV}"
RRECOMMENDS = "ctags"
+
RCONFLICTS = "xcv2"
+
SRCDATE = "20060815"
+
PV = "0.0+cvs${SRCDATE}"
+
PR = "r5"
+
  
# upstream does not yet publish any release so we have to fetch last working version from CVS
+
# upstream does not yet publish any release so we have to fetch last working version from GIT
SRC_URI = "cvs://anonymous@xcv.example.org/cvsroot/xcv;module=xcv \
+
SRCREV = "6a5e79ae8a0f4a273a603b2df1742972510d3d8f"
           file://toolbar-resize-fix.patch;patch=1"
+
SRC_URI = "git://xcv.example.org/xcv;protocol=http \
 +
           file://toolbar-resize-fix.patch"
  
 
S = "${WORKDIR}/xcv/"
 
S = "${WORKDIR}/xcv/"
Line 94: Line 99:
 
     install -m 0644 xcv.1.gz ${D}${mandir}/man1/
 
     install -m 0644 xcv.1.gz ${D}${mandir}/man1/
 
}
 
}
 +
 +
RDEPENDS_${PN} = "shared-mime-info"
 +
RRECOMMENDS_${PN} = "ctags"
 +
RCONFLICTS_${PN} = "xcv2"
 
</pre>
 
</pre>
  
 
= PR variables with recipes that use INC files =  
 
= 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.  The following is a proposed solution:
+
 
 +
This is obsolete, now we're not using PR variables and when you're increasing PV/PE it's better to drop PR variable.
 +
 
 +
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>
 
<pre>
Line 105: Line 117:
 
</pre>
 
</pre>
  
When converting existing recipes to use INC_PR, set the initial INC_PR to the maximum of the current PR's.
+
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 14:38, 28 February 2014

Contents

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 in OE-Core are usually using tabs for indentation, but other layers usually use consistent indentation with 4 spaces (in shell task, python tasks and for indentation of multi-line variables)
  • Closing quote for multiline variables is preferably first character on its own line, when the first line is long, then it's better to start with "\ and put first value on 2nd line
 FOO = "\
     bar \
     done \
 "

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
    • 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

This is obsolete, now we're not using PR variables and when you're increasing PV/PE it's better to drop PR variable.

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

Personal tools
Namespaces

Variants
Actions
Navigation
Categories
OE services
Toolbox