summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml108
-rw-r--r--documentation/poky-ref-manual/technical-details.xml159
2 files changed, 160 insertions, 107 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index f88e2a1dbf..56b806de0b 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -9,8 +9,7 @@
9 software packages, extending or customizing images or porting the Yocto Project to 9 software packages, extending or customizing images or porting the Yocto Project to
10 new hardware (adding a new machine). 10 new hardware (adding a new machine).
11 The chapter also describes ways to modify package source code, combine multiple 11 The chapter also describes ways to modify package source code, combine multiple
12 versions of library files into a single image, track license changes, and handle 12 versions of library files into a single image, and handle a package name alias.
13 a package name alias.
14 Finally, the chapter contains advice about how to make changes to the 13 Finally, the chapter contains advice about how to make changes to the
15 Yocto Project to achieve the best results. 14 Yocto Project to achieve the best results.
16 </para> 15 </para>
@@ -919,111 +918,6 @@
919 </section> 918 </section>
920 </section> 919 </section>
921 920
922 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
923 <title>Tracking License Changes</title>
924
925 <para>
926 The license of an upstream project might change in the future. In order to prevent these changes
927 going unnoticed, the Yocto Project provides a
928 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
929 variable to track changes to the license text. The checksums are validated at the end of the
930 configure step, and if the checksums do not match, the build will fail.
931 </para>
932
933 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
934 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
935
936 <para>
937 The <filename>LIC_FILES_CHKSUM</filename>
938 variable contains checksums of the license text in the source code for the recipe.
939 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
940 <literallayout class='monospaced'>
941 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
942 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
943 file://licfile2.txt;endline=50;md5=zzzz \
944 ..."
945 </literallayout>
946 </para>
947
948 <para>
949 The Yocto Project uses the
950 <filename><link linkend='var-S'>S</link></filename> variable as the
951 default directory used when searching files listed in
952 <filename>LIC_FILES_CHKSUM</filename>.
953 The previous example employs the default directory.
954 </para>
955
956 <para>
957 You can also use relative paths as shown in the following example:
958 <literallayout class='monospaced'>
959 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
960 md5=bb14ed3c4cda583abc85401304b5cd4e"
961 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
962 </literallayout>
963 </para>
964
965 <para>
966 In this example, the first line locates a file in
967 <filename><link linkend='var-S'>S</link>/src/ls.c</filename>.
968 The second line refers to a file in
969 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
970 of <filename>S</filename>.
971 </para>
972 <para>
973 Note that this variable is mandatory for all recipes, unless the
974 <filename>LICENSE</filename> variable is set to "CLOSED".
975 </para>
976 </section>
977
978 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
979 <title>Explanation of Syntax</title>
980 <para>
981 As mentioned in the previous section, the
982 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
983 important files that contain the license text for the source code.
984 It is possible to specify a checksum for an entire file, or a specific section of a
985 file (specified by beginning and ending line numbers with the "beginline" and "endline"
986 parameters, respectively).
987 The latter is useful for source files with a license notice header,
988 README documents, and so forth.
989 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
990 first line of the file.
991 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
992 ends with the last line of the file.
993 </para>
994
995 <para>
996 The "md5" parameter stores the md5 checksum of the license text.
997 If the license text changes in any way as compared to this parameter
998 then a mismatch occurs.
999 This mismatch triggers a build failure and notifies the developer.
1000 Notification allows the developer to review and address the license text changes.
1001 Also note that if a mismatch occurs during the build, the correct md5
1002 checksum is placed in the build log and can be easily copied to the recipe.
1003 </para>
1004
1005 <para>
1006 There is no limit to how many files you can specify using the
1007 <filename>LIC_FILES_CHKSUM</filename> variable.
1008 Generally, however, every project requires a few specifications for license tracking.
1009 Many projects have a "COPYING" file that stores the license information for all the source
1010 code files.
1011 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
1012 </para>
1013
1014 <tip>
1015 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
1016 error and displays the correct "md5" parameter value during the build.
1017 The correct parameter is also captured in the build log.
1018 </tip>
1019
1020 <tip>
1021 If the whole file contains only license text, you do not need to use the "beginline" and
1022 "endline" parameters.
1023 </tip>
1024 </section>
1025 </section>
1026
1027 <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> 921 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">
1028 <title>Handling a Package Name Alias</title> 922 <title>Handling a Package Name Alias</title>
1029 <para> 923 <para>
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index 9e40a66008..965d967b05 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -568,6 +568,165 @@
568 </section> 568 </section>
569</section> 569</section>
570 570
571<section id="licenses">
572 <title>Licenses</title>
573
574 <para>
575 This section describes the mechanism by which the Yocto Project build system
576 tracks changes to licensing text.
577 The section also describes how to enable commercially licensed receipes,
578 which by default are disabled.
579 </para>
580
581 <section id="usingpoky-configuring-LIC_FILES_CHKSUM">
582 <title>Tracking License Changes</title>
583
584 <para>
585 The license of an upstream project might change in the future. In order to prevent these changes
586 going unnoticed, the Yocto Project provides a
587 <filename><link linkend='var-LIC_FILES_CHKSUM'>LIC_FILES_CHKSUM</link></filename>
588 variable to track changes to the license text. The checksums are validated at the end of the
589 configure step, and if the checksums do not match, the build will fail.
590 </para>
591
592 <section id="usingpoky-specifying-LIC_FILES_CHKSUM">
593 <title>Specifying the <filename>LIC_FILES_CHKSUM</filename> Variable</title>
594
595 <para>
596 The <filename>LIC_FILES_CHKSUM</filename>
597 variable contains checksums of the license text in the source code for the recipe.
598 Following is an example of how to specify <filename>LIC_FILES_CHKSUM</filename>:
599 <literallayout class='monospaced'>
600 LIC_FILES_CHKSUM = "file://COPYING;md5=xxxx \
601 file://licfile1.txt;beginline=5;endline=29;md5=yyyy \
602 file://licfile2.txt;endline=50;md5=zzzz \
603 ..."
604 </literallayout>
605 </para>
606
607 <para>
608 The Yocto Project uses the
609 <filename><link linkend='var-S'>S</link></filename> variable as the
610 default directory used when searching files listed in
611 <filename>LIC_FILES_CHKSUM</filename>.
612 The previous example employs the default directory.
613 </para>
614
615 <para>
616 You can also use relative paths as shown in the following example:
617 <literallayout class='monospaced'>
618 LIC_FILES_CHKSUM = "file://src/ls.c;startline=5;endline=16;\
619 md5=bb14ed3c4cda583abc85401304b5cd4e"
620 LIC_FILES_CHKSUM = "file://../license.html;md5=5c94767cedb5d6987c902ac850ded2c6"
621 </literallayout>
622 </para>
623
624 <para>
625 In this example, the first line locates a file in
626 <filename><link linkend='var-S'>S</link>/src/ls.c</filename>.
627 The second line refers to a file in
628 <filename><link linkend='var-WORKDIR'>WORKDIR</link></filename>, which is the parent
629 of <filename>S</filename>.
630 </para>
631 <para>
632 Note that this variable is mandatory for all recipes, unless the
633 <filename>LICENSE</filename> variable is set to "CLOSED".
634 </para>
635 </section>
636
637 <section id="usingpoky-LIC_FILES_CHKSUM-explanation-of-syntax">
638 <title>Explanation of Syntax</title>
639 <para>
640 As mentioned in the previous section, the
641 <filename>LIC_FILES_CHKSUM</filename> variable lists all the
642 important files that contain the license text for the source code.
643 It is possible to specify a checksum for an entire file, or a specific section of a
644 file (specified by beginning and ending line numbers with the "beginline" and "endline"
645 parameters, respectively).
646 The latter is useful for source files with a license notice header,
647 README documents, and so forth.
648 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
649 first line of the file.
650 Similarly, if you do not use the "endline" parameter, it is assumed that the license text
651 ends with the last line of the file.
652 </para>
653
654 <para>
655 The "md5" parameter stores the md5 checksum of the license text.
656 If the license text changes in any way as compared to this parameter
657 then a mismatch occurs.
658 This mismatch triggers a build failure and notifies the developer.
659 Notification allows the developer to review and address the license text changes.
660 Also note that if a mismatch occurs during the build, the correct md5
661 checksum is placed in the build log and can be easily copied to the recipe.
662 </para>
663
664 <para>
665 There is no limit to how many files you can specify using the
666 <filename>LIC_FILES_CHKSUM</filename> variable.
667 Generally, however, every project requires a few specifications for license tracking.
668 Many projects have a "COPYING" file that stores the license information for all the source
669 code files.
670 This practice allows you to just track the "COPYING" file as long as it is kept up to date.
671 </para>
672
673 <tip>
674 If you specify an empty or invalid "md5" parameter, BitBake returns an md5 mis-match
675 error and displays the correct "md5" parameter value during the build.
676 The correct parameter is also captured in the build log.
677 </tip>
678
679 <tip>
680 If the whole file contains only license text, you do not need to use the "beginline" and
681 "endline" parameters.
682 </tip>
683 </section>
684 </section>
685
686 <section id="enabling-commercially-licensed-recipes">
687 <title>Enabling Commercially Licensed Recipes</title>
688
689 <para>
690 By default, the Yocto Project build system disables components that
691 have commercial licensing requirements.
692 The following four statements in the
693 <filename>$HOME/poky/meta/conf/distro/poky.conf</filename> file
694 disable components:
695 <literallayout class='monospaced'>
696 COMMERCIAL_LICENSE ?= "lame gst-fluendo-mp3 libmad mpeg2dec ffmpeg qmmp"
697 COMMERCIAL_AUDIO_PLUGINS ?= ""
698 COMMERCIAL_VIDEO_PLUGINS ?= ""
699 COMMERCIAL_QT ?= "qmmp"
700 </literallayout>
701 </para>
702
703 <para>
704 If you want to enable these components, you can do so by making sure you have
705 the following statements in the configuration file:
706 <literallayout class='monospaced'>
707 COMMERCIAL_AUDIO_PLUGINS = "gst-plugins-ugly-mad \
708 gst-plugins-ugly-mpegaudioparse"
709 COMMERCIAL_VIDEO_PLUGINS = "gst-plugins-ugly-mpeg2dec \
710 gst-plugins-ugly-mpegstream gst-plugins-bad-mpegvideoparse"
711 COMMERCIAL_LICENSE = ""
712 COMMERCIAL_QT = ""
713 </literallayout>
714 </para>
715
716 <para>
717 Excluding a package name from the
718 <filename>COMMERCIAL_LICENSE</filename> or
719 <filename>COMMERCIAL_QT</filename> statement enables that package.
720 </para>
721
722 <para>
723 Specifying audio and video plug-ins as part of the
724 <filename>COMMERCIAL_AUDIO_PLUGINS</filename> and
725 <filename>COMMERCIAL_VIDEO_PLUGINS</filename> statements includes
726 the plug-ins into built images - thus adding support for media formats.
727 </para>
728 </section>
729</section>
571</chapter> 730</chapter>
572<!-- 731<!--
573vim: expandtab tw=80 ts=4 732vim: expandtab tw=80 ts=4