summaryrefslogtreecommitdiffstats
path: root/documentation/ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2016-01-19 05:26:02 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2016-01-29 17:04:47 +0000
commitd39e9d1451c316083aee809fee22c539d4b8869d (patch)
tree2d1aca21abbd51c96164c832c2160a7ec3250e75 /documentation/ref-manual
parent1e7735e2901c1db0fbc810b102dda4645a0a97a1 (diff)
downloadpoky-d39e9d1451c316083aee809fee22c539d4b8869d.tar.gz
ref-manual: Rewrite of "Image Generation" and devtool text.
Rewrite of devtool reference section. This was a separate commit but got squashed wrong so it ended up with this commit. The changes to "Image Generation" section reflect the new, more detailed image generation figure (From yocto-docs rev: 827c6872b88c17d2d0c8d44b1024fff19076e505) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r--documentation/ref-manual/closer-look.xml103
1 files changed, 71 insertions, 32 deletions
diff --git a/documentation/ref-manual/closer-look.xml b/documentation/ref-manual/closer-look.xml
index bb7624c9e8..c05972e9ec 100644
--- a/documentation/ref-manual/closer-look.xml
+++ b/documentation/ref-manual/closer-look.xml
@@ -993,11 +993,13 @@
993 993
994 <para> 994 <para>
995 The image generation process consists of several stages and 995 The image generation process consists of several stages and
996 depends on many variables. 996 depends on several tasks and variables.
997 The 997 The
998 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link> 998 <link linkend='ref-tasks-rootfs'><filename>do_rootfs</filename></link>
999 task uses these key variables 999 task creates the root filesystem (file and directory structure)
1000 to help create the list of packages to actually install: 1000 for an image.
1001 This task uses several key variables to help create the list
1002 of packages to actually install:
1001 <itemizedlist> 1003 <itemizedlist>
1002 <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>: 1004 <listitem><para><link linkend='var-IMAGE_INSTALL'><filename>IMAGE_INSTALL</filename></link>:
1003 Lists out the base set of packages to install from 1005 Lists out the base set of packages to install from
@@ -1017,23 +1019,34 @@
1017 Determines the language(s) for which additional 1019 Determines the language(s) for which additional
1018 language support packages are installed. 1020 language support packages are installed.
1019 </para></listitem> 1021 </para></listitem>
1022 <listitem><para><link linkend='var-PACKAGE_INSTALL'><filename>PACKAGE_INSTALL</filename></link>:
1023 The final list of packages passed to the package manager
1024 for installation into the image.
1025 </para></listitem>
1020 </itemizedlist> 1026 </itemizedlist>
1021 </para> 1027 </para>
1022 1028
1023 <para> 1029 <para>
1030 With
1031 <link linkend='var-IMAGE_ROOTFS'><filename>IMAGE_ROOTFS</filename></link>
1032 pointing to the location of the filesystem under construction and
1033 the <filename>PACKAGE_INSTALL</filename> variable providing the
1034 final list of packages to install, the root file system is
1035 created.
1036 </para>
1037
1038 <para>
1024 Package installation is under control of the package manager 1039 Package installation is under control of the package manager
1025 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or 1040 (e.g. smart/rpm, opkg, or apt/dpkg) regardless of whether or
1026 not package management is enabled for the target. 1041 not package management is enabled for the target.
1027 At the end of the process, if package management is not 1042 At the end of the process, if package management is not
1028 enabled for the target, the package manager's data files 1043 enabled for the target, the package manager's data files
1029 are deleted from the root filesystem. 1044 are deleted from the root filesystem.
1030 </para> 1045 As part of the final stage of package installation, postinstall
1031 1046 scripts that are part of the packages are run.
1032 <para> 1047 Any scripts that fail to run
1033 During image generation, the build system attempts to run 1048 on the build host are run on the target when the target system
1034 all post-installation scripts. 1049 is first booted.
1035 Any that fail to run on the build host are run on the
1036 target when the target system is first booted.
1037 If you are using a 1050 If you are using a
1038 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>, 1051 <ulink url='&YOCTO_DOCS_DEV_URL;#creating-a-read-only-root-filesystem'>read-only root filesystem</ulink>,
1039 all the post installation scripts must succeed during the 1052 all the post installation scripts must succeed during the
@@ -1042,24 +1055,17 @@
1042 </para> 1055 </para>
1043 1056
1044 <para> 1057 <para>
1045 During Optimization, optimizing processes are run across 1058 The final stages of the <filename>do_rootfs</filename> task
1046 the image. 1059 handle post processing.
1047 These processes include <filename>mklibs</filename> and 1060 Post processing includes creation of a manifest file and
1048 <filename>prelink</filename>. 1061 optimizations.
1049 The <filename>mklibs</filename> process optimizes the size
1050 of the libraries.
1051 A <filename>prelink</filename> process optimizes the dynamic
1052 linking of shared libraries to reduce start up time of
1053 executables.
1054 </para> 1062 </para>
1055 1063
1056 <para> 1064 <para>
1057 Along with writing out the root filesystem image, the 1065 The manifest file (<filename>.manifest</filename>) resides
1058 <filename>do_rootfs</filename> task creates a manifest file 1066 in the same directory as the root filesystem image.
1059 (<filename>.manifest</filename>) in the same directory as 1067 This file lists out, line-by-line, the installed packages.
1060 the root filesystem image that lists out, line-by-line, the 1068 The manifest file is useful for the
1061 installed packages.
1062 This manifest file is useful for the
1063 <link linkend='ref-classes-testimage*'><filename>testimage</filename></link> 1069 <link linkend='ref-classes-testimage*'><filename>testimage</filename></link>
1064 class, for example, to determine whether or not to run 1070 class, for example, to determine whether or not to run
1065 specific tests. 1071 specific tests.
@@ -1069,21 +1075,54 @@
1069 </para> 1075 </para>
1070 1076
1071 <para> 1077 <para>
1072 Part of the image generation process includes compressing the 1078 Optimizing processes run across the image include
1073 root filesystem image. 1079 <filename>mklibs</filename>, <filename>prelink</filename>,
1074 Compression is accomplished through several optimization 1080 and any other post-processing commands as defined by the
1075 routines designed to reduce the overall size of the image. 1081 <link linkend='var-ROOTFS_POSTPROCESS_COMMAND'><filename>ROOTFS_POSTPROCESS_COMMAND</filename></link>
1082 variable.
1083 The <filename>mklibs</filename> process optimizes the size
1084 of the libraries, while the
1085 <filename>prelink</filename> process optimizes the dynamic
1086 linking of shared libraries to reduce start up time of
1087 executables.
1088 </para>
1089
1090 <para>
1091 After the root filesystem is built, processing begins on
1092 the image through the <filename>do_image</filename> task.
1093 The build system runs any pre-processing commands as defined
1094 by the
1095 <link linkend='var-IMAGE_PREPROCESS_COMMAND'><filename>IMAGE_PREPROCESS_COMMAND</filename></link>
1096 variable.
1097 This variable specifies a list of functions to call before
1098 the OpenEmbedded build system creates the final image output
1099 files.
1076 </para> 1100 </para>
1077 1101
1078 <para> 1102 <para>
1079 After the root filesystem has been constructed, the image 1103 The <filename>do_image</filename> task dynamically creates
1080 generation process turns everything into an image file or 1104 other <filename>do_image_*</filename> tasks as needed, which
1081 a set of image files. 1105 include compressing the root filesystem image to reduce the
1106 overall size of the image.
1107 The process turns everything into an image file or a set of
1108 image files.
1082 The formats used for the root filesystem depend on the 1109 The formats used for the root filesystem depend on the
1083 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link> 1110 <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
1084 variable. 1111 variable.
1085 </para> 1112 </para>
1086 1113
1114 <para>
1115 The final task involved in image creation is the
1116 <filename>do_image_complete</filename> task.
1117 This task completes the image by applying any image
1118 post processing as defined through the
1119 <link linkend='var-IMAGE_POSTPROCESS_COMMAND'><filename>IMAGE_POSTPROCESS_COMMAND</filename></link>
1120 variable.
1121 The variable specifies a list of functions to call once the
1122 OpenEmbedded build system has created the final image output
1123 files.
1124 </para>
1125
1087 <note> 1126 <note>
1088 The entire image generation process is run under Pseudo. 1127 The entire image generation process is run under Pseudo.
1089 Running under Pseudo ensures that the files in the root 1128 Running under Pseudo ensures that the files in the root