Difference between revisions of "Styleguide"
From Openembedded.org
(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...) |
|||
(14 intermediate revisions by 8 users not shown) | |||
Line 1: | Line 1: | ||
− | = | + | = Naming Conventions = |
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | [[Versioning Policy|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 = | |
− | + | <pre> | |
+ | DESCRIPTION = "X11 Code Viewer" | ||
+ | AUTHOR = "John Bazz <john.bazz@example.org>" | ||
+ | HOMEPAGE = "http://www.example.org/xcv/" | ||
+ | SECTION = "x11/applications" | ||
+ | PRIORITY = "optional" | ||
+ | LICENSE = "GPLv2" | ||
+ | DEPENDS = "libsm libx11 libxext libxaw" | ||
+ | RDEPENDS = "shared-mime-info" | ||
+ | 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 | ||
+ | SRC_URI = "cvs://anonymous@xcv.example.org/cvsroot/xcv;module=xcv \ | ||
+ | file://toolbar-resize-fix.patch;patch=1" | ||
+ | |||
+ | 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/ | ||
+ | } | ||
+ | </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 09:24, 9 October 2012
Contents
Naming Conventions
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
DESCRIPTION = "X11 Code Viewer" AUTHOR = "John Bazz <john.bazz@example.org>" HOMEPAGE = "http://www.example.org/xcv/" SECTION = "x11/applications" PRIORITY = "optional" LICENSE = "GPLv2" DEPENDS = "libsm libx11 libxext libxaw" RDEPENDS = "shared-mime-info" 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 SRC_URI = "cvs://anonymous@xcv.example.org/cvsroot/xcv;module=xcv \ file://toolbar-resize-fix.patch;patch=1" 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/ }
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