Difference between revisions of "Styleguide"
From Openembedded.org
m (→Version policy for OE recipes) |
PaulEggleton (talk | contribs) (Remove reference to PRIORITY) |
||
(15 intermediate revisions by 9 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 | ||
+ | ** 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> | ||
+ | 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 08:53, 11 October 2013
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
- 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