|
|
| (10 intermediate revisions by 5 users not shown) |
| Line 1: |
Line 1: |
| = Motivation =
| | '''Please see the [http://openembedded.org/wiki/Styleguide OpenEmbedded style guidelines]'''. |
| | |
| 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 =
| |
| | |
| * http://wiki.openembedded.net/index.php/Styleguide
| |
| | |
| * 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
| |
|
| |
| | |
| | |
| === 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 =
| |
| | |
| [[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.
| |
| | |
| = 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 =
| |
| | |
| <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]]
| |
