summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2013-08-02 16:56:40 +0300
committerRichard Purdie <richard.purdie@linuxfoundation.org>2013-08-13 13:18:47 +0100
commit4b23d26063790c4dad466cf8a0af8ba4a0970f1d (patch)
tree954e2b6096c4fa983d18ae04cb8860067cc21725 /documentation
parent17ded75fdec517bfc6809091c56910cf55986f62 (diff)
downloadpoky-4b23d26063790c4dad466cf8a0af8ba4a0970f1d.tar.gz
ref-manual, mega-manual: New section for images/SDK
Fixes [YOCTO #2808] Added a new section for the closer look at how BitBake creates images and the SDK installer files. This included the section itself, a new .PNG figure that had to be added to the figures directory of both the ref-manual and the mega-manual. Finally, the Makefile needed to be edited so that the tarballs for the ref-manual and mega-manual also included the new figure. Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/Makefile5
-rw-r--r--documentation/mega-manual/figures/images-sdk.pngbin0 -> 24595 bytes
-rw-r--r--documentation/ref-manual/figures/images-sdk.pngbin0 -> 24595 bytes
-rw-r--r--documentation/ref-manual/ref-structure.xml9
-rw-r--r--documentation/ref-manual/technical-details.xml163
5 files changed, 174 insertions, 3 deletions
diff --git a/documentation/Makefile b/documentation/Makefile
index ca70bce772..e286ea4ddc 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -198,7 +198,7 @@ TARFILES = mega-manual.html mega-style.css figures/yocto-environment.png figures
198 figures/sched-wakeup-profile.png figures/sysprof-callers.png \ 198 figures/sched-wakeup-profile.png figures/sysprof-callers.png \
199 figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \ 199 figures/sysprof-copy-from-user.png figures/sysprof-copy-to-user.png figures/cross-development-toolchains.png \
200 figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \ 200 figures/yocto-environment-ref.png figures/user-configuration.png figures/source-input.png \
201 figures/package-feeds.png figures/layer-input.png 201 figures/package-feeds.png figures/layer-input.png figures/images-sdk.png
202 endif 202 endif
203 203
204MANUALS = $(DOC)/$(DOC).html 204MANUALS = $(DOC)/$(DOC).html
@@ -214,7 +214,8 @@ TARFILES = ref-manual.html ref-style.css figures/poky-title.png \
214 figures/buildhistory.png figures/buildhistory-web.png eclipse \ 214 figures/buildhistory.png figures/buildhistory-web.png eclipse \
215 figures/cross-development-toolchains.png figures/layer-input.png \ 215 figures/cross-development-toolchains.png figures/layer-input.png \
216 figures/package-feeds.png figures/source-input.png \ 216 figures/package-feeds.png figures/source-input.png \
217 figures/user-configuration.png figures/yocto-environment-ref.png 217 figures/user-configuration.png figures/yocto-environment-ref.png \
218 figures/images-sdk.png
218MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse 219MANUALS = $(DOC)/$(DOC).html $(DOC)/$(DOC).pdf $(DOC)/eclipse
219FIGURES = figures 220FIGURES = figures
220STYLESHEET = $(DOC)/*.css 221STYLESHEET = $(DOC)/*.css
diff --git a/documentation/mega-manual/figures/images-sdk.png b/documentation/mega-manual/figures/images-sdk.png
new file mode 100644
index 0000000000..c124a452a3
--- /dev/null
+++ b/documentation/mega-manual/figures/images-sdk.png
Binary files differ
diff --git a/documentation/ref-manual/figures/images-sdk.png b/documentation/ref-manual/figures/images-sdk.png
new file mode 100644
index 0000000000..c124a452a3
--- /dev/null
+++ b/documentation/ref-manual/figures/images-sdk.png
Binary files differ
diff --git a/documentation/ref-manual/ref-structure.xml b/documentation/ref-manual/ref-structure.xml
index d482511516..1d19ffd07f 100644
--- a/documentation/ref-manual/ref-structure.xml
+++ b/documentation/ref-manual/ref-structure.xml
@@ -356,7 +356,14 @@
356 <title><filename>build/tmp/deploy/</filename></title> 356 <title><filename>build/tmp/deploy/</filename></title>
357 357
358 <para> 358 <para>
359 This directory contains any "end result" output from the OpenEmbedded build process. 359 This directory contains any "end result" output from the
360 OpenEmbedded build process.
361 The <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
362 variable points to this directory.
363 For more detail on the contents of the <filename>deploy</filename>
364 directory, see the
365 "<link linkend='images-and-application-development-sdk'>Images and Application Development SDK</link>"
366 section.
360 </para> 367 </para>
361 </section> 368 </section>
362 369
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml
index c7a49da946..6ae8ee50e0 100644
--- a/documentation/ref-manual/technical-details.xml
+++ b/documentation/ref-manual/technical-details.xml
@@ -796,6 +796,169 @@
796 <filename>do_package_write_ipk</filename> for IPK packages). 796 <filename>do_package_write_ipk</filename> for IPK packages).
797 </para> 797 </para>
798 </section> 798 </section>
799
800 <section id='images-and-application-development-sdk'>
801 <title>Images and Application Development SDK</title>
802
803 <para>
804 The purpose of using the OpenEmbedded build system is to produce
805 an image or a Software Development Kit (SDK).
806 You can see from the main
807 <link linkend='a-closer-look-at-the-yocto-project-development-environment'>Yocto Project Development Environment</link>
808 figure that the output (shown in red) are images and SDKs.
809 This section is going to look more closely at this output:
810 <imagedata fileref="figures/images-sdk.png" align="center" width="5in" depth="4in" />
811 </para>
812
813 <section id='images-dev-environment'>
814 <title>Images</title>
815
816 <para>
817 The images produced by BitBake are compressed forms of the
818 root filesystems that are ready to boot on a target device.
819 You can see the
820 "<link linkend='ref-images'>Images</link>" chapter for a list
821 of example images that the Yocto Project provides.
822 </para>
823
824 <para>
825 Images are kept in the
826 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
827 inside the <filename>deploy/images</filename> folder as shown
828 in the figure.
829 This folder contains any files expected to be loaded on the
830 target device.
831 The
832 <link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>
833 variable points to the <filename>deploy</filename> directory.
834 <itemizedlist>
835 <listitem><para><filename>&lt;image&gt;</filename>:
836 A <filename>*.bin</filename> image file.
837 The <link linkend='var-KERNEL_IMAGETYPE'><filename>KERNEL_IMAGETYPE</filename></link>
838 variable setting determines the naming scheme for the
839 image file.
840 Depending on that variable, the file could begin with
841 a variety of naming strings.
842 The <filename>deploy/images</filename> directory can
843 contain multiple image files.</para></listitem>
844 <listitem><para><filename>&lt;root-filesystem&gt;</filename>:
845 Root filesystems for the target device (e.g.
846 <filename>*.ext3</filename> or <filename>*.bz2</filename>
847 files).
848 The <link linkend='var-IMAGE_FSTYPES'><filename>IMAGE_FSTYPES</filename></link>
849 variable setting determines the root filesystem
850 type.
851 The <filename>deploy/images</filename> directory can
852 contain multiple root filesystems.</para></listitem>
853 <listitem><para><filename>&lt;kernel-modules&gt;</filename>:
854 Tarballs that contain all the modules used by the
855 kernel.
856 Kernel module tarballs exist for legacy purposes and
857 can be suppressed by setting the
858 <link linkend='var-MODULE_TARBALL_DEPLOY'><filename>MODULE_TARBALL_DEPLOY</filename></link>
859 variable to "0".
860 The <filename>deploy/images</filename> directory can
861 contain multiple kernel module tarballs.
862 </para></listitem>
863 <listitem><para><filename>&lt;bootloaders&gt;</filename>:
864 Bootloaders supporting the image.
865 The <filename>deploy/images</filename> directory can
866 contain multiple bootloaders.
867 </para></listitem>
868 <listitem><para><filename>&lt;symlinks&gt;</filename>:
869 The <filename>images/deploy</filename> folder contains
870 a symbolic link for each actual file in the folder.
871 Links exist for all types of files (i.e. images,
872 root filesystems, bootloaders, and kernel module
873 tarballs).
874 The link scheme for images is such that a single link
875 exists for the most recently built image.
876 In addition to that single image link, additional
877 links exist on a one-for-one basis that map to each
878 physical image file.</para></listitem>
879 </itemizedlist>
880 </para>
881 </section>
882
883 <section id='sdk-dev-environment'>
884 <title>Application Development SDK</title>
885
886 <para>
887 An Application Development SDK (referred to as an
888 "SDK installer" in this section) is a self-extracting SDK
889 installer file (<filename>*.sh</filename>) that, when run,
890 installs a cross-development toolchain, a set of libraries
891 and headers, and an SDK environment setup script.
892 Running this installer essentially sets up your
893 cross-development environment.
894 You can think of the cross-toolchains as the "host" part
895 because they run on the SDK machine.
896 You can think of the libraries and headers as the "target"
897 part because they are built for the target hardware.
898 The setup script is added so that you can initialize the
899 environment before using the tools.
900 </para>
901
902 <note>
903 <para>
904 The Yocto Project supports several methods by which you can
905 set up this cross-development environment.
906 These methods include downloading pre-built SDK installers,
907 building and installing your own SKD installer, or running
908 an Application Development Toolkit (ADT) installer to
909 install not just cross-development toolchains
910 but also additional tools to help in this type of
911 development.
912 </para>
913
914 <para>
915 For background information on cross-development toolchains
916 in the Yocto Project development environment, see the
917 "<link linkend='cross-development-toolchain-generation'>Cross-Development Toolchain Generation</link>"
918 section.
919 For information on setting up a cross-development
920 environment, see the
921 "<ulink url='&YOCTO_DOCS_ADT_URL;#installing-the-adt'>Installing the ADT and Toolchains</ulink>"
922 section in the Yocto Project Application Developer's Guide.
923 </para>
924 </note>
925
926 <para>
927 When built using BitBake, the SDK installers are kept in the
928 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>
929 inside the <filename>deploy/sdk</filename> folder as shown
930 in the figure at the beginning of this section.
931 Several variables exist that help configure these files:
932 <itemizedlist>
933 <listitem><para><link linkend='var-DEPLOY_DIR'><filename>DEPLOY_DIR</filename></link>:
934 Points to the <filename>deploy</filename>
935 directory.</para></listitem>
936 <listitem><para><link linkend='var-SDKMACHINE'><filename>SDKMACHINE</filename></link>:
937 Specifies the architecture of the machine
938 on which the cross-development tools are run to
939 create packages for the target hardware.
940 </para></listitem>
941 <listitem><para><link linkend='var-SDKIMAGE_FEATURES'><filename>SDKIMAGE_FEATURES</filename></link>:
942 Lists the features to include in the libraries.
943 </para></listitem>
944 <listitem><para><link linkend='var-TOOLCHAIN_HOSTS_TASKS'><filename>TOOLCHAIN_HOSTS_TASKS</filename></link>:
945 Lists packages that make up the host
946 part of the SDK installer (i.e. the part that runs on
947 the <filename>SDKMACHINE</filename>).
948 When you use <filename>bitbake sdk_populate</filename>
949 to create the SDK installer, a set of default tasks
950 apply.
951 This variable allows you to add more tasks.
952 </para></listitem>
953 <listitem><para><link linkend='var-TOOLCHAIN_TARGET_TASKS'><filename>TOOLCHAIN_TARGET_TASKS</filename></link>:
954 Lists packages that make up the target part
955 of the SDK installer (i.e. the part built for the
956 target hardware).
957 </para></listitem>
958 </itemizedlist>
959 </para>
960 </section>
961 </section>
799</section> 962</section>
800 963
801<section id="cross-development-toolchain-generation"> 964<section id="cross-development-toolchain-generation">