Please note that User Registration has been temporarily disabled due to a recent increase in automated registrations. If anyone needs an account, please request one here: RequestAccount. Thanks for your patience!

Difference between revisions of "Styleguide"

From Openembedded.org
Jump to: navigation, search
m (→‎Version policy for OE recipes)
(scrape the last known-good version off http://web.archive.org/web/20070302230526/http://www.openembedded.org/node/46/edit It's cumbersome. ~curse the one who deleted access to the old website)
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
+
* Use quotes on the right hand side of assignments: FOO = "BAR"
−
* PR '''must not''' contain hyphens
+
* 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
 +
* The correct spacing for a variable is FOO = "BAR".
 +
* Indentation of multiline variables such as SRC_URI is desireable.
  
−
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 Guidelines =
−
             
+
−
== Date based packages ==
+
  
−
The current policy is to use the format PV = "1.2+scmYYYYMMDD".
+
* 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.
  
−
* cvs packages should use <latest released version>+cvs<date>, e.g. foo_1.3+cvs20051106
+
* If you define custom ''do_'' routines, keep them in the order of the tasks being executed, that is:
−
* svn packages should use <latest released version>+svn<date>, e.g. foo_1.3+svn20051106
+
** do_fetch
 +
** do_unpack
 +
** do_patch
 +
** do_configure
 +
** do_compile
 +
** do_install
 +
** do_package
 +
** do_stage
  
−
== Pitfalls ==
+
* 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.
  
−
Prerelease packages such as
+
* 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
  
−
* foo_2.4.4rc2
+
= Example Recipe =
−
* 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:
+
<pre>
 +
DESCRIPTION = "X11 Code Viewer"
 +
AUTHOR = "John Bazz <john.bazz@example.org>"
 +
HOMEPAGE = "http://www.example.org/xcv/"
 +
SECTION = "x11/applications"
 +
PRIORITY = "optional"
 +
MAINTAINER = "Joe Foobar <joe.foobar@example.org"
 +
LICENSE = "GPLv2"
 +
DEPENDS = "libsm libx11 libxext libxaw"
 +
RDEPENDS = "shared-mime-info"
 +
RRECOMMENTS = "ctags"
 +
RCONFLICTS = "xcv2"
 +
SRCDATE = "20060815"
 +
PV = "0.0+cvs${SRCDATE}"
 +
PR = "r5"
  
−
* foo_2.4.3+2.4.4rc2
+
# 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"
  
−
[[Category:Policy]]
+
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>

Revision as of 01:27, 28 July 2008

Contents

Naming Conventions

Use $packagename_$version.bb

Format Guidelines

  • No spaces are allowed behind the line continuation symbol
  • 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 either tabs or spaces for indentation, but don't mix the two in the same file
  • The correct spacing for a variable is FOO = "BAR".
  • Indentation of multiline variables such as SRC_URI is desireable.

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

Example Recipe 

DESCRIPTION = "X11 Code Viewer"
AUTHOR = "John Bazz <john.bazz@example.org>"
HOMEPAGE = "http://www.example.org/xcv/"
SECTION = "x11/applications"
PRIORITY = "optional"
MAINTAINER = "Joe Foobar <joe.foobar@example.org"
LICENSE = "GPLv2"
DEPENDS = "libsm libx11 libxext libxaw"
RDEPENDS = "shared-mime-info"
RRECOMMENTS = "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/
}
Retrieved from "http://openembedded.org/index.php?title=Styleguide&oldid=354"
Personal tools
Namespaces

Variants
Actions
Navigation
Categories
OE services
Toolbox