Recipe & Patch Style Guide - Revision history

PaulEggleton: Replaced content with "'''Please see the [http://openembedded.org/wiki/Styleguide OpenEmbedded style guidelines]'''."

2014-06-05T11:02:03Z

Replaced content with "'''Please see the [http://openembedded.org/wiki/Styleguide OpenEmbedded style guidelines]'''."

PaulEggleton: Update guide for modern conventions

2014-06-05T09:56:51Z

Update guide for modern conventions

← Older revision		Revision as of 09:56, 5 June 2014
Line 11:		Line 11:

	* Consistent whitespace throughout the file		* Consistent whitespace throughout the file
	* File follows a roughly standard variable order		* File follows a roughly standard variable order (based on the order tasks are executed)
	* Patches are all documented		* Patches are all documented
	* No legacy staging		* Use BBCLASSEXTEND where possible instead of separate -native and -nativesdk recipes
	* 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		* pkgconfig .pc files are correct and don't need manual mangling
	* No custom do_configure for autotooled projects		* No custom do_configure for autotooled projects
	* ~~Uses~~ "make install" where at all possible		* Use "make install" where at all possible
	** if recipe installs can we patch make install and push upstream		** if recipe installs can we patch make install and push upstream

Line 77:		Line 75:

	* 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		* 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
			** SUMMARY
	** DESCRIPTION		** DESCRIPTION
	** AUTHOR		** AUTHOR
Line 121:		Line 120:
	SRCDATE = "20600815"		SRCDATE = "20600815"
	PV = "0.0+cvs${SRCDATE}"		PV = "0.0+cvs${SRCDATE}"
	~~PR = "r5"~~

	# upstream does not yet publish any release so we have to fetch last working version from CVS		# upstream does not yet publish any release so we have to fetch last working version from CVS

Rpjday: "LIC_FILE_CHKSUM" -> "LIC_FILES_CHKSUM"

2012-12-13T13:36:19Z

"LIC_FILE_CHKSUM" -> "LIC_FILES_CHKSUM"

← Older revision		Revision as of 13:36, 13 December 2012
Line 258:		Line 258:
	== License Updates ==		== License 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~~		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_FILES_CHKSUM

	=== LICENSE ===		=== LICENSE ===
Line 287:		Line 287:
	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.		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:		* Tips on using the LIC_FILES_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		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.		2. If the whole file contains only license text, then there is no need to specify “beginline” and “endline” parameters.

PaulEggleton: Some corrections

2012-08-17T14:20:46Z

Some corrections

← Older revision		Revision as of 14:20, 17 August 2012
Line 36:		Line 36:
	recipe provides.		recipe provides.

	SUMMARY should give an 80 character/one line maximum short summary of the description		SUMMARY should give an 80 character/one line maximum short summary of the description.
			Note that by default, DESCRIPTION is set to the value of SUMMARY, so if you only have
			a short description to use, just set SUMMARY.

	== White Space Management ==		== White Space Management ==

Line 43:		Line 46:
	* Indentation of multiline variables such as SRC_URI is desirable.		* Indentation of multiline variables such as SRC_URI is desirable.
	* Most variables such as SRC_URI should use spaces.		* Most variables such as SRC_URI should use spaces.
	* ~~Use~~ spaces for ~~indentation~~ as developers ~~tends~~ to use different amount of spaces per ~~one~~ tab.		* For multiple-line continuations, use spaces for indenting as developers tend to use different amount of spaces per tab.
	* Shell functions should use tabs		* Shell functions should use tabs
	* Python functions ~~should~~ use spaces (4 spaces per indent).		* Python functions must use spaces (4 spaces per indent).
	* No spaces are allowed after the line continuation symbol		* No spaces are allowed after the line continuation symbol
	* Comments inside bb files are allowed using the '#' character at the beginning of a line.		* Comments inside bb files are allowed using the '#' character at the beginning of a line, but you cannot use a comment within a continuation.


Line 148:		Line 151:
	= Patches =		= Patches =

	Patches should contain information about where they came from and why they are required, as the project moves forward, we want to increase the quality of the data that is made available to the community. This can be done in the recipes and also in the patch files in order to understand why the patch exists and to help future maintainer to understand why it is required. The following information covers how to incorporate and manage patches within the meta-data. For details on how to format newly created patches or properly submit existing patches for incorporation, please refer to the [[Contribution_Guidelines]].		Patches (i.e. patch files within the metadata, which are referred to in SRC_URI) should contain information about where they came from and why they are required, as the project moves forward, we want to increase the quality of the data that is made available to the community. This can be done in the recipes and also in the patch files in order to understand why the patch exists and to help future maintainer to understand why it is required. The following information covers how to incorporate and manage patches within the meta-data.

			For details on how to format newly created patches or properly submit existing patches for incorporation, please refer to the '''[[Contribution_Guidelines]]'''.

	== New style patch application ==		== New style patch application ==
Line 267:		Line 272:

	=== LIC_FILES_CHKSUM ===		=== 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.		If a LICENSE or COPYING file exists, use it along with the license text from one source (header file preferred), 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 reconcile licenses.

	* How to specify the LIC_FILES_CHKSUM variable:		* How to specify the LIC_FILES_CHKSUM variable:

Dvhart: Update the patches section to reference the newly created Contribution_Guidelines page.

2011-11-08T22:00:19Z

Update the patches section to reference the newly created Contribution_Guidelines page.

@@ Line 148: / Line 148: @@
 = Patches =
-Patches should contain information about where they came from and why they are required, as the project moves forward, we want to increase the quality of the data that is made available to the community. This can be done in the recipes and also in the patch files in order to understand why the patch exists and to help future maintainer to understand why it is required.
+Patches should contain information about where they came from and why they are required, as the project moves forward, we want to increase the quality of the data that is made available to the community. This can be done in the recipes and also in the patch files in order to understand why the patch exists and to help future maintainer to understand why it is required. The following information covers how to incorporate and manage patches within the meta-data. For details on how to format newly created patches or properly submit existing patches for incorporation, please refer to the [[Contribution_Guidelines]].
 == New style patch application ==
@@ Line 220: / Line 176: @@
 could be changed to:
   file://another.diff
 = License Fields =

Rpurdie: Reorganise page, clear up duplication and provide structure

2011-05-16T17:41:33Z

Reorganise page, clear up duplication and provide structure

Show changes

Rpurdie: /* Style Guidelines */

2011-05-16T17:23:13Z

Style Guidelines

← Older revision		Revision as of 17:23, 16 May 2011
Line 293:		Line 293:

	* Variables related to the same package (*_{PN} and similar) should be kept together and after any PACKAGES definition		* Variables related to the same package (*_{PN} and similar) should be kept together and after any PACKAGES definition
			* Variables operating on packages (R* ones so RDEPENDS, RRECOMMENDS, RPROVIDES and so on as well as variables like ALLOW_EMPTY) should always specify the package they apply to, e.g. RDEPENDS_${PN} = "x", not RDEPENDS = "x"

	= Example Recipe =		= Example Recipe =

Rpurdie: /* Example Recipe */

2011-05-16T17:21:39Z

Example Recipe

← Older revision		Revision as of 17:21, 16 May 2011
Line 304:		Line 304:
	LICENSE = "GPLv2"		LICENSE = "GPLv2"
	DEPENDS = "libsm libx11 libxext libxaw"		DEPENDS = "libsm libx11 libxext libxaw"
	~~RDEPENDS = "shared-mime-info"~~
	~~RRECOMMENDS = "ctags"~~
	~~RCONFLICTS = "xcv2"~~
	SRCDATE = "20060815"		SRCDATE = "20060815"
	PV = "0.0+cvs${SRCDATE}"		PV = "0.0+cvs${SRCDATE}"
Line 330:		Line 327:
	install -m 0644 xcv.1.gz ${D}${mandir}/man1/		install -m 0644 xcv.1.gz ${D}${mandir}/man1/
	}		}

			RDEPENDS_${PN} = "shared-mime-info"
			RRECOMMENDS_${PN} = "ctags"
			RCONFLICTS_${PN} = "xcv2"

	</pre>		</pre>

Rpurdie: /* Format Guidelines */

2011-05-16T17:20:33Z

Format Guidelines

← Older revision		Revision as of 17:20, 16 May 2011
Line 238:		Line 238:
	= Format Guidelines =		= Format Guidelines =

	* No spaces are allowed ~~behind~~ the line continuation symbol		* No spaces are allowed after the line continuation symbol
	* The correct spacing for a variable is FOO = "BAR".		* The correct spacing for a variable is FOO = "BAR".
	* Use quotes on the right hand side of assignments: 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.		* 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.		* 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~~.		* Indentation of multiline variables such as SRC_URI is desirable.

	= Style Checking tools =		= Style Checking tools =

Rpurdie: Add note about package variable grouping

2011-05-16T17:18:20Z

Add note about package variable grouping

← Older revision		Revision as of 17:18, 16 May 2011
Line 273:		Line 273:
	** LICENSE		** LICENSE
	** DEPENDS		** DEPENDS
	** RDEPENDS
	** RRECOMMENDS
	** RSUGGESTS
	** PROVIDES
	** RPROVIDES
	** RCONFLICTS
	** SRCDATE		** SRCDATE
			** SRCREV
	** PV		** PV
	** PR		** PR
Line 290:		Line 285:
	** PACKAGES		** PACKAGES
	** FILES		** FILES
			** RDEPENDS
			** RRECOMMENDS
			** RSUGGESTS
			** PROVIDES
			** RPROVIDES
			** RCONFLICTS

			* Variables related to the same package (*_{PN} and similar) should be kept together and after any PACKAGES definition

	= Example Recipe =		= Example Recipe =