diff options
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r-- | documentation/dev-manual/dev-manual-start.xml | 134 |
1 files changed, 119 insertions, 15 deletions
diff --git a/documentation/dev-manual/dev-manual-start.xml b/documentation/dev-manual/dev-manual-start.xml index 4c6c441fe0..dc30659159 100644 --- a/documentation/dev-manual/dev-manual-start.xml +++ b/documentation/dev-manual/dev-manual-start.xml | |||
@@ -701,13 +701,16 @@ | |||
701 | </section> | 701 | </section> |
702 | </section> | 702 | </section> |
703 | 703 | ||
704 | <section id='performing-a-simple-build'> | 704 | <section id='dev-building-an-image'> |
705 | <title>Performing a Simple Build</title> | 705 | <title>Building an Image</title> |
706 | 706 | ||
707 | <para> | 707 | <para> |
708 | In the development environment, you need to build an image whenever | ||
709 | you change hardware support, add or change system libraries, or add | ||
710 | or change services that have dependencies. | ||
708 | Several methods exist that allow you to build an image within the | 711 | Several methods exist that allow you to build an image within the |
709 | Yocto Project. | 712 | Yocto Project. |
710 | This procedure shows how to build an image using BitBake from a | 713 | This section shows you how to build an image using BitBake from a |
711 | Linux host. | 714 | Linux host. |
712 | <note><title>Notes</title> | 715 | <note><title>Notes</title> |
713 | <itemizedlist> | 716 | <itemizedlist> |
@@ -715,7 +718,7 @@ | |||
715 | For information on how to build an image using | 718 | For information on how to build an image using |
716 | <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>, | 719 | <ulink url='&YOCTO_DOCS_REF_URL;#toaster-term'>Toaster</ulink>, |
717 | see the | 720 | see the |
718 | <ulink url='&YOCTO_DOCS_TOAST_URL;'>Yocto Project Toaster Manual</ulink>. | 721 | <ulink url='&YOCTO_DOCS_TOAST_URL;'>Toaster Manual</ulink>. |
719 | </para></listitem> | 722 | </para></listitem> |
720 | <listitem><para> | 723 | <listitem><para> |
721 | For information on how to use | 724 | For information on how to use |
@@ -724,6 +727,12 @@ | |||
724 | section in the Yocto Project Application Development and | 727 | section in the Yocto Project Application Development and |
725 | the Extensible Software Development Kit (eSDK) manual. | 728 | the Extensible Software Development Kit (eSDK) manual. |
726 | </para></listitem> | 729 | </para></listitem> |
730 | <listitem><para> | ||
731 | For a practical example on how to build an image using the | ||
732 | OpenEmbedded build system, see the | ||
733 | "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" | ||
734 | section of the Yocto Project Quick Start. | ||
735 | </para></listitem> | ||
727 | </itemizedlist> | 736 | </itemizedlist> |
728 | </note> | 737 | </note> |
729 | </para> | 738 | </para> |
@@ -736,9 +745,6 @@ | |||
736 | For detailed information on the build process using BitBake, see the | 745 | For detailed information on the build process using BitBake, see the |
737 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#images-dev-environment'>Images</ulink>" | 746 | "<ulink url='&YOCTO_DOCS_OVERVIEW_URL;#images-dev-environment'>Images</ulink>" |
738 | section in the Yocto Project Overview Manual. | 747 | section in the Yocto Project Overview Manual. |
739 | You can also reference the | ||
740 | "<ulink url='&YOCTO_DOCS_QS_URL;#qs-building-images'>Building Images</ulink>" | ||
741 | section in the Yocto Project Quick Start. | ||
742 | </para> | 748 | </para> |
743 | 749 | ||
744 | <para> | 750 | <para> |
@@ -757,14 +763,30 @@ | |||
757 | <emphasis>Initialize the Build Environment:</emphasis> | 763 | <emphasis>Initialize the Build Environment:</emphasis> |
758 | Initialize the build environment by sourcing the build | 764 | Initialize the build environment by sourcing the build |
759 | environment script (i.e. | 765 | environment script (i.e. |
760 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). | 766 | <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>): |
767 | <literallayout class='monospaced'> | ||
768 | $ source &OE_INIT_FILE; [<replaceable>build_dir</replaceable>] | ||
769 | </literallayout></para> | ||
770 | |||
771 | <para>When you use the initialization script, the | ||
772 | OpenEmbedded build system uses <filename>build</filename> as | ||
773 | the default Build Directory in your current work directory. | ||
774 | You can use a <replaceable>build_dir</replaceable> argument | ||
775 | with the script to specify a different build directory. | ||
776 | <note><title>Tip</title> | ||
777 | A common practice is to use a different Build Directory for | ||
778 | different targets. | ||
779 | For example, <filename>~/build/x86</filename> for a | ||
780 | <filename>qemux86</filename> target, and | ||
781 | <filename>~/build/arm</filename> for a | ||
782 | <filename>qemuarm</filename> target. | ||
783 | </note> | ||
761 | </para></listitem> | 784 | </para></listitem> |
762 | <listitem><para> | 785 | <listitem><para> |
763 | <emphasis>Make Sure Your <filename>local.conf</filename> | 786 | <emphasis>Make Sure Your <filename>local.conf</filename> |
764 | File is Correct:</emphasis> | 787 | File is Correct:</emphasis> |
765 | Ensure the <filename>conf/local.conf</filename> configuration | 788 | Ensure the <filename>conf/local.conf</filename> configuration |
766 | file, which is found in the | 789 | file, which is found in the Build Directory, |
767 | <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, | ||
768 | is set up how you want it. | 790 | is set up how you want it. |
769 | This file defines many aspects of the build environment | 791 | This file defines many aspects of the build environment |
770 | including the target machine architecture through the | 792 | including the target machine architecture through the |
@@ -772,18 +794,100 @@ | |||
772 | the packaging format used during the build | 794 | the packaging format used during the build |
773 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>), | 795 | (<ulink url='&YOCTO_DOCS_REF_URL;#var-PACKAGE_CLASSES'><filename>PACKAGE_CLASSES</filename></ulink>), |
774 | and a centralized tarball download directory through the | 796 | and a centralized tarball download directory through the |
775 | <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'>DL_DIR</ulink></filename> variable. | 797 | <ulink url='&YOCTO_DOCS_REF_URL;#var-DL_DIR'><filename>DL_DIR</filename></ulink> variable. |
776 | </para></listitem> | 798 | </para></listitem> |
777 | <listitem><para> | 799 | <listitem><para> |
778 | <emphasis>Build the Image:</emphasis> | 800 | <emphasis>Build the Image:</emphasis> |
779 | Build the image using the <filename>bitbake</filename> command. | 801 | Build the image using the <filename>bitbake</filename> command: |
780 | For example, the following command builds the | 802 | <literallayout class='monospaced'> |
803 | $ bitbake <replaceable>target</replaceable> | ||
804 | </literallayout> | ||
805 | <note> | ||
806 | For information on BitBake, see the | ||
807 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | ||
808 | </note> | ||
809 | The <replaceable>target</replaceable> is the name of the | ||
810 | recipe you want to build. | ||
811 | Common targets are the images in | ||
812 | <filename>meta/recipes-core/images</filename>, | ||
813 | <filename>meta/recipes-sato/images</filename>, etc. all found | ||
814 | in the | ||
815 | <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. | ||
816 | Or, the target can be the name of a recipe for a specific | ||
817 | piece of software such as BusyBox. | ||
818 | For more details about the images the OpenEmbedded build | ||
819 | system supports, see the | ||
820 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
821 | chapter in the Yocto Project Reference Manual.</para> | ||
822 | |||
823 | <para>As an example, the following command builds the | ||
781 | <filename>core-image-minimal</filename> image: | 824 | <filename>core-image-minimal</filename> image: |
782 | <literallayout class='monospaced'> | 825 | <literallayout class='monospaced'> |
783 | $ bitbake core-image-minimal | 826 | $ bitbake core-image-minimal |
784 | </literallayout> | 827 | </literallayout> |
785 | For information on BitBake, see the | 828 | Once an image has been built, it often needs to be installed. |
786 | <ulink url='&YOCTO_DOCS_BB_URL;'>BitBake User Manual</ulink>. | 829 | The images and kernels built by the OpenEmbedded build system |
830 | are placed in the Build Directory in | ||
831 | <filename class="directory">tmp/deploy/images</filename>. | ||
832 | For information on how to run pre-built images such as | ||
833 | <filename>qemux86</filename> and <filename>qemuarm</filename>, | ||
834 | see the | ||
835 | <ulink url='&YOCTO_DOCS_SDK_URL;'>Yocto Project Application Development and the Extensible Software Development Kit (eSDK)</ulink> | ||
836 | manual. | ||
837 | For information about how to install these images, see the | ||
838 | documentation for your particular board or machine. | ||
839 | <note><title>Build Notes</title> | ||
840 | <itemizedlist> | ||
841 | <listitem><para> | ||
842 | If you experience a build error due to resources | ||
843 | temporarily being unavailable and it appears you | ||
844 | should not be having this issue, it might be due | ||
845 | to the combination of a 4.3+ Linux kernel and | ||
846 | <filename>systemd</filename> version 228+ | ||
847 | (i.e. see this | ||
848 | <ulink url='http://unix.stackexchange.com/questions/253903/creating-threads-fails-with-resource-temporarily-unavailable-with-4-3-kernel'>link</ulink> | ||
849 | for information).</para> | ||
850 | |||
851 | <para>To work around this issue, you can try either | ||
852 | of the following: | ||
853 | <itemizedlist> | ||
854 | <listitem><para> | ||
855 | Try the build again. | ||
856 | </para></listitem> | ||
857 | <listitem><para> | ||
858 | Modify the "DefaultTasksMax" | ||
859 | <filename>systemd</filename> parameter | ||
860 | by uncommenting it and setting it to | ||
861 | "infinity". | ||
862 | You can find this parameter in the | ||
863 | <filename>system.conf</filename> file | ||
864 | located in | ||
865 | <filename>/etc/systemd</filename> | ||
866 | on most systems. | ||
867 | </para></listitem> | ||
868 | </itemizedlist> | ||
869 | </para></listitem> | ||
870 | <listitem><para> | ||
871 | Building an image without GNU General Public | ||
872 | License Version 3 (GPLv3), or similarly licensed, | ||
873 | components is supported for only minimal and | ||
874 | base images. | ||
875 | See the | ||
876 | "<ulink url='&YOCTO_DOCS_REF_URL;#ref-images'>Images</ulink>" | ||
877 | chapter in the Yocto Project Reference Manual | ||
878 | for more information. | ||
879 | </para></listitem> | ||
880 | <listitem><para> | ||
881 | When building an image using GPL components, | ||
882 | you need to maintain your original settings and | ||
883 | not switch back and forth applying different | ||
884 | versions of the GNU General Public License. | ||
885 | If you rebuild using different versions of GPL, | ||
886 | dependency errors might occur due to some components | ||
887 | not being rebuilt. | ||
888 | </para></listitem> | ||
889 | </itemizedlist> | ||
890 | </note> | ||
787 | </para></listitem> | 891 | </para></listitem> |
788 | </orderedlist> | 892 | </orderedlist> |
789 | </para> | 893 | </para> |