From 7f141cf9a0e357bcd11ad50d7b40cea5a388df3c Mon Sep 17 00:00:00 2001 From: Scott Rifenbark Date: Thu, 8 Mar 2018 13:43:53 -0800 Subject: bsp-guide: Minor edits to the licensing section. (From yocto-docs rev: a7d13e2e9f9a947e65f969422202f04784724063) Signed-off-by: Scott Rifenbark Signed-off-by: Richard Purdie --- documentation/bsp-guide/bsp.xml | 416 ++++++++++++++++++++++------------------ 1 file changed, 232 insertions(+), 184 deletions(-) (limited to 'documentation') diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 72b065dad3..1edbc049de 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -1425,39 +1425,55 @@ Released BSP Recommendations - Following are recommendations for a released BSP that conforms to the - Yocto Project: + Following are recommendations for released BSPs that + conform to the Yocto Project: - Bootable Images: - BSP releases - can contain one or more bootable images. - Including bootable images allows users to easily try out the BSP - on their own hardware. - In some cases, it might not be convenient to include a - bootable image. - In this case, you might want to make two versions of the - BSP available: one that contains binary images, and one - that does not. - The version that does not contain bootable images avoids - unnecessary download times for users not interested in the images. - - If you need to distribute a BSP and include bootable images or build kernel and - filesystems meant to allow users to boot the BSP for evaluation - purposes, you should put the images and artifacts within a - binary/ subdirectory located in the - meta-bsp_name directory. - If you do include a bootable image as part of the BSP and the image - was built by software covered by the GPL or other open source licenses, - it is your responsibility to understand - and meet all licensing requirements, which could include distribution - of source files. - Use a Yocto Linux Kernel: - Kernel recipes in the BSP should be based on a Yocto Linux kernel. - Basing your recipes on these kernels reduces the costs for maintaining - the BSP and increases its scalability. - See the Yocto Linux Kernel category in the + + Bootable Images: + Released BSPs can contain one or more bootable + images. + Including bootable images allows users to easily + try out the BSP using their own hardware. + + In some cases, it might not be convenient + to include a bootable image. + If so, you might want to make two versions of the + BSP available: one that contains binary images, and + one that does not. + The version that does not contain bootable images + avoids unnecessary download times for users not + interested in the images. + + If you need to distribute a BSP and include + bootable images or build kernel and filesystems + meant to allow users to boot the BSP for evaluation + purposes, you should put the images and artifacts + within a + binary/ subdirectory located + in the + meta-bsp_name + directory. + + If you do include a bootable image as part + of the BSP and the image was built by software + covered by the GPL or other open source licenses, + it is your responsibility to understand + and meet all licensing requirements, which could + include distribution of source files. + + + + Use a Yocto Linux Kernel: + Kernel recipes in the BSP should be based on a + Yocto Linux kernel. + Basing your recipes on these kernels reduces + the costs for maintaining the BSP and increases + its scalability. + See the Yocto Linux Kernel + category in the Source Repositories - for these kernels. + for these kernels. + @@ -1467,78 +1483,94 @@ Customizing a Recipe for a BSP - If you plan on customizing a recipe for a particular BSP, you need to do the - following: - - Create a .bbappend - file for the modified recipe. - For information on using append files, see the - "Using .bbappend Files in Your Layer" - section in the Yocto Project Development Tasks Manual. - - - Ensure your directory structure in the BSP layer - that supports your machine is such that it can be found - by the build system. - See the example later in this section for more information. - - - Put the append file in a directory whose name matches - the machine's name and is located in an appropriate - sub-directory inside the BSP layer (i.e. - recipes-bsp, recipes-graphics, - recipes-core, and so forth). - - Place the BSP-specific files in the proper directory - inside the BSP layer. - How expansive the layer is affects where you must place these files. - For example, if your layer supports several different machine types, - you need to be sure your layer's directory structure includes hierarchy - that separates the files out according to machine. - If your layer does not support multiple machines, the layer would not - have that additional hierarchy and the files would obviously not be - able to reside in a machine-specific directory. - - - - - - Following is a specific example to help you better understand the process. - Consider an example that customizes a recipe by adding - a BSP-specific configuration file named interfaces to the - init-ifupdown_1.0.bb recipe for machine "xyz" where the - BSP layer also supports several other machines. - Do the following: - - Edit the init-ifupdown_1.0.bbappend file so that it - contains the following: - + If you plan on customizing a recipe for a particular BSP, + you need to do the following: + + + Create a *.bbappend file for + the modified recipe. + For information on using append files, see the + "Using .bbappend Files in Your Layer" + section in the Yocto Project Development Tasks + Manual. + + + Ensure your directory structure in the BSP layer + that supports your machine is such that the + OpenEmbedded build system can find it. + See the example later in this section for more + information. + + + Put the append file in a directory whose name matches + the machine's name and is located in an appropriate + sub-directory inside the BSP layer (i.e. + recipes-bsp, + recipes-graphics, + recipes-core, and so forth). + + + Place the BSP-specific files in the proper + directory inside the BSP layer. + How expansive the layer is affects where you must + place these files. + For example, if your layer supports several + different machine types, you need to be sure your + layer's directory structure includes hierarchy + that separates the files according to machine. + If your layer does not support multiple machines, + the layer would not have that additional hierarchy + and the files would obviously not be able to reside + in a machine-specific directory. + + + + + + Following is a specific example to help you better understand + the process. + This example customizes customizes a recipe by adding a + BSP-specific configuration file named + interfaces to the + init-ifupdown_1.0.bb recipe for machine + "xyz" where the BSP layer also supports several other + machines: + + + Edit the + init-ifupdown_1.0.bbappend file + so that it contains the following: + FILESEXTRAPATHS_prepend := "${THISDIR}/files:" - - The append file needs to be in the - meta-xyz/recipes-core/init-ifupdown directory. - - Create and place the new interfaces - configuration file in the BSP's layer here: - + + The append file needs to be in the + meta-xyz/recipes-core/init-ifupdown + directory. + + + Create and place the new + interfaces configuration file in + the BSP's layer here: + meta-xyz/recipes-core/init-ifupdown/files/xyz-machine-one/interfaces - - - If the meta-xyz layer did not support - multiple machines, you would place the - interfaces configuration file in the - layer here: - + + + If the meta-xyz layer did + not support multiple machines, you would place + the interfaces configuration + file in the layer here: + meta-xyz/recipes-core/init-ifupdown/files/interfaces - - - The - FILESEXTRAPATHS - variable in the append files extends the search path - the build system uses to find files during the build. - Consequently, for this example you need to have the - files directory in the same location - as your append file. + + + The + FILESEXTRAPATHS + variable in the append files extends the search path + the build system uses to find files during the build. + Consequently, for this example you need to have the + files directory in the same + location as your append file. + @@ -1547,115 +1579,131 @@ BSP Licensing Considerations - In some cases, a BSP contains separately licensed Intellectual Property (IP) - for a component or components. - For these cases, you are required to accept the terms of a commercial or other - type of license that requires some kind of explicit End User License Agreement (EULA). - Once the license is accepted, the OpenEmbedded build system can then build and - include the corresponding component in the final BSP image. - If the BSP is available as a pre-built image, you can download the image after - agreeing to the license or EULA. + In some cases, a BSP contains separately licensed + Intellectual Property (IP) for a component or components. + For these cases, you are required to accept the terms + of a commercial or other type of license that requires + some kind of explicit End User License Agreement (EULA). + Once you accept the license, the OpenEmbedded build system + can then build and include the corresponding component + in the final BSP image. + If the BSP is available as a pre-built image, you can + download the image after agreeing to the license or EULA. - You could find that some separately licensed components that are essential - for normal operation of the system might not have an unencumbered (or free) - substitute. - Without these essential components, the system would be non-functional. - Then again, you might find that other licensed components that are simply - 'good-to-have' or purely elective do have an unencumbered, free replacement - component that you can use rather than agreeing to the separately licensed component. - Even for components essential to the system, you might find an unencumbered component - that is not identical but will work as a less-capable version of the - licensed version in the BSP recipe. + You could find that some separately licensed components + that are essential for normal operation of the system might + not have an unencumbered (or free) substitute. + Without these essential components, the system would be + non-functional. + Then again, you might find that other licensed components + that are simply 'good-to-have' or purely elective do have + an unencumbered, free replacement component that you can + use rather than agreeing to the separately licensed + component. + Even for components essential to the system, you might + find an unencumbered component that is not identical but + will work as a less-capable version of the licensed version + in the BSP recipe. - For cases where you can substitute a free component and still - maintain the system's functionality, the "Downloads" page from the - Yocto Project website's - makes available de-featured BSPs - that are completely free of any IP encumbrances. + For cases where you can substitute a free component and + still maintain the system's functionality, the "DOWNLOADS" + selection from the "SOFTWARE" tab on the + Yocto Project website + makes available de-featured BSPs that are completely free + of any IP encumbrances. For these cases, you can use the substitution directly and without any further licensing requirements. - If present, these fully de-featured BSPs are named appropriately - different as compared to the names of the respective - encumbered BSPs. - If available, these substitutions are your - simplest and most preferred options. - Use of these substitutions of course assumes the resulting functionality meets - system requirements. - - - - If however, a non-encumbered version is unavailable or - it provides unsuitable functionality or quality, you can use an encumbered - version. + If present, these fully de-featured BSPs are named + appropriately different as compared to the names of their + respective encumbered BSPs. + If available, these substitutions are your simplest and + most preferred options. + Obviously, use of these substitutions assumes the resulting + functionality meets system requirements. + + If however, a non-encumbered version is unavailable or + it provides unsuitable functionality or quality, you can + use an encumbered version. + - A couple different methods exist within the OpenEmbedded build system to - satisfy the licensing requirements for an encumbered BSP. + A couple different methods exist within the OpenEmbedded + build system to satisfy the licensing requirements for an + encumbered BSP. The following list describes them in order of preference: - Use the + + Use the LICENSE_FLAGS - variable to define the recipes that have commercial or other - types of specially-licensed packages: - For each of those recipes, you can - specify a matching license string in a + Variable to Define the Recipes that Have Commercial + or Other Types of Specially-Licensed Packages: + For each of those recipes, you can specify a + matching license string in a local.conf variable named LICENSE_FLAGS_WHITELIST. - Specifying the matching license string signifies that you agree to the license. - Thus, the build system can build the corresponding recipe and include - the component in the image. + Specifying the matching license string signifies + that you agree to the license. + Thus, the build system can build the corresponding + recipe and include the component in the image. See the "Enabling Commercially Licensed Recipes" - section in the Yocto Project Concepts Manual for details on how - to use these variables. + section in the Yocto Project Concepts Manual for + details on how to use these variables. + If you build as you normally would, without specifying any recipes in the - LICENSE_FLAGS_WHITELIST, the build stops and - provides you with the list of recipes that you have - tried to include in the image that need entries in - the LICENSE_FLAGS_WHITELIST. - Once you enter the appropriate license flags into the whitelist, - restart the build to continue where it left off. + LICENSE_FLAGS_WHITELIST, the + build stops and provides you with the list of recipes + that you have tried to include in the image that + need entries in the + LICENSE_FLAGS_WHITELIST. + Once you enter the appropriate license flags into + the whitelist, restart the build to continue where + it left off. During the build, the prompt will not appear again since you have satisfied the requirement. - Once the appropriate license flags are on the white list - in the LICENSE_FLAGS_WHITELIST variable, you - can build the encumbered image with no change at all - to the normal build process. - Get a pre-built version of the BSP: - You can get this type of BSP by visiting the - "Downloads" page of the + + Once the appropriate license flags are on the + white list in the + LICENSE_FLAGS_WHITELIST variable, + you can build the encumbered image with no change + at all to the normal build process. + + + Get a Pre-Built Version of the BSP: + You can get this type of BSP by selecting the + "DOWNLOADS" item from the "SOFTWARE" tab on the Yocto Project website. - You can download BSP tarballs that contain proprietary components - after agreeing to the licensing - requirements of each of the individually encumbered - packages as part of the download process. - Obtaining the BSP this way allows you to access an encumbered - image immediately after agreeing to the + You can download BSP tarballs that contain + proprietary components after agreeing to the + licensing requirements of each of the individually + encumbered packages as part of the download process. + Obtaining the BSP this way allows you to access an + encumbered image immediately after agreeing to the click-through license agreements presented by the website. - Note that if you want to build the image - yourself using the recipes contained within the BSP - tarball, you will still need to create an - appropriate LICENSE_FLAGS_WHITELIST to match the - encumbered recipes in the BSP. + If you want to build the image yourself using + the recipes contained within the BSP tarball, + you will still need to create an appropriate + LICENSE_FLAGS_WHITELIST + to match the encumbered recipes in the BSP. + + + Pre-compiled images are bundled with a time-limited + kernel that runs for a predetermined amount of time + (10 days) before it forces the system to reboot. + This limitation is meant to discourage direct + redistribution of the image. + You must eventually rebuild the image if you want + to remove this restriction. + - - - Pre-compiled images are bundled with - a time-limited kernel that runs for a - predetermined amount of time (10 days) before it forces - the system to reboot. - This limitation is meant to discourage direct redistribution - of the image. - You must eventually rebuild the image if you want to remove this restriction. -
@@ -1818,7 +1866,7 @@ IF THERE IS A LAUNDRY LIST OF ITEMS THAT NEED DEFINITION OR GET SET UP AS A RESULT OF THIS PROCEDURE, LIST THEM HERE.] - [PAREMETER 1] + [PARAMETER 1] [PARAMETER 2] [PARAMETER 3] [PARAMETER 4] @@ -1887,7 +1935,7 @@