diff options
author | Scott Rifenbark <scott.m.rifenbark@intel.com> | 2013-03-27 08:11:41 -0700 |
---|---|---|
committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2013-04-04 14:12:52 +0100 |
commit | cf6887d91485ffbf6f94978627296234a2d37a5f (patch) | |
tree | 937e51a4dec165278b45a9b947b9ea28babde226 /documentation/ref-manual | |
parent | 30cdf93d0c3791a2463f99963daf253f3d093fb1 (diff) | |
download | poky-cf6887d91485ffbf6f94978627296234a2d37a5f.tar.gz |
ref-manual: rewrite of license flags matching section.
This whole section was very complicated and difficult to follow.
I have rewritten it to clear it up.
(From yocto-docs rev: 6ad1828eaa3e91b850696590cc732485a52f4cb6)
Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/ref-manual')
-rw-r--r-- | documentation/ref-manual/technical-details.xml | 156 |
1 files changed, 83 insertions, 73 deletions
diff --git a/documentation/ref-manual/technical-details.xml b/documentation/ref-manual/technical-details.xml index d66d7050a1..58a6b53744 100644 --- a/documentation/ref-manual/technical-details.xml +++ b/documentation/ref-manual/technical-details.xml | |||
@@ -7,7 +7,7 @@ | |||
7 | 7 | ||
8 | <para> | 8 | <para> |
9 | This chapter provides technical details for various parts of the Yocto Project. | 9 | This chapter provides technical details for various parts of the Yocto Project. |
10 | Currently, topics include Yocto Project components, | 10 | Currently, topics include Yocto Project components, |
11 | shared state (sstate) cache, x32, and Licenses. | 11 | shared state (sstate) cache, x32, and Licenses. |
12 | </para> | 12 | </para> |
13 | 13 | ||
@@ -17,7 +17,7 @@ | |||
17 | <para> | 17 | <para> |
18 | The BitBake task executor together with various types of configuration files form the | 18 | The BitBake task executor together with various types of configuration files form the |
19 | OpenEmbedded Core. | 19 | OpenEmbedded Core. |
20 | This section overviews these by describing what they are used for | 20 | This section overviews these by describing what they are used for |
21 | and how they interact. | 21 | and how they interact. |
22 | </para> | 22 | </para> |
23 | 23 | ||
@@ -126,8 +126,8 @@ | |||
126 | <title>Classes</title> | 126 | <title>Classes</title> |
127 | 127 | ||
128 | <para> | 128 | <para> |
129 | Class files (<filename>.bbclass</filename>) contain information that | 129 | Class files (<filename>.bbclass</filename>) contain information that |
130 | is useful to share between | 130 | is useful to share between |
131 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files. | 131 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> files. |
132 | An example is the Autotools class, which contains | 132 | An example is the Autotools class, which contains |
133 | common settings for any application that Autotools uses. | 133 | common settings for any application that Autotools uses. |
@@ -319,7 +319,7 @@ | |||
319 | Information based on direct inputs is referred to as the "basehash" in the | 319 | Information based on direct inputs is referred to as the "basehash" in the |
320 | code. | 320 | code. |
321 | However, there is still the question of a task's indirect inputs - the | 321 | However, there is still the question of a task's indirect inputs - the |
322 | things that were already built and present in the | 322 | things that were already built and present in the |
323 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. | 323 | <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>. |
324 | The checksum (or signature) for a particular task needs to add the hashes | 324 | The checksum (or signature) for a particular task needs to add the hashes |
325 | of all the tasks on which the particular task depends. | 325 | of all the tasks on which the particular task depends. |
@@ -366,7 +366,7 @@ | |||
366 | </literallayout> | 366 | </literallayout> |
367 | The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the | 367 | The "OEBasicHash" <filename>BB_SIGNATURE_HANDLER</filename> is the same as the |
368 | "OEBasic" version but adds the task hash to the stamp files. | 368 | "OEBasic" version but adds the task hash to the stamp files. |
369 | This results in any | 369 | This results in any |
370 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> | 370 | <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink> |
371 | change that changes the task hash, automatically | 371 | change that changes the task hash, automatically |
372 | causing the task to be run again. | 372 | causing the task to be run again. |
@@ -543,7 +543,7 @@ | |||
543 | information in the file. | 543 | information in the file. |
544 | If you specify two files, BitBake compares the two files and dumps out | 544 | If you specify two files, BitBake compares the two files and dumps out |
545 | the differences between the two. | 545 | the differences between the two. |
546 | This more easily helps answer the question of "What | 546 | This more easily helps answer the question of "What |
547 | changed between X and Y?"</para></listitem> | 547 | changed between X and Y?"</para></listitem> |
548 | </itemizedlist> | 548 | </itemizedlist> |
549 | </para> | 549 | </para> |
@@ -560,9 +560,9 @@ | |||
560 | into the checksum calculation, but do affect a task's output. | 560 | into the checksum calculation, but do affect a task's output. |
561 | A good example is perhaps when a tool changes its output. | 561 | A good example is perhaps when a tool changes its output. |
562 | Assume that the output of <filename>rpmdeps</filename> needed to change. | 562 | Assume that the output of <filename>rpmdeps</filename> needed to change. |
563 | The result of the change should be that all the | 563 | The result of the change should be that all the |
564 | <filename>package</filename>, <filename>package_write_rpm</filename>, | 564 | <filename>package</filename>, <filename>package_write_rpm</filename>, |
565 | and <filename>package_deploy-rpm</filename> shared state cache | 565 | and <filename>package_deploy-rpm</filename> shared state cache |
566 | items would become invalid. | 566 | items would become invalid. |
567 | But, because this is a change that is external to the code and therefore implicit, | 567 | But, because this is a change that is external to the code and therefore implicit, |
568 | the associated shared state cache items do not become invalidated. | 568 | the associated shared state cache items do not become invalidated. |
@@ -780,8 +780,8 @@ | |||
780 | of <filename><link linkend='var-S'>S</link></filename>. | 780 | of <filename><link linkend='var-S'>S</link></filename>. |
781 | </para> | 781 | </para> |
782 | <para> | 782 | <para> |
783 | Note that <filename>LIC_FILES_CHKSUM</filename> variable is | 783 | Note that <filename>LIC_FILES_CHKSUM</filename> variable is |
784 | mandatory for all recipes, unless the | 784 | mandatory for all recipes, unless the |
785 | <filename>LICENSE</filename> variable is set to "CLOSED". | 785 | <filename>LICENSE</filename> variable is set to "CLOSED". |
786 | </para> | 786 | </para> |
787 | </section> | 787 | </section> |
@@ -902,94 +902,104 @@ | |||
902 | <title>License Flag Matching</title> | 902 | <title>License Flag Matching</title> |
903 | 903 | ||
904 | <para> | 904 | <para> |
905 | In general, license flag matching is simple. | 905 | License flag matching allows you to control what recipes the |
906 | However, understanding some concepts will help you | 906 | OpenEmbedded build system includes in the build. |
907 | Fundamentally, the build system attempts to match | ||
908 | <filename>LICENSE_FLAG</filename> strings found in | ||
909 | recipes against <filename>LICENSE_FLAGS_WHITELIST</filename> | ||
910 | strings found in the whitelist. | ||
911 | A match, causes the build system to include a recipe in the | ||
912 | build, while failure to find a match causes the build system to | ||
913 | exclued a recipe. | ||
914 | </para> | ||
915 | |||
916 | <para> | ||
917 | In general, license flag matching is simple. | ||
918 | However, understanding some concepts will help you | ||
907 | correctly and effectively use matching. | 919 | correctly and effectively use matching. |
908 | </para> | 920 | </para> |
909 | 921 | ||
910 | <para> | 922 | <para> |
911 | Before a flag | 923 | Before a flag |
912 | defined by a particular recipe is tested against the | 924 | defined by a particular recipe is tested against the |
913 | contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the | 925 | contents of the whitelist, the expanded string |
914 | expanded string <filename>_${PN}</filename> is | 926 | <filename>_${PN}</filename> is appended to the flag. |
915 | appended to the flag. | 927 | This expansion makes each <filename>LICENSE_FLAGS</filename> |
916 | This expansion makes each <filename>LICENSE_FLAGS</filename> | ||
917 | value recipe-specific. | 928 | value recipe-specific. |
918 | After expansion, the string is then matched against the | 929 | After expansion, the string is then matched against the |
919 | whitelist. | 930 | whitelist. |
920 | Thus, specifying <filename>LICENSE_FLAGS = "commercial"</filename> | 931 | Thus, specifying |
921 | in recipe "foo" for example, results in the string | 932 | <filename>LICENSE_FLAGS = "commercial"</filename> |
933 | in recipe "foo", for example, results in the string | ||
922 | <filename>"commercial_foo"</filename>. | 934 | <filename>"commercial_foo"</filename>. |
923 | And that string would normally be appears in the whitelist | 935 | And, to create a match, that string must appear in the |
924 | in order for a match to occur. | 936 | whitelist. |
925 | </para> | 937 | </para> |
926 | 938 | ||
927 | <para> | 939 | <para> |
928 | Judicious use of the <filename>LICENSE_FLAGS</filename> | 940 | Judicious use of the <filename>LICENSE_FLAGS</filename> |
929 | strings and the contents of the | 941 | strings and the contents of the |
930 | <filename>LICENSE_FLAGS_WHITELIST</filename> variable | 942 | <filename>LICENSE_FLAGS_WHITELIST</filename> variable |
931 | allows you a lot of flexibility for matching license | 943 | allows you a lot of flexibility for including or excluding |
932 | flags. | 944 | recipes based on licensing. |
933 | For example, you can broaden the matching capabilities by | 945 | For example, you can broaden the matching capabilities by |
934 | using string subsets from the <filename>LICENSE_FLAGS</filename> | 946 | using license flags string subsets in the whitelist. |
935 | variables in the whitelist. | 947 | <note>When using a string subset, be sure to use the part of |
936 | <note>Be sure to use the part of the expanded | 948 | the expanded string that precedes the appended underscore |
937 | string that precedes | 949 | character (e.g. <filename>usethispart_1.3</filename>, |
938 | the underscore character (e.g. | ||
939 | <filename>usethispart_1.3</filename>, | ||
940 | <filename>usethispart_1.4</filename>, and so forth). | 950 | <filename>usethispart_1.4</filename>, and so forth). |
941 | </note> | 951 | </note> |
942 | For example, simply specifying the string "commercial" in | 952 | For example, simply specifying the string "commercial" in |
943 | the whitelist matches any expanded | 953 | the whitelist matches any expanded |
944 | <filename>LICENSE_FLAGS</filename> definition that starts with | 954 | <filename>LICENSE_FLAGS</filename> definition that starts with |
945 | the string "commercial" such as "commercial_foo" and | 955 | the string "commercial" such as "commercial_foo" and |
946 | "commercial_bar", which are the strings the build system | 956 | "commercial_bar", which are the strings the build system |
947 | automatically generates for hypothetical recipes named | 957 | automatically generates for hypothetical recipes named |
948 | "foo" and "bar" assuming those recipes simply specify the | 958 | "foo" and "bar" assuming those recipes simply specify the |
949 | following: | 959 | following: |
950 | <literallayout class='monospaced'> | 960 | <literallayout class='monospaced'> |
951 | LICENSE_FLAGS = "commercial" | 961 | LICENSE_FLAGS = "commercial" |
952 | </literallayout> | 962 | </literallayout> |
963 | Thus, you can choose to exhaustively | ||
964 | enumerate each license flag in the whitelist and | ||
965 | allow only specific recipes into the image, or | ||
966 | you can use a string subset that causes a broader range of | ||
967 | matches to allow a range of recipes into the image. | ||
953 | </para> | 968 | </para> |
954 | 969 | ||
955 | <para> | 970 | <para> |
956 | Judicious use of the strings with the | 971 | This scheme works even if the |
957 | <filename>LICENSE_FLAGS</filename> variable and the Broadening the match allows for a range of specificity for the | 972 | <filename>LICENSE_FLAG</filename> string already |
958 | items in the whitelist, from more general to perfectly | 973 | has <filename>_${PN}</filename> appended. |
959 | specific. | 974 | For example, the build system turns the license flag |
960 | So you have the choice of exhaustively | 975 | "commercial_1.2_foo" into "commercial_1.2_foo_foo" and would |
961 | enumerating each license flag in the whitelist to | 976 | match both the general "commercial" and the specific |
962 | allow only those specific recipes into the image, or | 977 | "commercial_1.2_foo" strings found in the whitelist, as |
963 | of using a more general string to pick up anything | 978 | expected. |
964 | matching just the first component or components of the specified | ||
965 | string. | ||
966 | </para> | 979 | </para> |
967 | 980 | ||
968 | <para> | 981 | <para> |
969 | This scheme works even if the flag already | 982 | Here are some other scenarios: |
970 | has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is | 983 | <itemizedlist> |
971 | redundant, but does not affect the outcome. | 984 | <listitem><para>You can specify a versioned string in the |
972 | For example, a license flag of "commercial_1.2_foo" would | 985 | recipe such as "commercial_foo_1.2" in a "foo" recipe. |
973 | turn into "commercial_1.2_foo_foo" and would match | 986 | The build system expands this string to |
974 | both the general "commercial" and the specific | 987 | "commercial_foo_1.2_foo". |
975 | "commercial_1.2_foo", as expected. | 988 | Combine this license flag with a whitelist that has |
976 | The flag would also match | 989 | the string "commercial" and you match the flag along |
977 | "commercial_1.2_foo_foo" and "commercial_1.2", which | 990 | with any other flag that starts with the string |
978 | does not make much sense regarding use in the whitelist. | 991 | "commercial".</para></listitem> |
979 | </para> | 992 | <listitem><para>Under the same circumstances, you can |
980 | 993 | use "commercial_foo" in the whitelist and the | |
981 | <para> | 994 | build system not only matches "commercial_foo_1.2" but |
982 | For a versioned string, you could instead specify | 995 | also matches any license flag with the string |
983 | "commercial_foo_1.2", which would turn into | 996 | "commercial_foo", regardless of the version. |
984 | "commercial_foo_1.2_foo". | 997 | </para></listitem> |
985 | And, as expected, this flag allows | 998 | <listitem><para>You can be very specific and use both the |
986 | you to pick up this package along with | 999 | package and version parts in the whitelist (e.g. |
987 | anything else "commercial" when you specify "commercial" | 1000 | "commercial_foo_1.2") to specifically match a |
988 | in the whitelist. | 1001 | versioned recipe.</para></listitem> |
989 | Or, the flag allows you to pick up this package along with anything "commercial_foo" | 1002 | </itemizedlist> |
990 | regardless of version when you use "commercial_foo" in the whitelist. | ||
991 | Finally, you can be completely specific about the package and version and specify | ||
992 | "commercial_foo_1.2" package and version. | ||
993 | </para> | 1003 | </para> |
994 | </section> | 1004 | </section> |
995 | 1005 | ||
@@ -1006,7 +1016,7 @@ | |||
1006 | COMMERCIAL_QT = "" | 1016 | COMMERCIAL_QT = "" |
1007 | </literallayout> | 1017 | </literallayout> |
1008 | If you want to enable these components, you can do so by making sure you have | 1018 | If you want to enable these components, you can do so by making sure you have |
1009 | statements similar to the following | 1019 | statements similar to the following |
1010 | in your <filename>local.conf</filename> configuration file: | 1020 | in your <filename>local.conf</filename> configuration file: |
1011 | <literallayout class='monospaced'> | 1021 | <literallayout class='monospaced'> |
1012 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ | 1022 | COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ |