summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2018-05-16 14:50:42 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2018-05-24 17:16:35 +0100
commitbfaf918ec932261273c7383a9922c88301c92822 (patch)
tree856229d63ecde210c10a019a452ae0bbd08d611a /documentation/dev-manual
parent16e730e638b9261036fea382cddf045f445cd365 (diff)
downloadpoky-bfaf918ec932261273c7383a9922c88301c92822.tar.gz
dev-manual: Moved "Building a Tiny System"
This section is now part of the building parent section. I have moved it there in the common tasks chapter. (From yocto-docs rev: a9fccb1bca8e18169d93416c7a6e17723bcf01c7) Signed-off-by: Scott Rifenbark <srifenbark@gmail.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.xml852
1 files changed, 425 insertions, 427 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 63b758a569..07e01f0f25 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -5522,6 +5522,431 @@
5522 </orderedlist> 5522 </orderedlist>
5523 </para> 5523 </para>
5524 </section> 5524 </section>
5525
5526 <section id='building-a-tiny-system'>
5527 <title>Building a Tiny System</title>
5528
5529 <para>
5530 Very small distributions have some significant advantages such
5531 as requiring less on-die or in-package memory (cheaper), better
5532 performance through efficient cache usage, lower power requirements
5533 due to less memory, faster boot times, and reduced development
5534 overhead.
5535 Some real-world examples where a very small distribution gives
5536 you distinct advantages are digital cameras, medical devices,
5537 and small headless systems.
5538 </para>
5539
5540 <para>
5541 This section presents information that shows you how you can
5542 trim your distribution to even smaller sizes than the
5543 <filename>poky-tiny</filename> distribution, which is around
5544 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
5545 </para>
5546
5547 <section id='tiny-system-overview'>
5548 <title>Overview</title>
5549
5550 <para>
5551 The following list presents the overall steps you need to
5552 consider and perform to create distributions with smaller
5553 root filesystems, achieve faster boot times, maintain your critical
5554 functionality, and avoid initial RAM disks:
5555 <itemizedlist>
5556 <listitem><para>
5557 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
5558 </para></listitem>
5559 <listitem><para>
5560 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
5561 </para></listitem>
5562 <listitem><para>
5563 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
5564 </para></listitem>
5565 <listitem><para>
5566 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
5567 </para></listitem>
5568 <listitem><para>
5569 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
5570 </para></listitem>
5571 <listitem><para>
5572 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
5573 </para></listitem>
5574 <listitem><para>
5575 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
5576 </para></listitem>
5577 </itemizedlist>
5578 </para>
5579 </section>
5580
5581 <section id='goals-and-guiding-principles'>
5582 <title>Goals and Guiding Principles</title>
5583
5584 <para>
5585 Before you can reach your destination, you need to know
5586 where you are going.
5587 Here is an example list that you can use as a guide when
5588 creating very small distributions:
5589 <itemizedlist>
5590 <listitem><para>Determine how much space you need
5591 (e.g. a kernel that is 1 Mbyte or less and
5592 a root filesystem that is 3 Mbytes or less).
5593 </para></listitem>
5594 <listitem><para>Find the areas that are currently
5595 taking 90% of the space and concentrate on reducing
5596 those areas.
5597 </para></listitem>
5598 <listitem><para>Do not create any difficult "hacks"
5599 to achieve your goals.</para></listitem>
5600 <listitem><para>Leverage the device-specific
5601 options.</para></listitem>
5602 <listitem><para>Work in a separate layer so that you
5603 keep changes isolated.
5604 For information on how to create layers, see
5605 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
5606 </para></listitem>
5607 </itemizedlist>
5608 </para>
5609 </section>
5610
5611 <section id='understand-what-gives-your-image-size'>
5612 <title>Understand What Contributes to Your Image Size</title>
5613
5614 <para>
5615 It is easiest to have something to start with when creating
5616 your own distribution.
5617 You can use the Yocto Project out-of-the-box to create the
5618 <filename>poky-tiny</filename> distribution.
5619 Ultimately, you will want to make changes in your own
5620 distribution that are likely modeled after
5621 <filename>poky-tiny</filename>.
5622 <note>
5623 To use <filename>poky-tiny</filename> in your build,
5624 set the
5625 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
5626 variable in your
5627 <filename>local.conf</filename> file to "poky-tiny"
5628 as described in the
5629 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
5630 section.
5631 </note>
5632 </para>
5633
5634 <para>
5635 Understanding some memory concepts will help you reduce the
5636 system size.
5637 Memory consists of static, dynamic, and temporary memory.
5638 Static memory is the TEXT (code), DATA (initialized data
5639 in the code), and BSS (uninitialized data) sections.
5640 Dynamic memory represents memory that is allocated at runtime:
5641 stacks, hash tables, and so forth.
5642 Temporary memory is recovered after the boot process.
5643 This memory consists of memory used for decompressing
5644 the kernel and for the <filename>__init__</filename>
5645 functions.
5646 </para>
5647
5648 <para>
5649 To help you see where you currently are with kernel and root
5650 filesystem sizes, you can use two tools found in the
5651 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in
5652 the <filename>scripts/tiny/</filename> directory:
5653 <itemizedlist>
5654 <listitem><para><filename>ksize.py</filename>: Reports
5655 component sizes for the kernel build objects.
5656 </para></listitem>
5657 <listitem><para><filename>dirsize.py</filename>: Reports
5658 component sizes for the root filesystem.</para></listitem>
5659 </itemizedlist>
5660 This next tool and command help you organize configuration
5661 fragments and view file dependencies in a human-readable form:
5662 <itemizedlist>
5663 <listitem><para><filename>merge_config.sh</filename>:
5664 Helps you manage configuration files and fragments
5665 within the kernel.
5666 With this tool, you can merge individual configuration
5667 fragments together.
5668 The tool allows you to make overrides and warns you
5669 of any missing configuration options.
5670 The tool is ideal for allowing you to iterate on
5671 configurations, create minimal configurations, and
5672 create configuration files for different machines
5673 without having to duplicate your process.</para>
5674 <para>The <filename>merge_config.sh</filename> script is
5675 part of the Linux Yocto kernel Git repositories
5676 (i.e. <filename>linux-yocto-3.14</filename>,
5677 <filename>linux-yocto-3.10</filename>,
5678 <filename>linux-yocto-3.8</filename>, and so forth)
5679 in the
5680 <filename>scripts/kconfig</filename> directory.</para>
5681 <para>For more information on configuration fragments,
5682 see the
5683 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
5684 section in the Yocto Project Linux Kernel Development
5685 Manual.
5686 </para></listitem>
5687 <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>:
5688 Using the BitBake command with these options brings up
5689 a Dependency Explorer from which you can view file
5690 dependencies.
5691 Understanding these dependencies allows you to make
5692 informed decisions when cutting out various pieces of the
5693 kernel and root filesystem.</para></listitem>
5694 </itemizedlist>
5695 </para>
5696 </section>
5697
5698 <section id='trim-the-root-filesystem'>
5699 <title>Trim the Root Filesystem</title>
5700
5701 <para>
5702 The root filesystem is made up of packages for booting,
5703 libraries, and applications.
5704 To change things, you can configure how the packaging happens,
5705 which changes the way you build them.
5706 You can also modify the filesystem itself or select a different
5707 filesystem.
5708 </para>
5709
5710 <para>
5711 First, find out what is hogging your root filesystem by running the
5712 <filename>dirsize.py</filename> script from your root directory:
5713 <literallayout class='monospaced'>
5714 $ cd <replaceable>root-directory-of-image</replaceable>
5715 $ dirsize.py 100000 > dirsize-100k.log
5716 $ cat dirsize-100k.log
5717 </literallayout>
5718 You can apply a filter to the script to ignore files under
5719 a certain size.
5720 The previous example filters out any files below 100 Kbytes.
5721 The sizes reported by the tool are uncompressed, and thus
5722 will be smaller by a relatively constant factor in a
5723 compressed root filesystem.
5724 When you examine your log file, you can focus on areas of the
5725 root filesystem that take up large amounts of memory.
5726 </para>
5727
5728 <para>
5729 You need to be sure that what you eliminate does not cripple
5730 the functionality you need.
5731 One way to see how packages relate to each other is by using
5732 the Dependency Explorer UI with the BitBake command:
5733 <literallayout class='monospaced'>
5734 $ cd <replaceable>image-directory</replaceable>
5735 $ bitbake -u taskexp -g <replaceable>image</replaceable>
5736 </literallayout>
5737 Use the interface to select potential packages you wish to
5738 eliminate and see their dependency relationships.
5739 </para>
5740
5741 <para>
5742 When deciding how to reduce the size, get rid of packages that
5743 result in minimal impact on the feature set.
5744 For example, you might not need a VGA display.
5745 Or, you might be able to get by with <filename>devtmpfs</filename>
5746 and <filename>mdev</filename> instead of
5747 <filename>udev</filename>.
5748 </para>
5749
5750 <para>
5751 Use your <filename>local.conf</filename> file to make changes.
5752 For example, to eliminate <filename>udev</filename> and
5753 <filename>glib</filename>, set the following in the
5754 local configuration file:
5755 <literallayout class='monospaced'>
5756 VIRTUAL-RUNTIME_dev_manager = ""
5757 </literallayout>
5758 </para>
5759
5760 <para>
5761 Finally, you should consider exactly the type of root
5762 filesystem you need to meet your needs while also reducing
5763 its size.
5764 For example, consider <filename>cramfs</filename>,
5765 <filename>squashfs</filename>, <filename>ubifs</filename>,
5766 <filename>ext2</filename>, or an <filename>initramfs</filename>
5767 using <filename>initramfs</filename>.
5768 Be aware that <filename>ext3</filename> requires a 1 Mbyte
5769 journal.
5770 If you are okay with running read-only, you do not need this
5771 journal.
5772 </para>
5773
5774 <note>
5775 After each round of elimination, you need to rebuild your
5776 system and then use the tools to see the effects of your
5777 reductions.
5778 </note>
5779 </section>
5780
5781 <section id='trim-the-kernel'>
5782 <title>Trim the Kernel</title>
5783
5784 <para>
5785 The kernel is built by including policies for hardware-independent
5786 aspects.
5787 What subsystems do you enable?
5788 For what architecture are you building?
5789 Which drivers do you build by default?
5790 <note>You can modify the kernel source if you want to help
5791 with boot time.
5792 </note>
5793 </para>
5794
5795 <para>
5796 Run the <filename>ksize.py</filename> script from the top-level
5797 Linux build directory to get an idea of what is making up
5798 the kernel:
5799 <literallayout class='monospaced'>
5800 $ cd <replaceable>top-level-linux-build-directory</replaceable>
5801 $ ksize.py > ksize.log
5802 $ cat ksize.log
5803 </literallayout>
5804 When you examine the log, you will see how much space is
5805 taken up with the built-in <filename>.o</filename> files for
5806 drivers, networking, core kernel files, filesystem, sound,
5807 and so forth.
5808 The sizes reported by the tool are uncompressed, and thus
5809 will be smaller by a relatively constant factor in a compressed
5810 kernel image.
5811 Look to reduce the areas that are large and taking up around
5812 the "90% rule."
5813 </para>
5814
5815 <para>
5816 To examine, or drill down, into any particular area, use the
5817 <filename>-d</filename> option with the script:
5818 <literallayout class='monospaced'>
5819 $ ksize.py -d > ksize.log
5820 </literallayout>
5821 Using this option breaks out the individual file information
5822 for each area of the kernel (e.g. drivers, networking, and
5823 so forth).
5824 </para>
5825
5826 <para>
5827 Use your log file to see what you can eliminate from the kernel
5828 based on features you can let go.
5829 For example, if you are not going to need sound, you do not
5830 need any drivers that support sound.
5831 </para>
5832
5833 <para>
5834 After figuring out what to eliminate, you need to reconfigure
5835 the kernel to reflect those changes during the next build.
5836 You could run <filename>menuconfig</filename> and make all your
5837 changes at once.
5838 However, that makes it difficult to see the effects of your
5839 individual eliminations and also makes it difficult to replicate
5840 the changes for perhaps another target device.
5841 A better method is to start with no configurations using
5842 <filename>allnoconfig</filename>, create configuration
5843 fragments for individual changes, and then manage the
5844 fragments into a single configuration file using
5845 <filename>merge_config.sh</filename>.
5846 The tool makes it easy for you to iterate using the
5847 configuration change and build cycle.
5848 </para>
5849
5850 <para>
5851 Each time you make configuration changes, you need to rebuild
5852 the kernel and check to see what impact your changes had on
5853 the overall size.
5854 </para>
5855 </section>
5856
5857 <section id='remove-package-management-requirements'>
5858 <title>Remove Package Management Requirements</title>
5859
5860 <para>
5861 Packaging requirements add size to the image.
5862 One way to reduce the size of the image is to remove all the
5863 packaging requirements from the image.
5864 This reduction includes both removing the package manager
5865 and its unique dependencies as well as removing the package
5866 management data itself.
5867 </para>
5868
5869 <para>
5870 To eliminate all the packaging requirements for an image,
5871 be sure that "package-management" is not part of your
5872 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
5873 statement for the image.
5874 When you remove this feature, you are removing the package
5875 manager as well as its dependencies from the root filesystem.
5876 </para>
5877 </section>
5878
5879 <section id='look-for-other-ways-to-minimize-size'>
5880 <title>Look for Other Ways to Minimize Size</title>
5881
5882 <para>
5883 Depending on your particular circumstances, other areas that you
5884 can trim likely exist.
5885 The key to finding these areas is through tools and methods
5886 described here combined with experimentation and iteration.
5887 Here are a couple of areas to experiment with:
5888 <itemizedlist>
5889 <listitem><para><filename>glibc</filename>:
5890 In general, follow this process:
5891 <orderedlist>
5892 <listitem><para>Remove <filename>glibc</filename>
5893 features from
5894 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
5895 that you think you do not need.</para></listitem>
5896 <listitem><para>Build your distribution.
5897 </para></listitem>
5898 <listitem><para>If the build fails due to missing
5899 symbols in a package, determine if you can
5900 reconfigure the package to not need those
5901 features.
5902 For example, change the configuration to not
5903 support wide character support as is done for
5904 <filename>ncurses</filename>.
5905 Or, if support for those characters is needed,
5906 determine what <filename>glibc</filename>
5907 features provide the support and restore the
5908 configuration.
5909 </para></listitem>
5910 <listitem><para>Rebuild and repeat the process.
5911 </para></listitem>
5912 </orderedlist></para></listitem>
5913 <listitem><para><filename>busybox</filename>:
5914 For BusyBox, use a process similar as described for
5915 <filename>glibc</filename>.
5916 A difference is you will need to boot the resulting
5917 system to see if you are able to do everything you
5918 expect from the running system.
5919 You need to be sure to integrate configuration fragments
5920 into Busybox because BusyBox handles its own core
5921 features and then allows you to add configuration
5922 fragments on top.
5923 </para></listitem>
5924 </itemizedlist>
5925 </para>
5926 </section>
5927
5928 <section id='iterate-on-the-process'>
5929 <title>Iterate on the Process</title>
5930
5931 <para>
5932 If you have not reached your goals on system size, you need
5933 to iterate on the process.
5934 The process is the same.
5935 Use the tools and see just what is taking up 90% of the root
5936 filesystem and the kernel.
5937 Decide what you can eliminate without limiting your device
5938 beyond what you need.
5939 </para>
5940
5941 <para>
5942 Depending on your system, a good place to look might be
5943 Busybox, which provides a stripped down
5944 version of Unix tools in a single, executable file.
5945 You might be able to drop virtual terminal services or perhaps
5946 ipv6.
5947 </para>
5948 </section>
5949 </section>
5525 </section> 5950 </section>
5526 5951
5527 5952
@@ -7821,433 +8246,6 @@
7821 </para> 8246 </para>
7822 </section> 8247 </section>
7823 8248
7824 <section id='building-a-tiny-system'>
7825 <title>Building a Tiny System</title>
7826
7827 <para>
7828 Very small distributions have some significant advantages such
7829 as requiring less on-die or in-package memory (cheaper), better
7830 performance through efficient cache usage, lower power requirements
7831 due to less memory, faster boot times, and reduced development
7832 overhead.
7833 Some real-world examples where a very small distribution gives
7834 you distinct advantages are digital cameras, medical devices,
7835 and small headless systems.
7836 </para>
7837
7838 <para>
7839 This section presents information that shows you how you can
7840 trim your distribution to even smaller sizes than the
7841 <filename>poky-tiny</filename> distribution, which is around
7842 5 Mbytes, that can be built out-of-the-box using the Yocto Project.
7843 </para>
7844
7845 <section id='tiny-system-overview'>
7846 <title>Overview</title>
7847
7848 <para>
7849 The following list presents the overall steps you need to
7850 consider and perform to create distributions with smaller
7851 root filesystems, achieve faster boot times, maintain your critical
7852 functionality, and avoid initial RAM disks:
7853 <itemizedlist>
7854 <listitem><para>
7855 <link linkend='goals-and-guiding-principles'>Determine your goals and guiding principles.</link>
7856 </para></listitem>
7857 <listitem><para>
7858 <link linkend='understand-what-gives-your-image-size'>Understand what contributes to your image size.</link>
7859 </para></listitem>
7860 <listitem><para>
7861 <link linkend='trim-the-root-filesystem'>Reduce the size of the root filesystem.</link>
7862 </para></listitem>
7863 <listitem><para>
7864 <link linkend='trim-the-kernel'>Reduce the size of the kernel.</link>
7865 </para></listitem>
7866 <listitem><para>
7867 <link linkend='remove-package-management-requirements'>Eliminate packaging requirements.</link>
7868 </para></listitem>
7869 <listitem><para>
7870 <link linkend='look-for-other-ways-to-minimize-size'>Look for other ways to minimize size.</link>
7871 </para></listitem>
7872 <listitem><para>
7873 <link linkend='iterate-on-the-process'>Iterate on the process.</link>
7874 </para></listitem>
7875 </itemizedlist>
7876 </para>
7877 </section>
7878
7879 <section id='goals-and-guiding-principles'>
7880 <title>Goals and Guiding Principles</title>
7881
7882 <para>
7883 Before you can reach your destination, you need to know
7884 where you are going.
7885 Here is an example list that you can use as a guide when
7886 creating very small distributions:
7887 <itemizedlist>
7888 <listitem><para>Determine how much space you need
7889 (e.g. a kernel that is 1 Mbyte or less and
7890 a root filesystem that is 3 Mbytes or less).
7891 </para></listitem>
7892 <listitem><para>Find the areas that are currently
7893 taking 90% of the space and concentrate on reducing
7894 those areas.
7895 </para></listitem>
7896 <listitem><para>Do not create any difficult "hacks"
7897 to achieve your goals.</para></listitem>
7898 <listitem><para>Leverage the device-specific
7899 options.</para></listitem>
7900 <listitem><para>Work in a separate layer so that you
7901 keep changes isolated.
7902 For information on how to create layers, see
7903 the "<link linkend='understanding-and-creating-layers'>Understanding and Creating Layers</link>" section.
7904 </para></listitem>
7905 </itemizedlist>
7906 </para>
7907 </section>
7908
7909 <section id='understand-what-gives-your-image-size'>
7910 <title>Understand What Contributes to Your Image Size</title>
7911
7912 <para>
7913 It is easiest to have something to start with when creating
7914 your own distribution.
7915 You can use the Yocto Project out-of-the-box to create the
7916 <filename>poky-tiny</filename> distribution.
7917 Ultimately, you will want to make changes in your own
7918 distribution that are likely modeled after
7919 <filename>poky-tiny</filename>.
7920 <note>
7921 To use <filename>poky-tiny</filename> in your build,
7922 set the
7923 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO'><filename>DISTRO</filename></ulink>
7924 variable in your
7925 <filename>local.conf</filename> file to "poky-tiny"
7926 as described in the
7927 "<link linkend='creating-your-own-distribution'>Creating Your Own Distribution</link>"
7928 section.
7929 </note>
7930 </para>
7931
7932 <para>
7933 Understanding some memory concepts will help you reduce the
7934 system size.
7935 Memory consists of static, dynamic, and temporary memory.
7936 Static memory is the TEXT (code), DATA (initialized data
7937 in the code), and BSS (uninitialized data) sections.
7938 Dynamic memory represents memory that is allocated at runtime:
7939 stacks, hash tables, and so forth.
7940 Temporary memory is recovered after the boot process.
7941 This memory consists of memory used for decompressing
7942 the kernel and for the <filename>__init__</filename>
7943 functions.
7944 </para>
7945
7946 <para>
7947 To help you see where you currently are with kernel and root
7948 filesystem sizes, you can use two tools found in the
7949 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> in
7950 the <filename>scripts/tiny/</filename> directory:
7951 <itemizedlist>
7952 <listitem><para><filename>ksize.py</filename>: Reports
7953 component sizes for the kernel build objects.
7954 </para></listitem>
7955 <listitem><para><filename>dirsize.py</filename>: Reports
7956 component sizes for the root filesystem.</para></listitem>
7957 </itemizedlist>
7958 This next tool and command help you organize configuration
7959 fragments and view file dependencies in a human-readable form:
7960 <itemizedlist>
7961 <listitem><para><filename>merge_config.sh</filename>:
7962 Helps you manage configuration files and fragments
7963 within the kernel.
7964 With this tool, you can merge individual configuration
7965 fragments together.
7966 The tool allows you to make overrides and warns you
7967 of any missing configuration options.
7968 The tool is ideal for allowing you to iterate on
7969 configurations, create minimal configurations, and
7970 create configuration files for different machines
7971 without having to duplicate your process.</para>
7972 <para>The <filename>merge_config.sh</filename> script is
7973 part of the Linux Yocto kernel Git repositories
7974 (i.e. <filename>linux-yocto-3.14</filename>,
7975 <filename>linux-yocto-3.10</filename>,
7976 <filename>linux-yocto-3.8</filename>, and so forth)
7977 in the
7978 <filename>scripts/kconfig</filename> directory.</para>
7979 <para>For more information on configuration fragments,
7980 see the
7981 "<ulink url='&YOCTO_DOCS_KERNEL_DEV_URL;#creating-config-fragments'>Creating Configuration Fragments</ulink>"
7982 section in the Yocto Project Linux Kernel Development
7983 Manual.
7984 </para></listitem>
7985 <listitem><para><filename>bitbake -u taskexp -g <replaceable>bitbake_target</replaceable></filename>:
7986 Using the BitBake command with these options brings up
7987 a Dependency Explorer from which you can view file
7988 dependencies.
7989 Understanding these dependencies allows you to make
7990 informed decisions when cutting out various pieces of the
7991 kernel and root filesystem.</para></listitem>
7992 </itemizedlist>
7993 </para>
7994 </section>
7995
7996 <section id='trim-the-root-filesystem'>
7997 <title>Trim the Root Filesystem</title>
7998
7999 <para>
8000 The root filesystem is made up of packages for booting,
8001 libraries, and applications.
8002 To change things, you can configure how the packaging happens,
8003 which changes the way you build them.
8004 You can also modify the filesystem itself or select a different
8005 filesystem.
8006 </para>
8007
8008 <para>
8009 First, find out what is hogging your root filesystem by running the
8010 <filename>dirsize.py</filename> script from your root directory:
8011 <literallayout class='monospaced'>
8012 $ cd <replaceable>root-directory-of-image</replaceable>
8013 $ dirsize.py 100000 > dirsize-100k.log
8014 $ cat dirsize-100k.log
8015 </literallayout>
8016 You can apply a filter to the script to ignore files under
8017 a certain size.
8018 The previous example filters out any files below 100 Kbytes.
8019 The sizes reported by the tool are uncompressed, and thus
8020 will be smaller by a relatively constant factor in a
8021 compressed root filesystem.
8022 When you examine your log file, you can focus on areas of the
8023 root filesystem that take up large amounts of memory.
8024 </para>
8025
8026 <para>
8027 You need to be sure that what you eliminate does not cripple
8028 the functionality you need.
8029 One way to see how packages relate to each other is by using
8030 the Dependency Explorer UI with the BitBake command:
8031 <literallayout class='monospaced'>
8032 $ cd <replaceable>image-directory</replaceable>
8033 $ bitbake -u taskexp -g <replaceable>image</replaceable>
8034 </literallayout>
8035 Use the interface to select potential packages you wish to
8036 eliminate and see their dependency relationships.
8037 </para>
8038
8039 <para>
8040 When deciding how to reduce the size, get rid of packages that
8041 result in minimal impact on the feature set.
8042 For example, you might not need a VGA display.
8043 Or, you might be able to get by with <filename>devtmpfs</filename>
8044 and <filename>mdev</filename> instead of
8045 <filename>udev</filename>.
8046 </para>
8047
8048 <para>
8049 Use your <filename>local.conf</filename> file to make changes.
8050 For example, to eliminate <filename>udev</filename> and
8051 <filename>glib</filename>, set the following in the
8052 local configuration file:
8053 <literallayout class='monospaced'>
8054 VIRTUAL-RUNTIME_dev_manager = ""
8055 </literallayout>
8056 </para>
8057
8058 <para>
8059 Finally, you should consider exactly the type of root
8060 filesystem you need to meet your needs while also reducing
8061 its size.
8062 For example, consider <filename>cramfs</filename>,
8063 <filename>squashfs</filename>, <filename>ubifs</filename>,
8064 <filename>ext2</filename>, or an <filename>initramfs</filename>
8065 using <filename>initramfs</filename>.
8066 Be aware that <filename>ext3</filename> requires a 1 Mbyte
8067 journal.
8068 If you are okay with running read-only, you do not need this
8069 journal.
8070 </para>
8071
8072 <note>
8073 After each round of elimination, you need to rebuild your
8074 system and then use the tools to see the effects of your
8075 reductions.
8076 </note>
8077
8078
8079 </section>
8080
8081 <section id='trim-the-kernel'>
8082 <title>Trim the Kernel</title>
8083
8084 <para>
8085 The kernel is built by including policies for hardware-independent
8086 aspects.
8087 What subsystems do you enable?
8088 For what architecture are you building?
8089 Which drivers do you build by default?
8090 <note>You can modify the kernel source if you want to help
8091 with boot time.
8092 </note>
8093 </para>
8094
8095 <para>
8096 Run the <filename>ksize.py</filename> script from the top-level
8097 Linux build directory to get an idea of what is making up
8098 the kernel:
8099 <literallayout class='monospaced'>
8100 $ cd <replaceable>top-level-linux-build-directory</replaceable>
8101 $ ksize.py > ksize.log
8102 $ cat ksize.log
8103 </literallayout>
8104 When you examine the log, you will see how much space is
8105 taken up with the built-in <filename>.o</filename> files for
8106 drivers, networking, core kernel files, filesystem, sound,
8107 and so forth.
8108 The sizes reported by the tool are uncompressed, and thus
8109 will be smaller by a relatively constant factor in a compressed
8110 kernel image.
8111 Look to reduce the areas that are large and taking up around
8112 the "90% rule."
8113 </para>
8114
8115 <para>
8116 To examine, or drill down, into any particular area, use the
8117 <filename>-d</filename> option with the script:
8118 <literallayout class='monospaced'>
8119 $ ksize.py -d > ksize.log
8120 </literallayout>
8121 Using this option breaks out the individual file information
8122 for each area of the kernel (e.g. drivers, networking, and
8123 so forth).
8124 </para>
8125
8126 <para>
8127 Use your log file to see what you can eliminate from the kernel
8128 based on features you can let go.
8129 For example, if you are not going to need sound, you do not
8130 need any drivers that support sound.
8131 </para>
8132
8133 <para>
8134 After figuring out what to eliminate, you need to reconfigure
8135 the kernel to reflect those changes during the next build.
8136 You could run <filename>menuconfig</filename> and make all your
8137 changes at once.
8138 However, that makes it difficult to see the effects of your
8139 individual eliminations and also makes it difficult to replicate
8140 the changes for perhaps another target device.
8141 A better method is to start with no configurations using
8142 <filename>allnoconfig</filename>, create configuration
8143 fragments for individual changes, and then manage the
8144 fragments into a single configuration file using
8145 <filename>merge_config.sh</filename>.
8146 The tool makes it easy for you to iterate using the
8147 configuration change and build cycle.
8148 </para>
8149
8150 <para>
8151 Each time you make configuration changes, you need to rebuild
8152 the kernel and check to see what impact your changes had on
8153 the overall size.
8154 </para>
8155 </section>
8156
8157 <section id='remove-package-management-requirements'>
8158 <title>Remove Package Management Requirements</title>
8159
8160 <para>
8161 Packaging requirements add size to the image.
8162 One way to reduce the size of the image is to remove all the
8163 packaging requirements from the image.
8164 This reduction includes both removing the package manager
8165 and its unique dependencies as well as removing the package
8166 management data itself.
8167 </para>
8168
8169 <para>
8170 To eliminate all the packaging requirements for an image,
8171 be sure that "package-management" is not part of your
8172 <ulink url='&YOCTO_DOCS_REF_URL;#var-IMAGE_FEATURES'><filename>IMAGE_FEATURES</filename></ulink>
8173 statement for the image.
8174 When you remove this feature, you are removing the package
8175 manager as well as its dependencies from the root filesystem.
8176 </para>
8177 </section>
8178
8179 <section id='look-for-other-ways-to-minimize-size'>
8180 <title>Look for Other Ways to Minimize Size</title>
8181
8182 <para>
8183 Depending on your particular circumstances, other areas that you
8184 can trim likely exist.
8185 The key to finding these areas is through tools and methods
8186 described here combined with experimentation and iteration.
8187 Here are a couple of areas to experiment with:
8188 <itemizedlist>
8189 <listitem><para><filename>glibc</filename>:
8190 In general, follow this process:
8191 <orderedlist>
8192 <listitem><para>Remove <filename>glibc</filename>
8193 features from
8194 <ulink url='&YOCTO_DOCS_REF_URL;#var-DISTRO_FEATURES'><filename>DISTRO_FEATURES</filename></ulink>
8195 that you think you do not need.</para></listitem>
8196 <listitem><para>Build your distribution.
8197 </para></listitem>
8198 <listitem><para>If the build fails due to missing
8199 symbols in a package, determine if you can
8200 reconfigure the package to not need those
8201 features.
8202 For example, change the configuration to not
8203 support wide character support as is done for
8204 <filename>ncurses</filename>.
8205 Or, if support for those characters is needed,
8206 determine what <filename>glibc</filename>
8207 features provide the support and restore the
8208 configuration.
8209 </para></listitem>
8210 <listitem><para>Rebuild and repeat the process.
8211 </para></listitem>
8212 </orderedlist></para></listitem>
8213 <listitem><para><filename>busybox</filename>:
8214 For BusyBox, use a process similar as described for
8215 <filename>glibc</filename>.
8216 A difference is you will need to boot the resulting
8217 system to see if you are able to do everything you
8218 expect from the running system.
8219 You need to be sure to integrate configuration fragments
8220 into Busybox because BusyBox handles its own core
8221 features and then allows you to add configuration
8222 fragments on top.
8223 </para></listitem>
8224 </itemizedlist>
8225 </para>
8226 </section>
8227
8228 <section id='iterate-on-the-process'>
8229 <title>Iterate on the Process</title>
8230
8231 <para>
8232 If you have not reached your goals on system size, you need
8233 to iterate on the process.
8234 The process is the same.
8235 Use the tools and see just what is taking up 90% of the root
8236 filesystem and the kernel.
8237 Decide what you can eliminate without limiting your device
8238 beyond what you need.
8239 </para>
8240
8241 <para>
8242 Depending on your system, a good place to look might be
8243 Busybox, which provides a stripped down
8244 version of Unix tools in a single, executable file.
8245 You might be able to drop virtual terminal services or perhaps
8246 ipv6.
8247 </para>
8248 </section>
8249 </section>
8250
8251 <section id='building-images-for-more-than-one-machine'> 8249 <section id='building-images-for-more-than-one-machine'>
8252 <title>Building Images for More than One Machine</title> 8250 <title>Building Images for More than One Machine</title>
8253 8251