summaryrefslogtreecommitdiffstats
path: root/documentation
diff options
context:
space:
mode:
authorTom Zanussi <tom.zanussi@intel.com>2012-03-21 17:50:20 -0600
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-03-23 14:24:49 +0000
commit9332e39d86191c1d4dad7565caae37362b8ffb13 (patch)
tree09545845dcb290a746604afb19fef05eca454092 /documentation
parent4a6e43cd6ec969df9d5ccea6b7c8689484de6149 (diff)
downloadpoky-9332e39d86191c1d4dad7565caae37362b8ffb13.tar.gz
documentation/poky-ref-manual/technical-details.xml: Licensed recipe edits
Applied and modified patch. Modifications included grammar, active voice, formatting, links, section creation, etc. (From yocto-docs rev: 76dc10138161124846c0752c251028ba16c45d7c) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation')
-rw-r--r--documentation/poky-ref-manual/technical-details.xml206
1 files changed, 176 insertions, 30 deletions
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index 19ce9ab224..b0c0f4659e 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -685,44 +685,190 @@
685 <title>Enabling Commercially Licensed Recipes</title> 685 <title>Enabling Commercially Licensed Recipes</title>
686 686
687 <para> 687 <para>
688 By default, the Yocto Project build system disables components that 688 By default, the Yocto Project build system disables
689 have commercial licensing requirements. 689 components that have commercial or other special licensing
690 The following four statements in the 690 requirements.
691 <filename>$HOME/poky/meta/conf/distro/poky.conf</filename> file 691 Such requirements are defined on a
692 disable components: 692 recipe-by-recipe basis through the <filename>LICENSE_FLAGS</filename> variable
693 definition in the affected recipe.
694 For instance, the
695 <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
696 recipe contains the following statement:
693 <literallayout class='monospaced'> 697 <literallayout class='monospaced'>
694 COMMERCIAL_LICENSE ?= "lame gst-fluendo-mp3 libmad mpeg2dec ffmpeg qmmp" 698 LICENSE_FLAGS = "commercial"
695 COMMERCIAL_AUDIO_PLUGINS ?= ""
696 COMMERCIAL_VIDEO_PLUGINS ?= ""
697 COMMERCIAL_QT ?= "qmmp"
698 </literallayout> 699 </literallayout>
699 </para> 700 This next example shows a recipe in another layer:
700 701 <literallayout class='monospaced'>
701 <para> 702 LICENSE_FLAGS = "license_${PN}_${PV}"
702 If you want to enable these components, you can do so by making sure you have 703 </literallayout>
703 the following statements in the configuration file: 704 In order for a component restricted by a <filename>LICENSE_FLAGS</filename>
705 definition to be enabled and included in an image, it
706 needs to have a matching entry in the global
707 <filename>LICENSE_FLAGS_WHITELIST</filename> variable, which is a variable
708 typically defined in your <filename>local.conf</filename> file.
709 For example, to enable
710 the <filename>$HOME/poky/meta/recipes-multimedia/gstreamer/gst-plugins-ugly</filename>
711 package, you could add either the string
712 "commercial_gst-plugins-ugly" or the more general string
713 "commercial" to <filename>LICENSE_FLAGS_WHITELIST</filename>.
714 See the
715 "<link linkend='license-flag-matching'>License Flag Matching</link>" section
716 for a full explanation of how <filename>LICENSE_FLAGS</filename> matching works.
717 Here is the example:
704 <literallayout class='monospaced'> 718 <literallayout class='monospaced'>
719 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly"
720 </literallayout>
721 Likewise, to additionally enable the package containing
722 <filename>LICENSE_FLAGS = "license_${PN}_${PV}"</filename>, and assuming
723 that the actual recipe name was <filename>emgd_1.10.bb</filename>,
724 the following string would enable that package as well as
725 the original <filename>gst-plugins-ugly</filename> package:
726 <literallayout class='monospaced'>
727 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly license_emgd_1.10"
728 </literallayout>
729 As a convenience, you do not need to specify the complete license string
730 in the whitelist for every package.
731 you can use an abbreviated form, which consists
732 of just the first portion or portions of the license string before
733 the initial underscore character or characters.
734 A partial string will match
735 any license that contains the given string as the first
736 portion of its license.
737 For example, the following
738 whitelist string will also match both of the packages
739 previously mentioned as well as any other packages that have
740 licenses starting with "commercial" or "license".
741 <literallayout class='monospaced'>
742 LICENSE_FLAGS_WHITELIST = "commercial license"
743 </literallayout>
744 </para>
745
746 <section id="license-flag-matching">
747 <title>License Flag Matching</title>
748
749 <para>
750 The definition of 'matching' in reference to a
751 recipe's <filename>LICENSE_FLAGS</filename> setting is simple.
752 However, some things exist that you should know about in order to
753 correctly and effectively use it.
754 </para>
755
756 <para>
757 Before a flag
758 defined by a particular recipe is tested against the
759 contents of the <filename>LICENSE_FLAGS_WHITELIST</filename> variable, the
760 string <filename>_${PN}</filename> (with
761 <link linkend='var-PN'><filename>PN</filename></link> expanded of course) is
762 appended to the flag, thus automatically making each
763 <filename>LICENSE_FLAGS</filename> value recipe-specific.
764 That string is
765 then matched against the whitelist.
766 So if you specify <filename>LICENSE_FLAGS = "commercial"</filename> in recipe
767 "foo" for example, the string <filename>"commercial_foo"</filename>
768 would normally be what is specified in the whitelist in order for it to
769 match.
770 </para>
771
772 <para>
773 You can broaden the match by
774 putting any "_"-separated beginning subset of a
775 <filename>LICENSE_FLAGS</filename> flag in the whitelist, which will also
776 match.
777 For example, simply specifying "commercial" in
778 the whitelist would match any expanded <filename>LICENSE_FLAGS</filename>
779 definition starting with "commercial" such as
780 "commercial_foo" and "commercial_bar", which are the
781 strings that would be automatically generated for
782 hypothetical "foo" and "bar" recipes assuming those
783 recipes had simply specified the following:
784 <literallayout class='monospaced'>
785 LICENSE_FLAGS = "commercial"
786 </literallayout>
787 </para>
788
789 <para>
790 Broadening the match allows for a range of specificity for the items
791 in the whitelist, from more general to perfectly
792 specific.
793 So you have the choice of exhaustively
794 enumerating each license flag in the whitelist to
795 allow only those specific recipes into the image, or
796 of using a more general string to pick up anything
797 matching just the first component or components of the specified
798 string.
799 </para>
800
801 <para>
802 This scheme works even if the flag already
803 has <filename>_${PN}</filename> appended - the extra <filename>_${PN}</filename> is
804 redundant, but does not affect the outcome.
805 For example, a license flag of "commercial_1.2_foo" would
806 turn into "commercial_1.2_foo_foo" and would match
807 both the general "commercial" and the specific
808 "commercial_1.2_foo", as expected.
809 The flag would also match
810 "commercial_1.2_foo_foo" and "commercial_1.2", which
811 does not make much sense regarding use in the whitelist.
812 </para>
813
814 <para>
815 For a versioned string, you could instead specify
816 "commercial_foo_1.2", which would turn into
817 "commercial_foo_1.2_foo".
818 And, as expected, this flag allows
819 you to pick up this package along with
820 anything else "commercial" when you specify "commercial"
821 in the whitelist.
822 Or, the flag allows you to pick up this package along with anything "commercial_foo"
823 regardless of version when you use "commercial_foo" in the whitelist.
824 Finally, you can be completely specific about the package and version and specify
825 "commercial_foo_1.1" package and version.
826 </para>
827 </section>
828
829 <section id="other-variables-related-to-commercial-licenses">
830 <title>Other Variables Related to Commercial Licenses</title>
831
832 <para>
833 Other helpful variables related to commercial
834 license handling exist and are defined in the
835 <filename>$HOME/poky/meta/conf/distro/include/default-distrovars.inc</filename> file:
836 <literallayout class='monospaced'>
837 COMMERCIAL_AUDIO_PLUGINS ?= ""
838 COMMERCIAL_VIDEO_PLUGINS ?= ""
839 COMMERCIAL_QT = ""
840 </literallayout>
841 If you want to enable these components, you can do so by making sure you have
842 the following statements in your <filename>local.conf</filename> configuration file:
843 <literallayout class='monospaced'>
705 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \ 844 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
706 gst-plugins-ugly-mpegaudioparse" 845 gst-plugins-ugly-mpegaudioparse"
707 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \ 846 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
708 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse" 847 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
709 COMMERCIAL_LICENSE = "" 848 COMMERCIAL_QT ?= "qmmp"
710 COMMERCIAL_QT = "" 849 LICENSE_FLAGS_WHITELIST = "commercial_gst-plugins-ugly commercial_gst-plugins-bad commercial_qmmp"
711 </literallayout> 850 </literallayout>
712 </para> 851 Of course, you could also create a matching whitelist
713 852 for those components using the more general "commercial"
714 <para> 853 in the whitelist, but that would also enable all the
715 Excluding a package name from the 854 other packages with <filename>LICENSE_FLAGS</filename> containing
716 <filename>COMMERCIAL_LICENSE</filename> or 855 "commercial", which you may or may not want:
717 <filename>COMMERCIAL_QT</filename> statement enables that package. 856 <literallayout class='monospaced'>
718 </para> 857 LICENSE_FLAGS_WHITELIST = "commercial"
858 </literallayout>
859 </para>
719 860
720 <para> 861 <para>
721 Specifying audio and video plug-ins as part of the 862 Specifying audio and video plug-ins as part of the
722 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and 863 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
723 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements includes 864 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements
724 the plug-ins into built images - thus adding support for media formats. 865 or commercial qt components as part of
725 </para> 866 the <filename>COMMERCIAL_QT</filename> statement (along
867 with the enabling <filename>LICENSE_FLAGS_WHITELIST</filename>) includes the
868 plug-ins or components into built images, thus adding
869 support for media formats or components.
870 </para>
871 </section>
726 </section> 872 </section>
727</section> 873</section>
728</chapter> 874</chapter>