diff --git a/documentation/bsp-guide/bsp.xml b/documentation/bsp-guide/bsp.xml index 6ae3ff9804..7d3345e06a 100644 --- a/documentation/bsp-guide/bsp.xml +++ b/documentation/bsp-guide/bsp.xml @@ -1415,9 +1415,9 @@ 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 Reference - Manual for details on how to use these variables. + "Enabling Commercially Licensed Recipes" + section in the Yocto Project Overview 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 diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml index b141498763..075d0f6fdf 100644 --- a/documentation/dev-manual/dev-manual-common-tasks.xml +++ b/documentation/dev-manual/dev-manual-common-tasks.xml @@ -2128,8 +2128,8 @@ containing the current checksum. For more explanation and examples of how to set the LIC_FILES_CHKSUM variable, see the - "Tracking License Changes" - section in the Yocto Project Reference Manual. + "Tracking License Changes" + section in the Yocto Project Overview Manual. To determine the correct checksum string, you can list the appropriate files in the LIC_FILES_CHKSUM variable with @@ -3211,7 +3211,8 @@ The variable LIC_FILES_CHKSUM is used to track source license changes as described in the - "Tracking License Changes" section. + "Tracking License Changes" + section in the Yocto Project Overview Manual. You can quickly create Autotool-based recipes in a manner similar to the previous example. diff --git a/documentation/overview-manual/overview-concepts.xml b/documentation/overview-manual/overview-concepts.xml index a7d6d2f6fb..2f5c14eef6 100644 --- a/documentation/overview-manual/overview-concepts.xml +++ b/documentation/overview-manual/overview-concepts.xml @@ -1460,6 +1460,396 @@ +
+ Licenses + + + This section describes the mechanism by which the OpenEmbedded + build system tracks changes to licensing text. + The section also describes how to enable commercially licensed + recipes, which by default are disabled. + + + + For information that can help you maintain compliance with + various open source licensing during the lifecycle of the product, + see the + "Maintaining Open Source License Compliance During Your Project's Lifecycle" + section in the Yocto Project Development Tasks Manual. + + +
+ Tracking License Changes + + + The license of an upstream project might change in the future. + In order to prevent these changes going unnoticed, the + LIC_FILES_CHKSUM + variable tracks changes to the license text. The checksums are + validated at the end of the configure step, and if the + checksums do not match, the build will fail. + + +
+ Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable + + + The LIC_FILES_CHKSUM + variable contains checksums of the license text in the + source code for the recipe. + Following is an example of how to specify + LIC_FILES_CHKSUM: + + LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ + file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ + file://licfile2.txt;endline=50;md5=zzzz \ + ..." + + Notes + + + When using "beginline" and "endline", realize + that line numbering begins with one and not + zero. + Also, the included lines are inclusive (i.e. + lines five through and including 29 in the + previous example for + licfile1.txt). + + + When a license check fails, the selected license + text is included as part of the QA message. + Using this output, you can determine the exact + start and finish for the needed license text. + + + + + + + The build system uses the + S + variable as the default directory when searching files + listed in LIC_FILES_CHKSUM. + The previous example employs the default directory. + + + + Consider this next example: + + LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ + md5=bb14ed3c4cda583abc85401304b5cd4e" + LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" + + + + + The first line locates a file in + ${S}/src/ls.c and isolates lines five + through 16 as license text. + The second line refers to a file in + WORKDIR. + + + + Note that LIC_FILES_CHKSUM variable is + mandatory for all recipes, unless the + LICENSE variable is set to "CLOSED". + +
+ +
+ Explanation of Syntax + + + As mentioned in the previous section, the + LIC_FILES_CHKSUM variable lists all + the important files that contain the license text for the + source code. + It is possible to specify a checksum for an entire file, + or a specific section of a file (specified by beginning and + ending line numbers with the "beginline" and "endline" + parameters, respectively). + The latter is useful for source files with a license + notice header, README documents, and so forth. + If you do not use the "beginline" parameter, then it is + assumed that the text begins on the first line of the file. + Similarly, if you do not use the "endline" parameter, + it is assumed that the license text ends with the last + line of the file. + + + + The "md5" parameter stores the md5 checksum of the license + text. + If the license text changes in any way as compared to + this parameter then a mismatch occurs. + This mismatch triggers a build failure and notifies + the developer. + Notification allows the developer to review and address + the license text changes. + Also note that if a mismatch occurs during the build, + the correct md5 checksum is placed in the build log and + can be easily copied to the recipe. + + + + There is no limit to how many files you can specify using + the LIC_FILES_CHKSUM variable. + Generally, however, every project requires a few + specifications for license tracking. + Many projects have a "COPYING" file that stores the + license information for all the source code files. + This practice allows you to just track the "COPYING" + file as long as it is kept up to date. + Tips + + + If you specify an empty or invalid "md5" + parameter, BitBake returns an md5 mis-match + error and displays the correct "md5" parameter + value during the build. + The correct parameter is also captured in + the build log. + + + If the whole file contains only license text, + you do not need to use the "beginline" and + "endline" parameters. + + + + +
+
+ +
+ Enabling Commercially Licensed Recipes + + + By default, the OpenEmbedded build system disables + components that have commercial or other special licensing + requirements. + Such requirements are defined on a + recipe-by-recipe basis through the + LICENSE_FLAGS + variable definition in the affected recipe. + For instance, the + poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + recipe contains the following statement: + + LICENSE_FLAGS = "commercial" + + Here is a slightly more complicated example that contains both + an explicit recipe name and version (after variable expansion): + + LICENSE_FLAGS = "license_${PN}_${PV}" + + In order for a component restricted by a + LICENSE_FLAGS definition to be enabled and + included in an image, it needs to have a matching entry in the + global + LICENSE_FLAGS_WHITELIST + variable, which is a variable typically defined in your + local.conf file. + For example, to enable the + poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly + package, you could add either the string + "commercial_gst-plugins-ugly" or the more general string + "commercial" to LICENSE_FLAGS_WHITELIST. + See the + "License Flag Matching" + section for a full + explanation of how LICENSE_FLAGS matching + works. + Here is the example: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" + + Likewise, to additionally enable the package built from the + recipe containing + LICENSE_FLAGS = "license_${PN}_${PV}", + and assuming that the actual recipe name was + emgd_1.10.bb, the following string would + enable that package as well as the original + gst-plugins-ugly package: + + LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" + + As a convenience, you do not need to specify the complete + license string in the whitelist for every package. + You can use an abbreviated form, which consists + of just the first portion or portions of the license + string before the initial underscore character or characters. + A partial string will match any license that contains the + given string as the first portion of its license. + For example, the following whitelist string will also match + both of the packages previously mentioned as well as any other + packages that have licenses starting with "commercial" or + "license". + + LICENSE_FLAGS_WHITELIST = "commercial license" + + + +
+ License Flag Matching + + + License flag matching allows you to control what recipes + the OpenEmbedded build system includes in the build. + Fundamentally, the build system attempts to match + LICENSE_FLAGS + strings found in recipes against + LICENSE_FLAGS_WHITELIST + strings found in the whitelist. + A match causes the build system to include a recipe in the + build, while failure to find a match causes the build + system to exclude a recipe. + + + + In general, license flag matching is simple. + However, understanding some concepts will help you + correctly and effectively use matching. + + + + Before a flag + defined by a particular recipe is tested against the + contents of the whitelist, the expanded string + _${PN} is appended to the flag. + This expansion makes each + LICENSE_FLAGS value recipe-specific. + After expansion, the string is then matched against the + whitelist. + Thus, specifying + LICENSE_FLAGS = "commercial" + in recipe "foo", for example, results in the string + "commercial_foo". + And, to create a match, that string must appear in the + whitelist. + + + + Judicious use of the LICENSE_FLAGS + strings and the contents of the + LICENSE_FLAGS_WHITELIST variable + allows you a lot of flexibility for including or excluding + recipes based on licensing. + For example, you can broaden the matching capabilities by + using license flags string subsets in the whitelist. + + When using a string subset, be sure to use the part of + the expanded string that precedes the appended + underscore character (e.g. + usethispart_1.3, + usethispart_1.4, and so forth). + + For example, simply specifying the string "commercial" in + the whitelist matches any expanded + LICENSE_FLAGS definition that starts + with the string "commercial" such as "commercial_foo" and + "commercial_bar", which are the strings the build system + automatically generates for hypothetical recipes named + "foo" and "bar" assuming those recipes simply specify the + following: + + LICENSE_FLAGS = "commercial" + + Thus, you can choose to exhaustively + enumerate each license flag in the whitelist and + allow only specific recipes into the image, or + you can use a string subset that causes a broader range of + matches to allow a range of recipes into the image. + + + + This scheme works even if the + LICENSE_FLAGS string already + has _${PN} appended. + For example, the build system turns the license flag + "commercial_1.2_foo" into "commercial_1.2_foo_foo" and + would match both the general "commercial" and the specific + "commercial_1.2_foo" strings found in the whitelist, as + expected. + + + + Here are some other scenarios: + + + You can specify a versioned string in the recipe + such as "commercial_foo_1.2" in a "foo" recipe. + The build system expands this string to + "commercial_foo_1.2_foo". + Combine this license flag with a whitelist that has + the string "commercial" and you match the flag + along with any other flag that starts with the + string "commercial". + + + Under the same circumstances, you can use + "commercial_foo" in the whitelist and the build + system not only matches "commercial_foo_1.2" but + also matches any license flag with the string + "commercial_foo", regardless of the version. + + + You can be very specific and use both the + package and version parts in the whitelist (e.g. + "commercial_foo_1.2") to specifically match a + versioned recipe. + + + +
+ + +
+
+
x32 psABI diff --git a/documentation/ref-manual/ref-variables.xml b/documentation/ref-manual/ref-variables.xml index a971e2a8f9..8baa0c0f07 100644 --- a/documentation/ref-manual/ref-variables.xml +++ b/documentation/ref-manual/ref-variables.xml @@ -7908,8 +7908,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" LICENSE is set to "CLOSED"). For more information, see the - " - Tracking License Changes" section. + "Tracking License Changes" + section in the Yocto Project Overview Manual. @@ -8044,8 +8044,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" require additional licenses in order to be used in a commercial product. For more information, see the - "Enabling Commercially Licensed Recipes" - section. + "Enabling Commercially Licensed Recipes" + section in the Yocto Project Overview Manual. @@ -8064,8 +8064,8 @@ recipes-graphics/xorg-font/font-alias_1.0.3.bb:PR = "${INC_PR}.3" This practice is otherwise known as "whitelisting" license flags. For more information, see the - Enabling Commercially Licensed Recipes" - section. + Enabling Commercially Licensed Recipes" + section in the Yocto Project Overview Manual. diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index ba0b27ddc9..3827366dcb 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml @@ -13,363 +13,6 @@ x32, Wayland support, and Licenses. -
- Licenses - - - This section describes the mechanism by which the OpenEmbedded build system - tracks changes to licensing text. - The section also describes how to enable commercially licensed recipes, - which by default are disabled. - - - - For information that can help you maintain compliance with various open - source licensing during the lifecycle of the product, see the - "Maintaining Open Source License Compliance During Your Project's Lifecycle" - section in the Yocto Project Development Tasks Manual. - - -
- Tracking License Changes - - - The license of an upstream project might change in the future. - In order to prevent these changes going unnoticed, the - LIC_FILES_CHKSUM - variable tracks changes to the license text. The checksums are validated at the end of the - configure step, and if the checksums do not match, the build will fail. - - -
- Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable - - - The LIC_FILES_CHKSUM - variable contains checksums of the license text in the source - code for the recipe. - Following is an example of how to specify - LIC_FILES_CHKSUM: - - LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \ - file://licfile1.txt;beginline=5;endline=29;md5=yyyy \ - file://licfile2.txt;endline=50;md5=zzzz \ - ..." - - Notes - - - When using "beginline" and "endline", realize that - line numbering begins with one and not zero. - Also, the included lines are inclusive (i.e. lines - five through and including 29 in the previous - example for licfile1.txt). - - - When a license check fails, the selected license - text is included as part of the QA message. - Using this output, you can determine the exact - start and finish for the needed license text. - - - - - - - The build system uses the - S variable as - the default directory when searching files listed in - LIC_FILES_CHKSUM. - The previous example employs the default directory. - - - - Consider this next example: - - LIC_FILES_CHKSUM = "file://src/ls.c;beginline=5;endline=16;\ - md5=bb14ed3c4cda583abc85401304b5cd4e" - LIC_FILES_CHKSUM = "file://${WORKDIR}/license.html;md5=5c94767cedb5d6987c902ac850ded2c6" - - - - - The first line locates a file in - ${S}/src/ls.c and isolates lines five - through 16 as license text. - The second line refers to a file in - WORKDIR. - - - Note that LIC_FILES_CHKSUM variable is - mandatory for all recipes, unless the - LICENSE variable is set to "CLOSED". - -
- -
- Explanation of Syntax - - As mentioned in the previous section, the - LIC_FILES_CHKSUM variable lists all the - important files that contain the license text for the source code. - It is possible to specify a checksum for an entire file, or a specific section of a - file (specified by beginning and ending line numbers with the "beginline" and "endline" - parameters, respectively). - The latter is useful for source files with a license notice header, - README documents, and so forth. - If you do not use the "beginline" parameter, then it is assumed that the text begins on the - first line of the file. - Similarly, if you do not use the "endline" parameter, it is assumed that the license text - ends with the last line of the file. - - - - The "md5" parameter stores the md5 checksum of the license text. - If the license text changes in any way as compared to this parameter - then a mismatch occurs. - This mismatch triggers a build failure and notifies the developer. - Notification allows the developer to review and address the license text changes. - Also note that if a mismatch occurs during the build, the correct md5 - checksum is placed in the build log and can be easily copied to the recipe. - - - - There is no limit to how many files you can specify using the - LIC_FILES_CHKSUM variable. - Generally, however, every project requires a few specifications for license tracking. - Many projects have a "COPYING" file that stores the license information for all the source - code files. - This practice allows you to just track the "COPYING" file as long as it is kept up to date. - - - - If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match - error and displays the correct "md5" parameter value during the build. - The correct parameter is also captured in the build log. - - - - If the whole file contains only license text, you do not need to use the "beginline" and - "endline" parameters. - -
-
- -
- Enabling Commercially Licensed Recipes - - - By default, the OpenEmbedded build system disables - components that have commercial or other special licensing - requirements. - Such requirements are defined on a - recipe-by-recipe basis through the - LICENSE_FLAGS - variable definition in the affected recipe. - For instance, the - poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly - recipe contains the following statement: - - LICENSE_FLAGS = "commercial" - - Here is a slightly more complicated example that contains both an - explicit recipe name and version (after variable expansion): - - LICENSE_FLAGS = "license_${PN}_${PV}" - - In order for a component restricted by a LICENSE_FLAGS - definition to be enabled and included in an image, it - needs to have a matching entry in the global - LICENSE_FLAGS_WHITELIST - variable, which is a variable - typically defined in your local.conf file. - For example, to enable - the poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly - package, you could add either the string - "commercial_gst-plugins-ugly" or the more general string - "commercial" to LICENSE_FLAGS_WHITELIST. - See the - "License Flag Matching" section - for a full explanation of how LICENSE_FLAGS matching works. - Here is the example: - - LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly" - - Likewise, to additionally enable the package built from the recipe containing - LICENSE_FLAGS = "license_${PN}_${PV}", and assuming - that the actual recipe name was emgd_1.10.bb, - the following string would enable that package as well as - the original gst-plugins-ugly package: - - LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10" - - As a convenience, you do not need to specify the complete license string - in the whitelist for every package. - You can use an abbreviated form, which consists - of just the first portion or portions of the license string before - the initial underscore character or characters. - A partial string will match - any license that contains the given string as the first - portion of its license. - For example, the following - whitelist string will also match both of the packages - previously mentioned as well as any other packages that have - licenses starting with "commercial" or "license". - - LICENSE_FLAGS_WHITELIST = "commercial license" - - - -
- License Flag Matching - - - License flag matching allows you to control what recipes the - OpenEmbedded build system includes in the build. - Fundamentally, the build system attempts to match - LICENSE_FLAGS - strings found in recipes against - LICENSE_FLAGS_WHITELIST - strings found in the whitelist. - A match causes the build system to include a recipe in the - build, while failure to find a match causes the build system to - exclude a recipe. - - - - In general, license flag matching is simple. - However, understanding some concepts will help you - correctly and effectively use matching. - - - - Before a flag - defined by a particular recipe is tested against the - contents of the whitelist, the expanded string - _${PN} is appended to the flag. - This expansion makes each LICENSE_FLAGS - value recipe-specific. - After expansion, the string is then matched against the - whitelist. - Thus, specifying - LICENSE_FLAGS = "commercial" - in recipe "foo", for example, results in the string - "commercial_foo". - And, to create a match, that string must appear in the - whitelist. - - - - Judicious use of the LICENSE_FLAGS - strings and the contents of the - LICENSE_FLAGS_WHITELIST variable - allows you a lot of flexibility for including or excluding - recipes based on licensing. - For example, you can broaden the matching capabilities by - using license flags string subsets in the whitelist. - When using a string subset, be sure to use the part of - the expanded string that precedes the appended underscore - character (e.g. usethispart_1.3, - usethispart_1.4, and so forth). - - For example, simply specifying the string "commercial" in - the whitelist matches any expanded - LICENSE_FLAGS definition that starts with - the string "commercial" such as "commercial_foo" and - "commercial_bar", which are the strings the build system - automatically generates for hypothetical recipes named - "foo" and "bar" assuming those recipes simply specify the - following: - - LICENSE_FLAGS = "commercial" - - Thus, you can choose to exhaustively - enumerate each license flag in the whitelist and - allow only specific recipes into the image, or - you can use a string subset that causes a broader range of - matches to allow a range of recipes into the image. - - - - This scheme works even if the - LICENSE_FLAGS string already - has _${PN} appended. - For example, the build system turns the license flag - "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would - match both the general "commercial" and the specific - "commercial_1.2_foo" strings found in the whitelist, as - expected. - - - - Here are some other scenarios: - - You can specify a versioned string in the - recipe such as "commercial_foo_1.2" in a "foo" recipe. - The build system expands this string to - "commercial_foo_1.2_foo". - Combine this license flag with a whitelist that has - the string "commercial" and you match the flag along - with any other flag that starts with the string - "commercial". - Under the same circumstances, you can - use "commercial_foo" in the whitelist and the - build system not only matches "commercial_foo_1.2" but - also matches any license flag with the string - "commercial_foo", regardless of the version. - - You can be very specific and use both the - package and version parts in the whitelist (e.g. - "commercial_foo_1.2") to specifically match a - versioned recipe. - - -
- - -
-