diff options
-rw-r--r-- | documentation/poky-ref-manual/extendpoky.xml | 108 | ||||
-rw-r--r-- | documentation/poky-ref-manual/technical-details.xml | 159 |
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 | <!-- |
573 | vim: expandtab tw=80 ts=4 | 732 | vim: expandtab tw=80 ts=4 |