Recipe & Patch Style Guide

From Yocto Project
Revision as of 19:23, 7 April 2011 by SaulWold (talk | contribs) (Created page with '= Motivation = As with most style guides, the idea here is to have a consistent format and look so that when someone new comes to the scene they can learn quickly and get involv…')
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Motivation

As with most style guides, the idea here is to have a consistent format and look so that when someone new comes to the scene they can learn quickly and get involved. This will also help the reviewers and maintainers understand what changes are being made by contributors.

Recipes file format and style

  • Consistent whitespace throughout the file
  • File follows a roughly standard variable order
  • Patches are all documented
  • No legacy staging
  • Use BBCLASSEXTEND where possible instead of -native versions
  • No -sdk or -nativesdk packages, use BBCLASSEXTEND
  • pkgconfig .pc files are correct and don't need manual mangling
  • No custom do_configure for autotooled projects
  • Uses "make install" where at all possible
    • if recipe installs can we patch make install and push upstream

Additional MetaData

Metadata to add into Recipes, when we start the update process or for non-changing packages we should add this data now.

  • DESCRIPTION
  • HOMEPAGE
  • BUGTRACKER
  • LICENSE
  • LIC_FILES_CHKSUM
  • DISTRO_PN_ALIAS

Recipe File Rules

BitBake Overrides

We will create a set of BitBake Overides for DEPENDENCY_CHECK and RECIPE_STATUS with defaults of "not done" and as recipes are checked the appropriate file will be updated to contain the status, these files will then be used to generate the spreadsheet / progress report so we know where we stand.

There're also additional overrides we'd like to track for project progress:

  • RECIPE_LATEST_VERSION_pn+<packagename>="x.y.z"; Override for missing or inaccurate version information from kevin’s script
  • RECIPE_PATCH_pn+<packagename>+<patchname>="description/status"; Description about a patch's purpose and its status whether necessary to keep
  • RECIPE_COMMENTS_pn+<packagename>="comments"; Contain micellaneous useful information about the package
  • RECIPE_TIME_BETWEEN_LAST_TWO_RELEASES_pn+<packagename>="5 months"; Activity tracking information
  • RECIPE_LATEST_RELEASE_DATE_pn+<packagename>="2010/03/03"; Last release date
  • RECIPE_INTEL_SECTION_pn="base"; section info defined by distro team, which may replace current SECTION later


Licence Updates

There are 2 parts to the licensing update that needs to happen in the recipe files, first is the LICENSE metadata, and the second is the License Verification with LIC_FILE_CHKSUM

LICENSE

  • GPLv2, GPLv2+, GPLv3, GPLv3+, LGPLv2,
  • LGPLv2+, LGPLv2.1, LGPLv2.1+, LGPLv3, LGPLv3+
  • Dual license: GPLv2 | BSD
  • Multiple licenses: GPLv3+ & LGPLv2.1+
  • Name Sub-Packages with different Licenses
    • LICENSE = "LGPLv2.1 & GPLv3+"
    • LICENSE_libidn = "LGPLv2.1"
    • LICENSE_libidn-tests = "GPLv3+"

LIC_FILES_CHKSUM

If a LICENSE or COPYING file exists, use it along with the license text from one source (header file prefered), if there is inconsistencies (multi versions, different licenses) report this information and then we can determine what the next steps should be to reconcile. Next steps include internal review and working with upstream community to reconclie licenses.

More information for using the LIC_FILES_CHKSUM variable
  • How to specify the LIC_FILES_CHKSUM variable:
LIC_FILES_CHKSUM = “file://COPYING;md5=xxxx \
                    file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
                    file://licfile2.txt;endline=50;md5=zzzz \
                    ...“
  • Explanation:

This file lists all the files with the text of licenses for the source code. It is also possible to specify on which line the license text starts and on which line it ends within that file using the “beginline” & “endline” parameters. If the “beginline” parameter is not specified then license text begins from the 1st line is assumed. Similarly if “endline” parameter is not specified then the license text ends at the last line in the file is assumed. So if a file contains only licensing information, then there is no need to specify “beginline” & “endline” parameters.

The “md5” parameter stores the md5 checksum of the license text. So if the license text changes in any way, it’s md5 sum will differ and will not match with the previously stored md5 checksum. This mismatch will trigger build failure, notifying developer about the license text md5 mismatch, and allowing the developer to review the license text changes. Also note that if md5 checksum is not matched while building, the correct md5 checksum is printed in the build log.

There is no limit on how many files can be specified. But generally every project would need specifying of just one or two files for license tracking. Many projects would have a “COPYING” file which will store all the license information for all the source code files. If the “COPYING” file is valid then tracking only that file would be enough.

  • Tips on using the LIC_FILE_CHKSUM variable:

1. if you specify empty or invalid “md5” parameter; then while building the package, bitbake will give md5 not matched error, and also show the correct “md5” parameter value in the build log

2. If the whole file contains only license text, then there is no need to specify “beginline” and “endline” parameters.


Shamelessly taken from OE

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.

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_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"
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.

Retrieved from "https://wiki.yoctoproject.org/wiki/index.php?title=Recipe_%26_Patch_Style_Guide&oldid=1183"