summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-common-tasks.xml
diff options
context:
space:
mode:
Diffstat (limited to 'documentation/dev-manual/dev-manual-common-tasks.xml')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml77
1 files changed, 77 insertions, 0 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 3024252b76..3c2012cf19 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -2267,6 +2267,83 @@
2267 2267
2268 </section> 2268 </section>
2269 2269
2270 <section id='new-dependencies'>
2271 <title>Dependencies</title>
2272
2273 <para>
2274 Most software packages have a short list of other packages
2275 that they require, which are called dependencies.
2276 These dependencies fall into two main categories: build-time
2277 dependencies, which are required when the software is built;
2278 and runtime dependencies, which are required to be installed
2279 on the target in order for the software to run.
2280 </para>
2281
2282 <para>
2283 Within a recipe, you specify build-time dependencies using the
2284 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
2285 variable.
2286 Although nuances exist, items specified in
2287 <filename>DEPENDS</filename> should be names of other recipes.
2288 It is important that you specify all build-time dependencies
2289 explicitly.
2290 If you do not, due to the parallel nature of BitBake's
2291 execution, you can end up with a race condition where the
2292 dependency is present for one task of a recipe (e.g.
2293 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-configure'><filename>do_configure</filename></ulink>)
2294 and then gone when the next task runs (e.g.
2295 <ulink url='&YOCTO_DOCS_REF_URL;#ref-tasks-compile'><filename>do_compile</filename></ulink>).
2296 </para>
2297
2298 <para>
2299 Another consideration is that configure scripts might
2300 automatically check for optional dependencies and enable
2301 corresponding functionality if those dependencies are found.
2302 This behavior means that to ensure deterministic results and
2303 thus avoid more race conditions, you need to either explicitly
2304 specify these dependencies as well, or tell the configure
2305 script explicitly to disable the functionality.
2306 If you wish to make a recipe that is more generally useful
2307 (e.g. publish the recipe in a layer for others to use),
2308 instead of hard-disabling the functionality, you can use the
2309 <ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGECONFIG'><filename>PACKAGECONFIG</filename></ulink>
2310 variable to allow functionality and the corresponding
2311 dependencies to be enabled and disabled easily by other
2312 users of the recipe.
2313 </para>
2314
2315 <para>
2316 Similar to build-time dependencies, you specify runtime
2317 dependencies through a variable -
2318 <ulink url='&YOCTO_DOCS_REF_URL;#var-RDEPENDS'><filename>RDEPENDS</filename></ulink>,
2319 which is package-specific.
2320 All variables that are package-specific need to have the name
2321 of the package added to the end as an override.
2322 Since the main package for a recipe has the same name as the
2323 recipe, and the recipe's name can be found through the
2324 <filename>${</filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink><filename>}</filename>
2325 variable, then you specify the dependencies for the main
2326 package by setting <filename>RDEPENDS_${PN}</filename>.
2327 If the package were named <filename>${PN}-tools</filename>,
2328 then you would set <filename>RDEPENDS_${PN}-tools</filename>,
2329 and so forth.
2330 </para>
2331
2332 <para>
2333 Some runtime dependencies will be set automatically at
2334 packaging time.
2335 These dependencies include any shared library dependencies
2336 (i.e. if a package "example" contains "libexample" and
2337 another package "mypackage" contains a binary that links to
2338 "libexample" then the OpenEmbedded build system will
2339 automatically add a runtime dependency to "mypackage" on
2340 "example").
2341 See the
2342 "<ulink url='&YOCTO_DOCS_REF_URL;#automatically-added-runtime-dependencies'>Automatically Added Runtime Dependencies</ulink>"
2343 in the Yocto Project Reference Manual for further details.
2344 </para>
2345 </section>
2346
2270 <section id='new-recipe-configuring-the-recipe'> 2347 <section id='new-recipe-configuring-the-recipe'>
2271 <title>Configuring the Recipe</title> 2348 <title>Configuring the Recipe</title>
2272 2349