@@ -43,9 +43,11 @@ include::overview.txt[]
// Build Configuration
include::buildcfg.txt[]
+// Recipe Development
+include::recipes.txt[]
+
// Metadata Language
include::language.txt[]
-//// including guidelines for recipe format/structure
// Tasks
include::tasks.txt[]
@@ -1,8 +1,292 @@
-Recipes
-=======
+// -*- Doc -*-
-This section describes the recipes provided by OE-lite/core.
+// This is part of the OE-lite Developers Handbook
+// Copyright (C) 2013
+// Kim Højgaard-Hansen <kimrhh@gmail.com>
-:leveloffset: 2
-include::auto/recipes/INDEX.txt[]
+OE-lite Recipes
+===============
+
+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 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"
+-----------
+
+.RDEPENDS
+Optional::
+ String specifying a list of dependencies needed to run the
+ software
+
+.Example
+[source,sh]
+-----------
+RDEPENDS=""
+-----------
+
+[NOTE]
+See the xref:_dependencies[Dependencies] chapter for more in depth
+information on how to specify dependencies.
+
+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.
+
+By default a number of packages are defined for each recipe:
+
+----
+${PN} ${PN}-dev ${PN}-dbg ${PN}-doc ${PN}-locale
+----
+
+A recipe can decide what files should end up in which packages using the
+`FILES_` variable. For example to make the file `foo` belong to the `bar`
+package:
+
+----
+PACKAGES += "${PN}-bar"
+FILES_${PN}-bar += "foo"
+----
+
+To avoid specifying every single file explicitly, it is possible to use
+globbing for the `FILES_` variable. For example to include all the files
+starting with `foo` in the `bar` package:
+
+----
+PACKAGES += "${PN}-bar"
+FILES_${PN}-bar += "foo*"
+----
+
+The default packages have the following file selection patterns set:
+
+----
+${PN}:
+'/bin/*' '/lib/lib*.so.*' '/share/testpkg' '/lib/testpkg' '/libexec/*' '/var/*'
+'/com/*' '/etc/*'
+${PN}-dev:
+'/lib/*.a' '/lib/*.la' '/lib/*.o' '/lib/lib*.so' '/share/aclocal' '/share/pkgconfig'
+'/include' '/lib/*/include' '/lib/pkgconfig'
+${PN}-dbg:
+'/libexec/.debug' '/bin/.debug' '/lib/.debug' '/lib/${PN}/.debug'
+${PN}-doc:
+'/share/doc' '/share/man' '/share/info'
+${PN}-locale:
+'/share/locale'
+----
From: Kim Højgaard-Hansen <kiho@prevas.dk> --- doc/manual.txt | 4 +- doc/recipes.txt | 294 +++++++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 292 insertions(+), 6 deletions(-)