Patchwork [core,4/5] recipe-guide.txt: A chapter describing how to create recipes

login
register
mail settings
Submitter kim.hansen@prevas.dk
Date Nov. 11, 2013, 2:25 p.m.
Message ID <1384179914-16049-4-git-send-email-kim.hansen@prevas.dk>
Download mbox | patch
Permalink /patch/290309/
State Changes Requested
Delegated to: Esben Haabendal
Headers show

Comments

kim.hansen@prevas.dk - Nov. 11, 2013, 2:25 p.m.
From: Kim Højgaard-Hansen <kiho@prevas.dk>

---
 doc/recipe-guide.txt | 247 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 247 insertions(+)
 create mode 100644 doc/recipe-guide.txt
Esben Haabendal - Nov. 27, 2013, 5:17 p.m.
> From: Kim Højgaard-Hansen <kiho@prevas.dk>
>
> ---
>  doc/recipe-guide.txt | 247 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 247 insertions(+)
>  create mode 100644 doc/recipe-guide.txt
>
> diff --git a/doc/recipe-guide.txt b/doc/recipe-guide.txt
> new file mode 100644
> index 0000000..f311d28
> --- /dev/null
> +++ b/doc/recipe-guide.txt
> @@ -0,0 +1,247 @@
> +// -*- Doc -*-
> +
> +// This is part of the OE-lite Developers Handbook
> +// Copyright (C) 2013
> +//   Kim Højgaard-Hansen <kimrhh@gmail.com>
> +
> +
> +Recipe format
> +=============
> +
> +This chapter covers how to create OE-lite recipes for building new software.
> +
> +What is a recipe
> +----------------
> +
> +An OE-lite recipe is a file with a recipe for building a piece of software
> +for OE-lite. Recipe files are located in the recipe directory in oe-lite
> +repositories and have the .oe file extension. The file contains source code
> +using the OE-lite recipe syntax which is a combination of Python and Shell
> +programming. The filename specifies the name of the recipe and optionally
> +recipe version as "name_version.oe" e.g.:
> +
> +-----
> +lua_5.2.1.oe
> +-----
> +
> +Allowed recipe names: `[a-zA-Z][a-zA-Z0-9\-]*`
> +
> +Allowed recipe versions: `[0-9\.]*`
> +
> +Recipe Metadata
> +---------------
> +
> +A recipe can define a number of metadata variables which is used to build and
> +describe the software. Variables can be assigned using the OE-lite
> +xref:_assignment_operators[assignment operators].
> +
> +.DESCRIPTION
> +Required::
> +	String specifying a description of the software the recipe will build.
> +	A description can be longer than SUMMARY.
> +
> +.Example
> +[source,sh]
> +----------
> +DESCRIPTION="Foo is an application that allows users to do bar much easier.
> +             than baz.
> +             
> +             It is a very flexible tool that with support for both x,y and z"
> +----------
> +
> +.SUMMARY
> +Optional::
> +	String specifying a short description of the software the recipe will
> +	build.
> +
> +.Example
> +[source,sh]
> +-----------
> +SUMMARY="Foo is a library for doing foo stuff"
> +-----------
> +
> +.LICENCE
> +Required::
> +	String specifying the licence(s) of the software the recipe will build.
> +	Each licence is seperated by whitespace.
> +
> +.Example
> +[source,sh]
> +----------
> +LICENCE="GPL-2 MIT"
> +----------
> +
> +.HOMEPAGE
> +Optional::
> +	String specifying the homepage for the software the recipe builds.
> +
> +.Example
> +[source,sh]
> +-----------
> +HOMEPAGE="http://www.greatproject.org/"
> +-----------
> +
> +.SRC_URI
> +Optional::
> +	A list of source files needed to build the software. Entries are
> +	separated by whitespace. A source file can be either local or remote.
> +	For remote files a protocol specifies how the file should be fetched
> +	using: `protocol://file` +
> +	See xref:_fetch_protocols[fetch protocols] for a list of supported
> +	protocols and how they should be used.
> +
> +.Example
> +[source,sh]
> +-----------
> +SRC_URI="http://www.foobar.org/pub/baz.tar.gz"
> +-----------
> +
> +.RECIPE_TYPES
> +Optional::
> +	String specifying what targets the software is going to be built for.
> +	Possible values are:
> +	native:::
> +		Build for the host/build machine
> +	sdk:::
> +		Build for the target SDK
> +	machine:::
> +		Build for the target machine
> +	sdk-cross:::
> +		FIXME
> +	canadian-cross:::
> +		FIXME
> +		
> +.Example
> +[source,sh]
> +--------
> +RECIPE_TYPES="native machine"
> +--------
> +
> +.RECIPE_FLAGS
> +Optional::
> +	String specifying a list of optional configuration flags for the
> +	recipe. Each flag is seperated by whitespace. The flags can be 
> +	enabled/disabled through USE flags see xref:_use_flags[USE flags].
> +
> +.Example
> +[source,sh]
> +--------
> +RECIPE_FLAGS="flag_one flag_two"
> +--------
> +
> +.DEPENDS
> +Optional::
> +	String specifying a list of dependencies needed to build the
> +	software.
> +
> +.Example
> +[source,sh]
> +-----------
> +DEPENDS="libbz2 libjpeg"
> +-----------
> +
> +Recipe Variables
> +----------------
> +
> +A number of Shell variables can be used in a recipe. Their value is set by the 
> +oe bakery tool to fit the build context.
> +
> +Variables refering to the recipe
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +`${PN}`::
> +	The name of the recipe
> +`${PV}`::
> +	The version of the recipe
> +`${PNV}`::
> +	The name and version of the recipe

AFAIK, we don't support a ${PNV} variable.  We do have a ${P} variable,
defined as

    P = "${PN}-${PV}"

in conf/package.conf.

> +
> +WARNING: The following variables are legacy variables, which should not be used
> +	 in new recipes. They are described here since they are still in use in
> +	 some recipes.
> +
> +`${BPN}`::
> +	Open Embedded legacy: The name of the recipe.

AFAIK, we don't support a ${BPN} variable, so I don't understand how it
should (still) be used in recipes...

> +`${RE}`::
> +	OE-lite core 2.0 legacy: Expands to the recipe type, to be able to
> +	depend on e.g. "-native" "-machine" easily.

Same here.  AFAIK, we don't support a ${RE} variable, so I don't
understand how it should (still) be used in recipes...

> +`${INC_PR}`::
> +	Open Embedded convention.
> +
> +Directory variables
> +~~~~~~~~~~~~~~~~~~~
> +
> +See 'meta/core/conf/oelayout.conf' for more details.
> +
> +`${OEPATH}`::
> +	The directory with the OE-lite manifest clone

That is not correct.  OEPATH is something like:

    # OEPATH='/data/Esben/oe-lite/master:/data/Esben/oe-lite/master/meta/base:/data/Esben/oe-lite/master/meta/core'
    OEPATH='${TOPDIR}:${TOPDIR}/meta/base:${TOPDIR}/meta/core'

So it is a colon separated list of paths, and not a (single) directory.

> +`${TMPDIR}`::
> +	Directory used for everything generated by OE bake +
> +	`${OEPATH}/tmp`
> +`${WORKDIR}`::
> +	Directory where the work is done for the recipe +
> +	`${TMPDIR}/work/${RECIPE_TYPE}/${RECIPE_ARCH}${EXTRA_ARCH}/${P}`
> +`${D}`::
> +	The directory the software build by the recipe is installed into. +
> +	`${WORKDIR}/install`
> +`${SOURCE_DIR}`::
> +	The directory for all extracted source code +
> +	`${WORKDIR}/src`

It is ${SRCDIR} not ${SOURCE_DIR}

> +`${S}`::
> +	Recipe source files directory +
> +	`${SOURCE_DIR}/${PNV}`

It is typically '${SRCDIR}/${P}', but is frequently changed in recipes.

> +`${STAGING_DIR}`::
> +	The directory used to stage any dependencies needed to build the software. +
> +	`${WORKDIR}/stage`

It is ${STAGE_DIR}.

> +
> +Build variables
> +~~~~~~~~~~~~~~~
> +
> +NOTE:
> +Build variables are controlled through OE classes, and should be described there.
> +
> +`${CC}` / `${BUILD_CC}`::
> +	The C compiler used to build the software. The value depends on what 
> +	recipe type is being built.

There are actually 3 variables: ${BUILD_CC}, ${CC}, ${TARGET_CC} They are for
building binaries for build, host and target architectures respectively.

> +`${CPP}` / `${BUILD_CPP}`::
> +	The C++ compiler used to build the software. The value depends on what
> +	recipe type is being built.

Again, 3 variables: ${BUILD_CPP}, ${CPP}, ${TARGET_CPP}

> +`${CXX}` / `${BUILD_CXX}`::
> +	The C++ compiler used to build the software. The value depends on what
> +	recipe type is being built.

Again, 3 variables: ${BUILD_CXX}, ${CXX}, ${TARGET_CXX}

> +`${LD}` / `${BUILD_LD}`::
> +	The linker used to link the software. The value depends on what
> +	recipe type is being built.

Again, 3 variables: ${BUILD_LD}, ${LD}, ${TARGET_LD}

> +`${BUILD_CCLD}`::
> +	FIXME

Again, 3 variables: ${BUILD_CCLD}, ${CCLD}, ${TARGET_CCLD}

> +`${CFLAGS}` / `${BUILD_CFLAGS}`::
> +	The C compiler flags used to build the software.

Again, 3 variables: ${BUILD_CFLAGS}, ${CFLAGS}, ${TARGET_CFLAGS}

> +`${BUILD_CXXFLAGS}`::
> +	The C and C++ compiler flags used to build the software.

Again, 3 variables: ${BUILD_CXXFLAGS}, ${CXXFLAGS}, ${TARGET_CXXFLAGS}

> +`${BUILD_CPPFLAGS}`::
> +	The C++ compiler flags used to build the software.

Again, 3 variables: ${BUILD_CPPFLAGS}, ${CPPFLAGS}, ${TARGET_CPPFLAGS}

> +`${BUILD_LDFLAGS}`::
> +	The linker flags used to link the software.

Again, 3 variables: ${BUILD_ldFLAGS}, ${ldFLAGS}, ${TARGET_ldFLAGS}

> +`${HOST_ARCH}`::
> +	The architecture of the host used to build the software.

> +`${TARGET_ARCH}`::
> +	The architecture of the target machine/cpu.

There is also ${BUILD_ARCH}.

> +
> +Recipe Packages
> +---------------
> +
> +One recipe will typically build one piece of upstream software like one library
> +or application. However, for embedded targets it is often only specific parts
> +of the software that is needed. For this reason one recipe can build multiple
> +"packages" each containing parts of the full software .
> +
> +.`RDEPENDS_${PN}`
> +Optional::
> +	String specifying a list of runtime dependencies for the software
> +	the recipe builds.

I think that can easily be misunderstood.  The RDEPENDS_${PN} variable
specifies the list of runtime dependencies for the ${PN} package that this
recipe builds.

> +
> +.Example
> +[source,sh]
> +-----------
> +RDEPENDS=""
> +-----------

Good work!  Will you revise it and send again?

/Esben

Patch

diff --git a/doc/recipe-guide.txt b/doc/recipe-guide.txt
new file mode 100644
index 0000000..f311d28
--- /dev/null
+++ b/doc/recipe-guide.txt
@@ -0,0 +1,247 @@ 
+// -*- Doc -*-
+
+// This is part of the OE-lite Developers Handbook
+// Copyright (C) 2013
+//   Kim Højgaard-Hansen <kimrhh@gmail.com>
+
+
+Recipe format
+=============
+
+This chapter covers how to create OE-lite recipes for building new software.
+
+What is a recipe
+----------------
+
+An OE-lite recipe is a file with a recipe for building a piece of software
+for OE-lite. Recipe files are located in the recipe directory in oe-lite
+repositories and have the .oe file extension. The file contains source code
+using the OE-lite recipe syntax which is a combination of Python and Shell
+programming. The filename specifies the name of the recipe and optionally
+recipe version as "name_version.oe" e.g.:
+
+-----
+lua_5.2.1.oe
+-----
+
+Allowed recipe names: `[a-zA-Z][a-zA-Z0-9\-]*`
+
+Allowed recipe versions: `[0-9\.]*`
+
+Recipe Metadata
+---------------
+
+A recipe can define a number of metadata variables which is used to build and
+describe the software. Variables can be assigned using the OE-lite
+xref:_assignment_operators[assignment operators].
+
+.DESCRIPTION
+Required::
+	String specifying a description of the software the recipe will build.
+	A description can be longer than SUMMARY.
+
+.Example
+[source,sh]
+----------
+DESCRIPTION="Foo is an application that allows users to do bar much easier.
+             than baz.
+             
+             It is a very flexible tool that with support for both x,y and z"
+----------
+
+.SUMMARY
+Optional::
+	String specifying a short description of the software the recipe will
+	build.
+
+.Example
+[source,sh]
+-----------
+SUMMARY="Foo is a library for doing foo stuff"
+-----------
+
+.LICENCE
+Required::
+	String specifying the licence(s) of the software the recipe will build.
+	Each licence is seperated by whitespace.
+
+.Example
+[source,sh]
+----------
+LICENCE="GPL-2 MIT"
+----------
+
+.HOMEPAGE
+Optional::
+	String specifying the homepage for the software the recipe builds.
+
+.Example
+[source,sh]
+-----------
+HOMEPAGE="http://www.greatproject.org/"
+-----------
+
+.SRC_URI
+Optional::
+	A list of source files needed to build the software. Entries are
+	separated by whitespace. A source file can be either local or remote.
+	For remote files a protocol specifies how the file should be fetched
+	using: `protocol://file` +
+	See xref:_fetch_protocols[fetch protocols] for a list of supported
+	protocols and how they should be used.
+
+.Example
+[source,sh]
+-----------
+SRC_URI="http://www.foobar.org/pub/baz.tar.gz"
+-----------
+
+.RECIPE_TYPES
+Optional::
+	String specifying what targets the software is going to be built for.
+	Possible values are:
+	native:::
+		Build for the host/build machine
+	sdk:::
+		Build for the target SDK
+	machine:::
+		Build for the target machine
+	sdk-cross:::
+		FIXME
+	canadian-cross:::
+		FIXME
+		
+.Example
+[source,sh]
+--------
+RECIPE_TYPES="native machine"
+--------
+
+.RECIPE_FLAGS
+Optional::
+	String specifying a list of optional configuration flags for the
+	recipe. Each flag is seperated by whitespace. The flags can be 
+	enabled/disabled through USE flags see xref:_use_flags[USE flags].
+
+.Example
+[source,sh]
+--------
+RECIPE_FLAGS="flag_one flag_two"
+--------
+
+.DEPENDS
+Optional::
+	String specifying a list of dependencies needed to build the
+	software.
+
+.Example
+[source,sh]
+-----------
+DEPENDS="libbz2 libjpeg"
+-----------
+
+Recipe Variables
+----------------
+
+A number of Shell variables can be used in a recipe. Their value is set by the 
+oe bakery tool to fit the build context.
+
+Variables refering to the recipe
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+`${PN}`::
+	The name of the recipe
+`${PV}`::
+	The version of the recipe
+`${PNV}`::
+	The name and version of the recipe
+
+WARNING: The following variables are legacy variables, which should not be used
+	 in new recipes. They are described here since they are still in use in
+	 some recipes.
+
+`${BPN}`::
+	Open Embedded legacy: The name of the recipe.
+`${RE}`::
+	OE-lite core 2.0 legacy: Expands to the recipe type, to be able to
+	depend on e.g. "-native" "-machine" easily.
+`${INC_PR}`::
+	Open Embedded convention.
+
+Directory variables
+~~~~~~~~~~~~~~~~~~~
+
+See 'meta/core/conf/oelayout.conf' for more details.
+
+`${OEPATH}`::
+	The directory with the OE-lite manifest clone
+`${TMPDIR}`::
+	Directory used for everything generated by OE bake +
+	`${OEPATH}/tmp`
+`${WORKDIR}`::
+	Directory where the work is done for the recipe +
+	`${TMPDIR}/work/${RECIPE_TYPE}/${RECIPE_ARCH}${EXTRA_ARCH}/${P}`
+`${D}`::
+	The directory the software build by the recipe is installed into. +
+	`${WORKDIR}/install`
+`${SOURCE_DIR}`::
+	The directory for all extracted source code +
+	`${WORKDIR}/src`
+`${S}`::
+	Recipe source files directory +
+	`${SOURCE_DIR}/${PNV}`
+`${STAGING_DIR}`::
+	The directory used to stage any dependencies needed to build the software. +
+	`${WORKDIR}/stage`
+
+Build variables
+~~~~~~~~~~~~~~~
+
+NOTE:
+Build variables are controlled through OE classes, and should be described there.
+
+`${CC}` / `${BUILD_CC}`::
+	The C compiler used to build the software. The value depends on what 
+	recipe type is being built.
+`${CPP}` / `${BUILD_CPP}`::
+	The C++ compiler used to build the software. The value depends on what
+	recipe type is being built.
+`${CXX}` / `${BUILD_CXX}`::
+	The C++ compiler used to build the software. The value depends on what
+	recipe type is being built.
+`${LD}` / `${BUILD_LD}`::
+	The linker used to link the software. The value depends on what
+	recipe type is being built.
+`${BUILD_CCLD}`::
+	FIXME
+`${CFLAGS}` / `${BUILD_CFLAGS}`::
+	The C compiler flags used to build the software.
+`${BUILD_CXXFLAGS}`::
+	The C and C++ compiler flags used to build the software.
+`${BUILD_CPPFLAGS}`::
+	The C++ compiler flags used to build the software.
+`${BUILD_LDFLAGS}`::
+	The linker flags used to link the software.
+`${HOST_ARCH}`::
+	The architecture of the host used to build the software.
+`${TARGET_ARCH}`::
+	The architecture of the target machine/cpu.
+
+Recipe Packages
+---------------
+
+One recipe will typically build one piece of upstream software like one library
+or application. However, for embedded targets it is often only specific parts
+of the software that is needed. For this reason one recipe can build multiple
+"packages" each containing parts of the full software .
+
+.`RDEPENDS_${PN}`
+Optional::
+	String specifying a list of runtime dependencies for the software
+	the recipe builds.
+
+.Example
+[source,sh]
+-----------
+RDEPENDS=""
+-----------