summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-03-27 18:23:25 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-04-04 14:13:36 +0100
commit4a4d34226443b04683d9981f99f635664133577b (patch)
tree05dff5a561811e740b308d4bc027749ee3e0da43 /documentation/dev-manual
parent072b38a5c26691280d2ac9ce8aa2c139bbc92a47 (diff)
downloadpoky-4a4d34226443b04683d9981f99f635664133577b.tar.gz
dev-manual: First draft of new init manager section.
I created a first draft of a section titled "Selecting an Initialization Manager." The text was based on information from Ross burton. This is for the "systemd" support that is new for 1.4. There is a lot of work left on the section. This is the first draft. Reported-by: Ross Burton <ross.burton@intel.com> (From yocto-docs rev: ad358b96834879abe8a10d89e77453e30799ac0a) 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.xml127
1 files changed, 91 insertions, 36 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index de35d849eb..768700a277 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1184,8 +1184,8 @@
1184 <title>Working With Libraries</title> 1184 <title>Working With Libraries</title>
1185 1185
1186 <para> 1186 <para>
1187 Libraries are an integral part of your system. 1187 Libraries are an integral part of your system.
1188 This section describes some common practices you might find 1188 This section describes some common practices you might find
1189 helpful when working with libraries to build your system: 1189 helpful when working with libraries to build your system:
1190 <itemizedlist> 1190 <itemizedlist>
1191 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link> 1191 <listitem><para><link linkend='including-static-library-files'>How to include static library files</link>
@@ -1442,46 +1442,46 @@
1442 <title>Installing Multiple Versions of the Same Library</title> 1442 <title>Installing Multiple Versions of the Same Library</title>
1443 1443
1444 <para> 1444 <para>
1445 Situations can exist where you need to install and use 1445 Situations can exist where you need to install and use
1446 multiple versions of the same library on the same system 1446 multiple versions of the same library on the same system
1447 at the same time. 1447 at the same time.
1448 These situations almost always exist when a library API 1448 These situations almost always exist when a library API
1449 changes and you have multiple pieces of software that 1449 changes and you have multiple pieces of software that
1450 depend on the separate versions of the library. 1450 depend on the separate versions of the library.
1451 To accomodate these situations, you can install multiple 1451 To accomodate these situations, you can install multiple
1452 versions of the same library in parallel on the same system. 1452 versions of the same library in parallel on the same system.
1453 </para> 1453 </para>
1454 1454
1455 <para> 1455 <para>
1456 The process is straight forward as long as the libraries use 1456 The process is straight forward as long as the libraries use
1457 proper versioning. 1457 proper versioning.
1458 With properly versioned libraries, all you need to do to 1458 With properly versioned libraries, all you need to do to
1459 individually specify the libraries is create separate, 1459 individually specify the libraries is create separate,
1460 appropriately named recipes where the 1460 appropriately named recipes where the
1461 <ulink url='&YOCTO_DOCS_REF_URL;#var-PN'><filename>PN</filename></ulink> part of 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 1462 name includes a portion that differentiates each library version
1463 (e.g.the major part of the version number). 1463 (e.g.the major part of the version number).
1464 Thus, instead of having a single recipe that loads one version 1464 Thus, instead of having a single recipe that loads one version
1465 of a library (e.g. <filename>clutter</filename>), you provide 1465 of a library (e.g. <filename>clutter</filename>), you provide
1466 multiple recipes that result in different versions 1466 multiple recipes that result in different versions
1467 of the libraries you want. 1467 of the libraries you want.
1468 As an example, the following two recipes would allow the 1468 As an example, the following two recipes would allow the
1469 two separate versions of the <filename>clutter</filename> 1469 two separate versions of the <filename>clutter</filename>
1470 library to co-exist on the same system: 1470 library to co-exist on the same system:
1471 <literallayout class='monospaced'> 1471 <literallayout class='monospaced'>
1472 clutter-1.6_1.6.20.bb 1472 clutter-1.6_1.6.20.bb
1473 clutter-1.8_1.8.4.bb 1473 clutter-1.8_1.8.4.bb
1474 </literallayout> 1474 </literallayout>
1475 Additionally, if you have other recipes that depend on a given 1475 Additionally, if you have other recipes that depend on a given
1476 library, you need to use the 1476 library, you need to use the
1477 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink> 1477 <ulink url='&YOCTO_DOCS_REF_URL;#var-DEPENDS'><filename>DEPENDS</filename></ulink>
1478 variable to create the dependency. 1478 variable to create the dependency.
1479 Continuing with the same example, if you want to have a recipe 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> 1480 depend on the 1.8 version of the <filename>clutter</filename>
1481 library, use the following in your recipe: 1481 library, use the following in your recipe:
1482 <literallayout class='monospaced'> 1482 <literallayout class='monospaced'>
1483 DEPENDS = "clutter-1.8" 1483 DEPENDS = "clutter-1.8"
1484 </literallayout> 1484 </literallayout>
1485 </para> 1485 </para>
1486 </section> 1486 </section>
1487 </section> 1487 </section>
@@ -2197,9 +2197,9 @@
2197 2197
2198 <para> 2198 <para>
2199 Very small distributions have some significant advantages such 2199 Very small distributions have some significant advantages such
2200 as requiring less on-die or in-package memory (cheaper), better 2200 as requiring less on-die or in-package memory (cheaper), better
2201 performance through efficient cache usage, lower power requirements 2201 performance through efficient cache usage, lower power requirements
2202 due to less memory, faster boot times, and reduced development 2202 due to less memory, faster boot times, and reduced development
2203 overhead. 2203 overhead.
2204 Some real-world examples where a very small distribution gives 2204 Some real-world examples where a very small distribution gives
2205 you distinct advantages are digital cameras, medical devices, 2205 you distinct advantages are digital cameras, medical devices,
@@ -2346,7 +2346,7 @@
2346 <title>Trim the Root Filesystem</title> 2346 <title>Trim the Root Filesystem</title>
2347 2347
2348 <para> 2348 <para>
2349 The root filesystem is made up of packages for booting, 2349 The root filesystem is made up of packages for booting,
2350 libraries, and applications. 2350 libraries, and applications.
2351 To change things you can configure how the packaging happens, 2351 To change things you can configure how the packaging happens,
2352 which changes the way you build them. 2352 which changes the way you build them.
@@ -2366,7 +2366,7 @@
2366 a certain size. 2366 a certain size.
2367 This example filters out anything below 100 Kbytes. 2367 This example filters out anything below 100 Kbytes.
2368 The sizes reported by the tool are uncompressed and thus, 2368 The sizes reported by the tool are uncompressed and thus,
2369 will be smaller by a relatively constant factor in a 2369 will be smaller by a relatively constant factor in a
2370 compressed root filesystem. 2370 compressed root filesystem.
2371 When you examine your log file, you can focus on areas of the 2371 When you examine your log file, you can focus on areas of the
2372 root filesystem that take up large amounts of memory. 2372 root filesystem that take up large amounts of memory.
@@ -2390,7 +2390,7 @@
2390 result in minimal impact on the feature set. 2390 result in minimal impact on the feature set.
2391 For example, you might not need a VGA display. 2391 For example, you might not need a VGA display.
2392 Or, you might be able to get by with <filename>devtmpfs</filename> 2392 Or, you might be able to get by with <filename>devtmpfs</filename>
2393 and <filename>mdev</filename> instead of 2393 and <filename>mdev</filename> instead of
2394 <filename>udev</filename>. 2394 <filename>udev</filename>.
2395 </para> 2395 </para>
2396 2396
@@ -2406,10 +2406,10 @@
2406 2406
2407 <para> 2407 <para>
2408 Finally, you should consider exactly the type of root 2408 Finally, you should consider exactly the type of root
2409 filesystem you need to meet your needs while also reducing 2409 filesystem you need to meet your needs while also reducing
2410 its size. 2410 its size.
2411 For example, consider <filename>cramfs</filename>, 2411 For example, consider <filename>cramfs</filename>,
2412 <filename>squashfs</filename>, <filename>ubifs</filename>, 2412 <filename>squashfs</filename>, <filename>ubifs</filename>,
2413 <filename>ext2</filename>, or an <filename>initramfs</filename> 2413 <filename>ext2</filename>, or an <filename>initramfs</filename>
2414 using <filename>initramfs</filename>. 2414 using <filename>initramfs</filename>.
2415 Be aware that <filename>ext3</filename> requires a 1 Mbyte 2415 Be aware that <filename>ext3</filename> requires a 1 Mbyte
@@ -2455,7 +2455,7 @@
2455 drivers, networking, core kernel files, filesystem, sound, 2455 drivers, networking, core kernel files, filesystem, sound,
2456 and so forth. 2456 and so forth.
2457 The sizes reported by the tool are uncompressed and thus, 2457 The sizes reported by the tool are uncompressed and thus,
2458 will be smaller by a relatively constant factor in a compressed 2458 will be smaller by a relatively constant factor in a compressed
2459 kernel image. 2459 kernel image.
2460 Look to reduce the areas that are large and taking up around 2460 Look to reduce the areas that are large and taking up around
2461 the "90% rule". 2461 the "90% rule".
@@ -3074,6 +3074,61 @@
3074 </para> 3074 </para>
3075 </section> 3075 </section>
3076 3076
3077 <section id="selecting-an-initialization-manager">
3078 <title>Selecting an Initialization Manager</title>
3079
3080 <para>
3081 By default, the Yocto Project uses
3082 <filename>SysVinit</filename> as the initialization manager.
3083 However, support also exists for <filename>systemd</filename>.
3084 If you want to use <filename>SysVinit</filename>, you do
3085 not have to do anything.
3086 But, if you want to use <filename>systemd</filename>, you must
3087 take some steps as described in the following sections.
3088 </para>
3089
3090 <section id='using-systemd-exclusively'>
3091 <title>Using systemd Exclusively</title>
3092
3093 <para>
3094 Set the following variables in your
3095 <filename>local.conf</filename> file as follows:
3096 <literallayout class='monospaced'>
3097 DISTRO_FEATURES = "systemd"
3098 VIRTUAL-RUNTIME_init-manager = "systemd"
3099 </literallayout>
3100 You can save some disk space by adding
3101 <filename>sysvinit</filename> to the distribution features
3102 considered for backfill as follows:
3103 <literallayout class='monospaced'>
3104 DISTRO_FEATURES_BACKFILL_CONSIDERED = "sysvinit"
3105 </literallayout>
3106 Doing so removes any redundant <filename>sysvinit</filename>
3107 scripts.
3108 </para>
3109 </section>
3110
3111 <section id='use-systemd-for-the-main-image-and-use-sysvinit-for-the-rescue-image'>
3112 <title>Use systemd for the Main Image and Use SysVinit for the Rescue Image</title>
3113
3114 <para>
3115 Set the following variables in your
3116 <filename>local.conf</filename> file as follows:
3117 <literallayout class='monospaced'>
3118 DISTRO_FEATURES = "systemd"
3119 VIRTUAL-RUNTIME_init-manager = "systemd"
3120 </literallayout>
3121 Doing so causes your main image to use
3122 <filename>packagegroup-core-boot</filename> and
3123 <filename>systemd</filename>.
3124 The rescue/minimal image cannot use this group.
3125 However, it can install <filename>sysvinit</filename>
3126 and the appropriate packages with have both
3127 <filename>systemd</filename> and <filename>sysvinit</filename>.
3128 </para>
3129 </section>
3130 </section>
3131
3077 <section id='excluding-recipes-from-the-build'> 3132 <section id='excluding-recipes-from-the-build'>
3078 <title>Excluding Recipes From the Build</title> 3133 <title>Excluding Recipes From the Build</title>
3079 3134
@@ -3269,10 +3324,10 @@
3269 3324
3270 <para> 3325 <para>
3271 Aside from the GDB cross-binary, you also need a GDB 3326 Aside from the GDB cross-binary, you also need a GDB
3272 initialization file in the same top directory in which 3327 initialization file in the same top directory in which
3273 your binary resides. 3328 your binary resides.
3274 When you start GDB on your host development system, GDB 3329 When you start GDB on your host development system, GDB
3275 finds this initialization file and executes all the 3330 finds this initialization file and executes all the
3276 commands within. 3331 commands within.
3277 For information on the <filename>.gdbinit</filename>, see 3332 For information on the <filename>.gdbinit</filename>, see
3278 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>" 3333 "<ulink url='http://sourceware.org/gdb/onlinedocs/gdb/'>Debugging with GDB</ulink>"
@@ -3289,7 +3344,7 @@
3289 the following to set your root filesystem location 3344 the following to set your root filesystem location
3290 by using a command with this form: 3345 by using a command with this form:
3291 <literallayout class='monospaced'> 3346 <literallayout class='monospaced'>
3292 set sysroot &lt;your-sysroot-path&gt; 3347 set sysroot &lt;your-sysroot-path&gt;
3293 </literallayout> 3348 </literallayout>
3294 </para> 3349 </para>
3295 </section> 3350 </section>
@@ -3298,17 +3353,17 @@
3298 <title>Launch the Host GDB</title> 3353 <title>Launch the Host GDB</title>
3299 3354
3300 <para> 3355 <para>
3301 To launch the host GDB, you need to source the 3356 To launch the host GDB, you need to source the
3302 cross-debugging environment script, which if you installed 3357 cross-debugging environment script, which if you installed
3303 the root filesystem in the default location is at 3358 the root filesystem in the default location is at
3304 <filename>/opt/poky/&DISTRO;</filename> and begins with the 3359 <filename>/opt/poky/&DISTRO;</filename> and begins with the
3305 string "environment-setup". 3360 string "environment-setup".
3306 </para> 3361 </para>
3307 3362
3308 <para> 3363 <para>
3309 Finally, run the <filename>cross-gdb</filename> binary 3364 Finally, run the <filename>cross-gdb</filename> binary
3310 and provide the inferior binary as part of the command line. 3365 and provide the inferior binary as part of the command line.
3311 For example, the following command form continues with the 3366 For example, the following command form continues with the
3312 example used in the previous section. 3367 example used in the previous section.
3313 This command form loads the <filename>foo</filename> binary 3368 This command form loads the <filename>foo</filename> binary
3314 as well as the debugging information: 3369 as well as the debugging information: