diff options
| -rw-r--r-- | documentation/dev-manual/dev-manual-common-tasks.xml | 852 |
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 | ||