| Message ID | 1384179914-16049-4-git-send-email-kim.hansen@prevas.dk |
|---|---|
| State | Changes Requested |
| Delegated to: | Esben Haabendal |
| Headers | show |
> 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
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="" +-----------
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