diff options
author | Scott Rifenbark <srifenbark@gmail.com> | 2018-03-21 09:04:24 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2018-03-25 09:41:13 +0100 |
commit | ce8c96481ea6aa3a391ac2936af6a472d903c4b4 (patch) | |
tree | 10558921370471d155d1378d20ab345eba1f9b92 /documentation/bsp-guide | |
parent | dcde1a9e336b0b52aa76c1c5a7a71f97f8c3e1e1 (diff) | |
download | openembedded-core-contrib-ce8c96481ea6aa3a391ac2936af6a472d903c4b4.tar.gz |
bsp-guide: Updated BSP terminolgy and BBLAYERS ordering
Fixed the way we refer to a BSP name. It is really
"meta-<bsp_root_name>" rather than "meta-<bsp_name>". The
name is the whole string and not just the root name.
Also added a tip on ordering the layers in the BBLAYERS
variable in the bblayers.conf file. Order is important.
(From yocto-docs rev: 9c56238295f5631c496377616ea98b860253e6f7)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/bsp-guide')
-rw-r--r-- | documentation/bsp-guide/bsp.xml | 110 |
1 files changed, 61 insertions, 49 deletions
diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 787dc7bff1..f9455ed861 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -38,10 +38,10 @@ Although not a strict requirement, BSP layers in the Yocto Project use the following well-established naming convention: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable> + meta-<replaceable>bsp_root_name</replaceable> </literallayout> The string "meta-" is prepended to the machine or platform name, which is - <replaceable>bsp_name</replaceable> in the above form. + <replaceable>bsp_root_name</replaceable> in the above form. <note><title>Tip</title> Because the BSP layer naming convention is well-established, it is advisable to follow it when creating layers. @@ -99,16 +99,16 @@ <para> The layer's base directory - (<filename>meta-<replaceable>bsp_name</replaceable></filename>) - is the root of the BSP Layer. - This root is what you add to the + (<filename>meta-<replaceable>bsp_root_name</replaceable></filename>) + is the root directory of the BSP Layer. + This directory is what you add to the <ulink url='&YOCTO_DOCS_REF_URL;#var-BBLAYERS'><filename>BBLAYERS</filename></ulink> variable in the <filename>conf/bblayers.conf</filename> file found in the <ulink url='&YOCTO_DOCS_REF_URL;#build-directory'>Build Directory</ulink>, which is established after you run the OpenEmbedded build environment setup script (i.e. <ulink url='&YOCTO_DOCS_REF_URL;#structure-core-script'><filename>&OE_INIT_FILE;</filename></ulink>). - Adding the root allows the + Adding the root directory allows the <ulink url='&YOCTO_DOCS_REF_URL;#build-system-term'>OpenEmbedded build system</ulink> to recognize the BSP layer and from it build an image. Here is an example: @@ -120,22 +120,34 @@ /usr/local/src/yocto/meta-mylayer \ " </literallayout> + <note><title>Tip</title> + Ordering and + <ulink url='&YOCTO_DOCS_REF_URL;#var-BBFILE_PRIORITY'><filename>BBFILE_PRIORITY</filename></ulink> + for the layers listed in <filename>BBLAYERS</filename> + matter. + For example, if multiple layers define a machine + configuration, the OpenEmbedded build system uses + the last layer searched given similar layer + priorities. + The build system works from the top-down through + the layers listed in <filename>BBLAYERS</filename>. + </note> </para> <para> - Some BSPs require additional layers on - top of the BSP's root layer in order to be functional. - For these cases, you also need to add those layers to the - <filename>BBLAYERS</filename> variable in order to build the BSP. - You must also specify in the "Dependencies" section of the BSP's - <filename>README</filename> file any requirements for additional - layers and, preferably, any - build instructions that might be contained elsewhere - in the <filename>README</filename> file. + Some BSPs require or depend on additional layers + beyond the BSP's root layer in order to be functional. + In this case, you need to specify these layers in the + <filename>README</filename> "Dependencies" section of the + BSP's root layer. + Additionally, if any build instructions exist for the + BSP, you must add them to the "Dependencies" section. </para> <para> Some layers function as a layer to hold other BSP layers. + These layers are knows as + "<ulink url='&YOCTO_DOCS_REF_URL;#term-container-layer'>container layers</ulink>". An example of this type of layer is the <filename>meta-intel</filename> layer. This layer contains BSP layers for the Intel-core2-32 @@ -365,17 +377,17 @@ realize that the actual file structures for specific BSPs could differ. <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/ - meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> - meta-<replaceable>bsp_name</replaceable>/README - meta-<replaceable>bsp_name</replaceable>/README.sources - meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> - meta-<replaceable>bsp_name</replaceable>/conf/layer.conf - meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf - meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* - meta-<replaceable>bsp_name</replaceable>/recipes-core/* - meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* - meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend + meta-<replaceable>bsp_root_name</replaceable>/ + meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable> + meta-<replaceable>bsp_root_name</replaceable>/README + meta-<replaceable>bsp_root_name</replaceable>/README.sources + meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable> + meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf + meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf + meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-core/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux-yocto_<replaceable>kernel_rev</replaceable>.bbappend </literallayout> </para> @@ -551,7 +563,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/<replaceable>bsp_license_file</replaceable> + meta-<replaceable>bsp_root_name</replaceable>/<replaceable>bsp_license_file</replaceable> </literallayout> </para> @@ -583,7 +595,7 @@ <para> You can find this file in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/README + meta-<replaceable>bsp_root_name</replaceable>/README </literallayout> </para> @@ -609,7 +621,7 @@ <para> You can find this file in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/README.sources + meta-<replaceable>bsp_root_name</replaceable>/README.sources </literallayout> </para> @@ -617,7 +629,7 @@ This file provides information on where to locate the BSP source files used to build the images (if any) that reside in - <filename>meta-<replaceable>bsp_name</replaceable>/binary</filename>. + <filename>meta-<replaceable>bsp_root_name</replaceable>/binary</filename>. Images in the <filename>binary</filename> would be images released with the BSP. The information in the <filename>README.sources</filename> @@ -639,7 +651,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/binary/<replaceable>bootable_images</replaceable> + meta-<replaceable>bsp_root_name</replaceable>/binary/<replaceable>bootable_images</replaceable> </literallayout> </para> @@ -677,7 +689,7 @@ <para> You can find this file in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/conf/layer.conf + meta-<replaceable>bsp_root_name</replaceable>/conf/layer.conf </literallayout> </para> @@ -692,7 +704,7 @@ In the following example, you would replace <replaceable>bsp</replaceable> with the actual name of the BSP (i.e. - <replaceable>bsp_name</replaceable> from the example + <replaceable>bsp_root_name</replaceable> from the example template). </para> @@ -752,7 +764,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/conf/machine/*.conf + meta-<replaceable>bsp_root_name</replaceable>/conf/machine/*.conf </literallayout> </para> @@ -819,7 +831,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/recipes-bsp/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-bsp/* </literallayout> </para> @@ -864,7 +876,7 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/recipes-graphics/* + meta-<replaceable>bsp_root_name</replaceable>/recipes-graphics/* </literallayout> </para> @@ -883,8 +895,8 @@ <para> You can find these files in the BSP Layer at: <literallayout class='monospaced'> - meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/linux*.bbappend - meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux/*.bb + meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/linux*.bbappend + meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux/*.bb </literallayout> </para> @@ -907,7 +919,7 @@ kernel recipe by using a similarly named append file, which is located in the BSP Layer for your target device (e.g. the - <filename>meta-<replaceable>bsp_name</replaceable>/recipes-kernel/linux</filename> directory). + <filename>meta-<replaceable>bsp_root_name</replaceable>/recipes-kernel/linux</filename> directory). </para> <para> @@ -915,7 +927,7 @@ <filename>linux-yocto_4.4.bb</filename> recipe to build the kernel. In other words, you have selected the kernel in your - <replaceable>bsp_name</replaceable><filename>.conf</filename> + <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file by adding <ulink url='&YOCTO_DOCS_REF_URL;#var-PREFERRED_PROVIDER'><filename>PREFERRED_PROVIDER</filename></ulink> and @@ -930,7 +942,7 @@ default, the <filename>PREFERRED_PROVIDER</filename> statement does not appear in the - <replaceable>bsp_name</replaceable><filename>.conf</filename> file. + <replaceable>bsp_root_name</replaceable><filename>.conf</filename> file. </note> You would use the <filename>linux-yocto_4.4.bbappend</filename> @@ -1308,7 +1320,7 @@ <listitem><para> <emphasis>License File:</emphasis> You must include a license file in the - <filename>meta-</filename><replaceable>bsp_name</replaceable> + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> directory. This license covers the BSP Metadata as a whole. You must specify which license to use since no @@ -1323,7 +1335,7 @@ <emphasis>README File:</emphasis> You must include a <filename>README</filename> file in the - <filename>meta-</filename><replaceable>bsp_name</replaceable> + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> directory. See the <ulink url='&YOCTO_GIT_URL;/cgit.cgi/meta-raspberrypi/tree/README'><filename>README</filename></ulink> @@ -1394,7 +1406,7 @@ <filename>binary</filename> directory, you must include a <filename>README.sources</filename> file in the - <filename>meta-</filename><replaceable>bsp_name</replaceable> + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> directory. This file specifies exactly where you can find the sources used to generate the binary images. @@ -1404,18 +1416,18 @@ You must include a <filename>conf/layer.conf</filename> file in the - <filename>meta-</filename><replaceable>bsp_name</replaceable> + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> directory. This file identifies the - <filename>meta-</filename><replaceable>bsp_name</replaceable> + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> BSP layer as a layer to the build system. </para></listitem> <listitem><para> <emphasis>Machine Configuration File:</emphasis> You must include one or more - <filename>conf/machine/</filename><replaceable>bsp_name</replaceable><filename>.conf</filename> + <filename>conf/machine/</filename><replaceable>bsp_root_name</replaceable><filename>.conf</filename> files in the - <filename>meta-</filename><replaceable>bsp_name</replaceable> + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> directory. These configuration files define machine targets that can be built using the BSP layer. @@ -1475,7 +1487,7 @@ within a <filename>binary/</filename> subdirectory located in the - <filename>meta-</filename><replaceable>bsp_name</replaceable> + <filename>meta-</filename><replaceable>bsp_root_name</replaceable> directory. <note> If you do include a bootable image as part |