From 5a3296cf25399052774b7ddfbe5a70aa46bd28d4 Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Fri, 8 Nov 2013 14:09:44 -0800 Subject: dev-manual: Put into place a rough draft of the "Writing Recipe" section This draft has the structure with text from Paul's email. It needs further work. (From yocto-docs rev: 08025edc34995f7436786e9ed3abdfa155db47af) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- .../dev-manual/dev-manual-common-tasks.xml | 169 +++++++++++++++++++++ 1 file changed, 169 insertions(+) diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index 3f4b446..707d1c3 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -1136,6 +1136,175 @@ +
+ Writing a New Recipe + + + Recipes (.bb files) are fundamental components + in the Yocto Project environment. + The OpenEmbedded build system parses and compiles your recipes to + create an image. + Your project consists in part of the recipes that define it. + This section describes how to create, write, and test a new + recipe. + + +
+ Overview + + + The following figure shows the basic process for creating a + new recipe. + Subsequent sections provide details for each step. + + +
+ +
+ Locate a Base Recipe + + + Working from an existing recipe or a skeleton recipe is the + best way to get started. + Here are some points on both methods: + + Locate a recipe that is close + to what you want to do and use it: + This method works when you are familiar with the + current recipe space. + The method does not work so well for those new to + the Yocto Project or writing recipes. + Some risks associated with this method are + using a recipe that has areas totally unrelated to + what you are trying to accomplish with your recipe, + not recognizing areas of the recipe that you might + have to add from scratch, and so forth. + All these risks stem from unfamiliarity with the + existing recipe space. + Use a skeleton recipe: + Using the skeleton recipe located at + <Need some path for a good recipe to use> is the + recommended method for creating a new recipe. + The skeleton recipe provides the fundamental areas + that you need to include, exclude, or alter to fit + your needs. + + + +
+ +
+ Fetching Code + + + fetching: basically a matter of ensuring SRC_URI is correct, and for archives +that SRC_URI checksums are specified and correct. We should show examples of +the error message you get when you don't, from which you can copy and paste +the lines with the correct values. + +
+ +
+ Unpacking Code + + + unpacking: ensure S matches the directory that contains the source. Often the +default will work for a source archive, but it depends on how the upstream +project structures their archive. If SRC_URI specifies to fetch the source from +an SCM such as git or svn you'll definitely need to set S. + +
+ +
+ Licensing + + + licensing: set correct values for LICENSE and LIC_FILES_CHKSUM, i.e. look for +a license statement somewhere (COPYING, LICENSE, part of a README, top of a +source file etc.) and then set the two variables accordingly. You need to go +through this several steps, i.e. look in the directory containing the +extracted source, then set LIC_FILES_CHKSUM to point to the file without the +md5 value specified, and then run bitbake on the recipe again and it will error +out with the actual md5 value which you can then put into the recipe. I notice +we don't necessarily have a list anywhere of the common values for LICENSE +either, so maybe we need to add this to the variable reference entry for this +variable. We should also cover what to do if there is no file specifying the +license shipped with the source. + +
+ +
+ Supporting Services + + + We'll probably also need some subsections on specific extra functions needed in +some recipes e.g. how to add support for services (sysvinit and systemd), +adding PACKAGECONFIG options, dealing with alternatives, etc. There's a +question in my mind on how some of these will overlap with the class reference +section though. + +
+ +
+ Configuring the Recipe + + + configure: this depends on whether you're using autotools or not; if you are +then you should set EXTRA_OECONF to pass any needed configure options specific +to this recipe. If you are not using autotools, you need to define your own +do_configure function, assuming there is anything to configure. At this point +you may also need to tweak DEPENDS if the configure scripts complain about any +required dependencies being missing, assuming it's not just looking in the +wrong place for the dependency in which case it's usually a matter of +supplying the appropriate configure options to point to the correct location +within the sysroot. + +
+ +
+ Compiling the Recipe + + + compile: if the recipe passes through do_compile successfully, nothing needs +to be done. If not, diagnose the failure. We might be able to highlight common +issues here such as parallel build failures, host path usage when building for +the target, etc. + +
+ +
+ Optionally Installing + + + install: for autotools/cmake recipes, if the recipe passes through do_install +successfully, nothing needs to be done (at this stage). If not, diagnose the +failure. For non-autotools recipes you need to define your own do_install +(which may well just run "oe_runmake install"). + +
+ +
+ Packaging + + + packaging: ensure that the files are packaged correctly. Resolve any package QA +issues (we need to have more detailed docs on this, probably as its own +section). This can also involve looking at packages-split under the work +directory and checking if files are where they need to be; if not, set +PACKAGES, FILES, do_install(_append) etc. as needed. + +
+ +
+ Testing + + + runtime testing: add the output package(s) to your image and ensure that they +work at runtime. + +
+
+
Writing a Recipe to Add a Package to Your Image -- cgit v1.1