summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-03-22 10:47:55 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-04-04 14:12:49 +0100
commitde4f0d1ded239a3af6e876bce87a963426f54074 (patch)
tree53fffafae93097d95babbc53b319ba00f9b231dd /documentation/dev-manual
parentd0edd46ebbcd681254ef70c97cd90b3f70cdc688 (diff)
downloadpoky-de4f0d1ded239a3af6e876bce87a963426f54074.tar.gz
dev-manual: New section for installing different versions of a lib
Fixes YOCTO #1548 Added a new section to describe how to install multiple versions of the same library in parallel on the same system. Also, I added some introductory text into the parent section that houses the three sub-sections that deal with library use-cases. (From yocto-docs rev: c77538bc8adae90e4b900f129b63988fa3ab6c9e) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml71
1 files changed, 49 insertions, 22 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e08332d948..0f6c78b855 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1184,7 +1184,17 @@
1184 <title>Working With Libraries</title> 1184 <title>Working With Libraries</title>
1185 1185
1186 <para> 1186 <para>
1187 Intro text 1187 Libraries are an integral part of your system.
1188 This section describes some common practices you might find
1189 helpful when working with libraries to build your system:
1190 <itemizedlist>
1191 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
1192 </para></listitem>
1193 <listitem><para><link linkend='combining-multiple-versions-library-files-into-one-image'>How to use the Multilib feature to combine multiple versions of library files into a single image</link>
1194 </para></listitem>
1195 <listitem><para><link linkend='installing-multiple-versions-of-the-same-library'>How to install multiple versions of the same library in parallel on the same system</link>
1196 </para></listitem>
1197 </itemizedlist>
1188 </para> 1198 </para>
1189 1199
1190 <section id='including-static-library-files'> 1200 <section id='including-static-library-files'>
@@ -1432,29 +1442,46 @@
1432 <title>Installing Multiple Versions of the Same Library</title> 1442 <title>Installing Multiple Versions of the Same Library</title>
1433 1443
1434 <para> 1444 <para>
1445 Situations can exist where you need to install and use
1446 multiple versions of the same library on the same system
1447 at the same time.
1448 These situations almost always exist when a library API
1449 changes and you have multiple pieces of software that
1450 depend on the separate versions of the library.
1451 To accomodate these situations, you can install multiple
1452 versions of the same library in parallel on the same system.
1453 </para>
1454
1455 <para>
1456 The process is straight forward as long as the libraries use
1457 proper versioning.
1458 With properly versioned libraries, all you need to do to
1459 individually specify the libraries is create separate,
1460 appropriately named recipes where the
1461 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of the
1462 name includes a portion that differentiates each library version
1463 (e.g.the major part of the version number).
1464 Thus, instead of having a single recipe that loads one version
1465 of a library (e.g. <filename>clutter</filename>), you provide
1466 multiple recipes that result in different versions
1467 of the libraries you want.
1468 As an example, the following two recipes would allow the
1469 two separate versions of the <filename>clutter</filename>
1470 library to co-exist on the same system:
1435 <literallayout class='monospaced'> 1471 <literallayout class='monospaced'>
1436 (08:04:38 AM) scottrif: RP: I am looking at an old bug (https://bugzilla.yoctoproject.org/show_bug.cgi?id=1548) regarding documenting how multiple different library versions of a library can be built and installed in parallel on a system. You mention Clutter as a good example of this. Before I start diving into this can you tell me if it is still relevant given the bug was filed in Oct. of 2011? 1472 clutter-1.6_1.6.20.bb
1437(08:06:44 AM) paul.eggleton: scottrif: it's still a valid use case I think 1473 clutter-1.8_1.8.4.bb
1438(08:06:59 AM) scottrif: paul.eggleton: ok - thanks
1439(08:07:43 AM) paul.eggleton: it's not too tricky assuming the library uses proper versioning itself; if it does you just need to ensure something version-specific appears in PN
1440(08:08:07 AM) paul.eggleton: so e.g. for clutter, PN is clutter-1.8 rather than just clutter
1441(08:09:25 AM) scottrif: paul.eggleton: so PN specifies version 1.8 in your example. Do you put multiple PN statements somewhere to accomplish installing multiple versions of the same library?
1442(08:09:52 AM) paul.eggleton: scottrif: no, you need to provide a separate recipe for each version
1443(08:09:59 AM) paul.eggleton: scottrif: so the PN would come from the file name
1444(08:10:07 AM) paul.eggleton: (as normal)
1445(08:10:24 AM) paul.eggleton: so e.g. the recipe might be clutter-1.8_1.8.4.bb
1446(08:10:30 AM) scottrif: paul.eggleton: ok - one version per library version and each recipe specifically uses PN to indicate the version.
1447(08:10:48 AM) paul.eggleton: the major part of the version, yes
1448(08:10:48 AM) scottrif: paul.eggleton: I mean one "recipe" per library version :)
1449(08:11:18 AM) scottrif: paul.eggleton: major being "1.8" in your example
1450(08:11:33 AM) paul.eggleton: right, in this instance one recipe per major version since the API got changed between the two
1451(08:11:56 AM) paul.eggleton: (which is the typical cause of needing to do this multiple version exercise)
1452(08:12:15 AM) scottrif: paul.eggleton: okay - so what circumstances do I tell the reader when it is a good idea to do this besides the case you just stated?
1453(08:14:07 AM) paul.eggleton: it's almost always about an API change and you have other pieces of software that depend on both versions that you need to build and use at runtime within the same system
1454(08:14:22 AM) paul.eggleton: in fact I can't think of another reason why you'd want to do this
1455(08:14:44 AM) scottrif: paul.eggleton: ok - I will stick to that one. Thanks! I will probably enlist you to check over the new section :)
1456(08:14:52 AM) paul.eggleton: scottrif: sure thing
1457 </literallayout> 1474 </literallayout>
1475 Additionally, if you have other recipes that depend on a given
1476 library, you need to use the
1477 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1478 variable to create the dependency.
1479 Continuing with the same example, if you want to have a recipe
1480 depend on the 1.8 version of the <filename>clutter</filename>
1481 library, use the following in your recipe:
1482 <literallayout class='monospaced'>
1483 DEPENDS = "clutter-1.8"
1484 </literallayout>
1458 </para> 1485 </para>
1459 </section> 1486 </section>
1460 </section> 1487 </section>