summaryrefslogtreecommitdiffstats
path: root/documentation/poky-ref-manual
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-12-08 13:22:23 -0800
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-01-30 16:05:49 +0000
commitd2f1ca8cbac271bd60a2fb98a4e9732202e42b25 (patch)
tree6440b4d37aff88c04c6450531cde12e87da14ca7 /documentation/poky-ref-manual
parentcaab52f6cc84b8fd09d150093bbb19674340ceaa (diff)
downloadpoky-d2f1ca8cbac271bd60a2fb98a4e9732202e42b25.tar.gz
documentation/poky-ref-manual/extendpoky.xml: intro changed and order changed
Beefed up the introductory paragraph and I re-ordered the "Making and Maintaining Changes" section towards the end of the chapter. (From yocto-docs rev: a58c0e73d720ffb7a4931fbc196ea3831992b514) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/poky-ref-manual')
-rw-r--r--documentation/poky-ref-manual/extendpoky.xml648
1 files changed, 325 insertions, 323 deletions
diff --git a/documentation/poky-ref-manual/extendpoky.xml b/documentation/poky-ref-manual/extendpoky.xml
index 30fce1459f..85366aecfc 100644
--- a/documentation/poky-ref-manual/extendpoky.xml
+++ b/documentation/poky-ref-manual/extendpoky.xml
@@ -3,13 +3,14 @@
3 3
4<chapter id='extendpoky'> 4<chapter id='extendpoky'>
5 5
6<title>Extending the Yocto Project</title> 6<title>Common Tasks</title>
7 <para> 7 <para>
8 This chapter provides information about how to extend the functionality 8 This chapter describes standard tasks such as adding new
9 already present in the Yocto Project.
10 The chapter also documents standard tasks such as adding new
11 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
12 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
12 versions of library files into a single image, track license changes, and handle
13 a package name alias.
13 Finally, the chapter contains advice about how to make changes to the 14 Finally, the chapter contains advice about how to make changes to the
14 Yocto Project to achieve the best results. 15 Yocto Project to achieve the best results.
15 </para> 16 </para>
@@ -658,324 +659,6 @@
658 </section> 659 </section>
659 </section> 660 </section>
660 661
661 <section id="usingpoky-changes">
662 <title>Making and Maintaining Changes</title>
663 <para>
664 Because the Yocto Project is extremely configurable and flexible,
665 we recognize that developers will want
666 to extend, configure or optimize it for their specific uses.
667 To best keep pace with future Yocto Project changes,
668 we recommend you make controlled changes to the Yocto Project.
669 </para>
670
671 <para>
672 The Yocto Project supports a <link linkend='usingpoky-changes-layers'>"layers"</link> concept.
673 If you use layers properly, you can ease future upgrades and allow segregation
674 between the Yocto Project core and a given developer's changes.
675 The following section provides more advice on managing changes to the Yocto Project.
676 </para>
677
678 <section id="usingpoky-changes-layers">
679 <title>BitBake Layers</title>
680 <para>
681 Often, developers want to extend the Yocto Project either by adding packages
682 or by overriding files contained within the Yocto Project to add their own
683 functionality.
684 BitBake has a powerful mechanism called
685 "layers", which provides a way to handle this extension in a fully
686 supported and non-invasive fashion.
687 </para>
688
689 <para>
690 The Yocto Project files include several additional layers such as
691 <filename>meta-rt</filename> and <filename>meta-yocto</filename>
692 that demonstrate this functionality.
693 The <filename>meta-rt</filename> layer is not enabled by default.
694 However, the <filename>meta-yocto</filename> layer is.
695 </para>
696
697 <para>
698 To enable a layer, you simply add the layer's path to the
699 <filename><link linkend='var-BBLAYERS'>BBLAYERS</link></filename> variable in your
700 <filename>bblayers.conf</filename> file, which is found in the Yocto Project file's
701 build directory.
702 The following example shows how to enable the <filename>meta-rt</filename>:
703 <literallayout class='monospaced'>
704 LCONF_VERSION = "1"
705
706 BBFILES ?= ""
707 BBLAYERS = " \
708 /path/to/poky/meta \
709 /path/to/poky/meta-yocto \
710 /path/to/poky/meta-rt \
711 "
712 </literallayout>
713 </para>
714
715 <para>
716 BitBake parses each <filename>conf/layer.conf</filename> file for each layer in
717 <filename>BBLAYERS</filename>
718 and adds the recipes, classes and configurations contained within the layer to
719 the Yocto Project.
720 To create your own layer, independent of the Yocto Project files,
721 simply create a directory with a <filename>conf/layer.conf</filename> file and
722 add the directory to your <filename>bblayers.conf</filename> file.
723 </para>
724
725 <para>
726 The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the
727 required syntax:
728 <literallayout class='monospaced'>
729 # We have a conf and classes directory, add to BBPATH
730 BBPATH := "${BBPATH}:${LAYERDIR}"
731
732 # We have a packages directory, add to BBFILES
733 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
734 ${LAYERDIR}/recipes-*/*/*.bbappend"
735
736 BBFILE_COLLECTIONS += "yocto"
737 BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
738 BBFILE_PRIORITY_yocto = "5"
739 </literallayout>
740 </para>
741
742 <para>
743 In the previous example, the recipes for the layers are added to
744 <filename><link linkend='var-BBFILES'>BBFILES</link></filename>.
745 The <filename><link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link></filename>
746 variable is then appended with the layer name.
747 The <filename><link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN</link></filename> variable
748 immediately expands with a regular expression used to match files from
749 <filename>BBFILES</filename> into
750 a particular layer, in this case by using the base pathname.
751 The <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename> variable
752 then assigns different priorities to the files in different layers.
753 Applying priorities is useful in situations where the same package might appear in multiple
754 layers and allows you to choose what layer should take precedence.
755 </para>
756
757 <para>
758 Note the use of the <filename><link linkend='var-LAYERDIR'>LAYERDIR</link></filename>
759 variable with the immediate expansion operator.
760 The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
761 requires the immediate expansion operator so that BitBake does not wait to expand the variable
762 when it's parsing a different directory.
763 </para>
764
765 <para>
766 BitBake can locate where other <filename>.bbclass</filename> and configuration files
767 are applied through the <filename>BBPATH</filename> environment variable.
768 For these cases, BitBake uses the first file with the matching name found in
769 <filename>BBPATH</filename>.
770 This is similar to the way the <filename>PATH</filename> variable is used for binaries.
771 We recommend, therefore, that you use unique <filename>.bbclass</filename>
772 and configuration file names in your custom layer.
773 </para>
774
775 <para>
776 We also recommend the following:
777 <itemizedlist>
778 <listitem><para>Store custom layers in a Git repository that uses the
779 <filename>meta-prvt-XXXX</filename> format.</para></listitem>
780 <listitem><para>Clone the repository alongside other <filename>meta</filename>
781 directories in the Yocto Project source files area.</para></listitem>
782 </itemizedlist>
783 Following these recommendations keeps your Yocto Project files area and
784 its configuration entirely inside the Yocto Project's core base.
785 </para>
786 </section>
787
788 <section id="usingpoky-changes-commits">
789 <title>Committing Changes</title>
790
791 <para>
792 Modifications to the Yocto Project are often managed under some kind of source
793 revision control system.
794 Because some simple practices can significantly improve usability, policy for committing changes
795 is important.
796 It helps to use a consistent documentation style when committing changes.
797 The Yocto Project development team has found the following practices work well:
798 <itemizedlist>
799 <listitem><para>The first line of the commit summarizes the change and begins with the
800 name of the affected package or packages.
801 However, not all changes apply to specific packages.
802 Consequently, the prefix could also be a machine name or class name.</para></listitem>
803 <listitem><para>The second part of the commit (if needed) is a longer more detailed
804 description of the changes.
805 Placing a blank line between the first and second parts helps with
806 readability.</para></listitem>
807 </itemizedlist>
808 </para>
809
810 <para>
811 Following is an example commit:
812 <literallayout class='monospaced'>
813 bitbake/data.py: Add emit_func() and generate_dependencies() functions
814
815 These functions allow generation of dependency data between functions and
816 variables allowing moves to be made towards generating checksums and allowing
817 use of the dependency information in other parts of BitBake.
818
819 Signed-off-by: Richard Purdie richard.purdie@linuxfoundation.org
820 </literallayout>
821 </para>
822
823 <para>
824 All commits should be self-contained such that they leave the
825 metadata in a consistent state that builds both before and after the
826 commit is made.
827 Besides being a good practice to follow, it helps ensure autobuilder test results
828 are valid.
829 </para>
830 </section>
831
832 <section id="usingpoky-changes-prbump">
833 <title>Package Revision Incrementing</title>
834
835 <para>
836 If a committed change results in changing the package output,
837 then the value of the
838 <filename><link linkend='var-PR'>PR</link></filename> variable needs to be increased
839 (or "bumped") as part of that commit.
840 This means that for new recipes you must be sure to add the <filename>PR</filename>
841 variable and set its initial value equal to "r0".
842 Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
843 Note that you can only use integer values following the "r" in the
844 <filename>PR</filename> variable.
845 </para>
846
847 <para>
848 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
849 you can also use the
850 <filename><link linkend='var-INC_PR'>INC_PR</link></filename> variable to ensure that
851 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
852 <filename>.inc</filename> file itself is changed.
853 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
854 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
855 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
856 If the <filename>.inc</filename> file is changed then its
857 <filename>INC_PR</filename> should be incremented.
858 </para>
859
860 <para>
861 When upgrading the version of a package, assuming the
862 <filename><link linkend='var-PV'>PV</link></filename> changes,
863 the <filename>PR</filename> variable should be reset to "r0"
864 (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
865 </para>
866
867 <para>
868 Usually, version increases occur only to packages.
869 However, if for some reason <filename>PV</filename> changes but does not
870 increase, you can increase the
871 <filename><link linkend='var-PE'>PE</link></filename> variable (Package Epoch).
872 The <filename>PE</filename> variable defaults to "0".
873 </para>
874
875 <para>
876 Version numbering strives to follow the
877 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
878 Debian Version Field Policy Guidelines</ulink>.
879 These guidelines define how versions are compared and what "increasing" a version means.
880 </para>
881
882 <para>
883 There are two reasons for following the previously mentioned guidelines.
884 First, to ensure that when a developer updates and rebuilds, they get all the changes to
885 the repository and do not have to remember to rebuild any sections.
886 Second, to ensure that target users are able to upgrade their
887 devices using package manager commands such as <filename>opkg upgrade</filename>
888 (or similar commands for dpkg/apt or rpm-based systems).
889 </para>
890
891 <para>
892 The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
893 </para>
894 </section>
895
896 <section id="usingpoky-changes-collaborate">
897 <title>Using The Yocto Project in a Team Environment</title>
898
899 <para>
900 It might not be immediately clear how you can use the Yocto Project in a team environment,
901 or scale it for a large team of developers.
902 The specifics of any situation determine the best solution.
903 Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
904 that experience has shown work well.
905 </para>
906
907 <para>
908 The core component of any development effort with the Yocto Project is often an
909 automated build and testing framework along with an image generation process.
910 You can use these core components to check that the metadata can be built,
911 highlight when commits break the build, and provide up-to-date images that
912 allow developers to test the end result and use it as a base platform for further
913 development.
914 Experience shows that buildbot is a good fit for this role.
915 What works well is to configure buildbot to make two types of builds:
916 incremental and full (from scratch).
917 See <ulink url='http://www.yoctoproject.org:8010'>the buildbot for the
918 Yocto Project</ulink> for an example implementation that uses buildbot.
919 </para>
920
921 <para>
922 You can tie incremental builds to a commit hook that triggers the build
923 each time a commit is made to the metadata.
924 This practice results in useful acid tests that determine whether a given commit
925 breaks the build in some serious way.
926 Associating a build to a commit can catch a lot of simple errors.
927 Furthermore, the tests are fast so developers can get quick feedback on changes.
928 </para>
929
930 <para>
931 Full builds build and test everything from the ground up.
932 These types of builds usually happen at predetermined times like during the
933 night when the machine load is low.
934 </para>
935
936 <para>
937 Most teams have many pieces of software undergoing active development at any given time.
938 You can derive large benefits by putting these pieces under the control of a source
939 control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN).
940 You can then set the autobuilder to pull the latest revisions of the packages
941 and test the latest commits by the builds.
942 This practice quickly highlights issues.
943 The Yocto Project easily supports testing configurations that use both a
944 stable known good revision and a floating revision.
945 The Yocto Project can also take just the changes from specific source control branches.
946 This capability allows you to track and test specific changes.
947 </para>
948
949 <para>
950 Perhaps the hardest part of setting this up is defining the software project or
951 the Yocto Project metadata policies that surround the different source control systems.
952 Of course circumstances will be different in each case.
953 However, this situation reveals one of the Yocto Project's advantages -
954 the system itself does not
955 force any particular policy on users, unlike a lot of build systems.
956 The system allows the best policies to be chosen for the given circumstances.
957 </para>
958 </section>
959
960 <section id="usingpoky-changes-updatingimages">
961 <title>Updating Existing Images</title>
962
963 <para>
964 Often, rather than re-flashing a new image, you might wish to install updated
965 packages into an existing running system.
966 You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory
967 through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename>
968 to point at the shared server.
969 Following is an example:
970 <literallayout class='monospaced'>
971 $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
972 $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
973 $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
974 </literallayout>
975 </para>
976 </section>
977 </section>
978
979 <section id="usingpoky-modifing-packages"> 662 <section id="usingpoky-modifing-packages">
980 <title>Modifying Package Source Code</title> 663 <title>Modifying Package Source Code</title>
981 <para> 664 <para>
@@ -1300,7 +983,7 @@
1300 important files that contain the license text for the source code. 983 important files that contain the license text for the source code.
1301 It is possible to specify a checksum for an entire file, or a specific section of a 984 It is possible to specify a checksum for an entire file, or a specific section of a
1302 file (specified by beginning and ending line numbers with the "beginline" and "endline" 985 file (specified by beginning and ending line numbers with the "beginline" and "endline"
1303 parameters respectively). 986 parameters, respectively).
1304 The latter is useful for source files with a license notice header, 987 The latter is useful for source files with a license notice header,
1305 README documents, and so forth. 988 README documents, and so forth.
1306 If you do not use the "beginline" parameter, then it is assumed that the text begins on the 989 If you do not use the "beginline" parameter, then it is assumed that the text begins on the
@@ -1381,6 +1064,325 @@
1381 file found in the Yocto Project files area. 1064 file found in the Yocto Project files area.
1382 </para> 1065 </para>
1383 </section> 1066 </section>
1067
1068 <section id="usingpoky-changes">
1069 <title>Making and Maintaining Changes</title>
1070 <para>
1071 Because the Yocto Project is extremely configurable and flexible,
1072 we recognize that developers will want
1073 to extend, configure or optimize it for their specific uses.
1074 To best keep pace with future Yocto Project changes,
1075 we recommend you make controlled changes to the Yocto Project.
1076 </para>
1077
1078 <para>
1079 The Yocto Project supports a <link linkend='usingpoky-changes-layers'>"layers"</link> concept.
1080 If you use layers properly, you can ease future upgrades and allow segregation
1081 between the Yocto Project core and a given developer's changes.
1082 The following section provides more advice on managing changes to the Yocto Project.
1083 </para>
1084
1085 <section id="usingpoky-changes-layers">
1086 <title>BitBake Layers</title>
1087 <para>
1088 Often, developers want to extend the Yocto Project either by adding packages
1089 or by overriding files contained within the Yocto Project to add their own
1090 functionality.
1091 BitBake has a powerful mechanism called
1092 "layers", which provides a way to handle this extension in a fully
1093 supported and non-invasive fashion.
1094 </para>
1095
1096 <para>
1097 The Yocto Project files include several additional layers such as
1098 <filename>meta-rt</filename> and <filename>meta-yocto</filename>
1099 that demonstrate this functionality.
1100 The <filename>meta-rt</filename> layer is not enabled by default.
1101 However, the <filename>meta-yocto</filename> layer is.
1102 </para>
1103
1104 <para>
1105 To enable a layer, you simply add the layer's path to the
1106 <filename><link linkend='var-BBLAYERS'>BBLAYERS</link></filename> variable in your
1107 <filename>bblayers.conf</filename> file, which is found in the Yocto Project file's
1108 build directory.
1109 The following example shows how to enable the <filename>meta-rt</filename>:
1110 <literallayout class='monospaced'>
1111 LCONF_VERSION = "1"
1112
1113 BBFILES ?= ""
1114 BBLAYERS = " \
1115 /path/to/poky/meta \
1116 /path/to/poky/meta-yocto \
1117 /path/to/poky/meta-rt \
1118 "
1119 </literallayout>
1120 </para>
1121
1122 <para>
1123 BitBake parses each <filename>conf/layer.conf</filename> file for each layer in
1124 <filename>BBLAYERS</filename>
1125 and adds the recipes, classes and configurations contained within the layer to
1126 the Yocto Project.
1127 To create your own layer, independent of the Yocto Project files,
1128 simply create a directory with a <filename>conf/layer.conf</filename> file and
1129 add the directory to your <filename>bblayers.conf</filename> file.
1130 </para>
1131
1132 <para>
1133 The <filename>meta-yocto/conf/layer.conf</filename> file demonstrates the
1134 required syntax:
1135 <literallayout class='monospaced'>
1136 # We have a conf and classes directory, add to BBPATH
1137 BBPATH := "${BBPATH}:${LAYERDIR}"
1138
1139 # We have a packages directory, add to BBFILES
1140 BBFILES := "${BBFILES} ${LAYERDIR}/recipes-*/*/*.bb \
1141 ${LAYERDIR}/recipes-*/*/*.bbappend"
1142
1143 BBFILE_COLLECTIONS += "yocto"
1144 BBFILE_PATTERN_yocto := "^${LAYERDIR}/"
1145 BBFILE_PRIORITY_yocto = "5"
1146 </literallayout>
1147 </para>
1148
1149 <para>
1150 In the previous example, the recipes for the layers are added to
1151 <filename><link linkend='var-BBFILES'>BBFILES</link></filename>.
1152 The <filename><link linkend='var-BBFILE_COLLECTIONS'>BBFILE_COLLECTIONS</link></filename>
1153 variable is then appended with the layer name.
1154 The <filename><link linkend='var-BBFILE_PATTERN'>BBFILE_PATTERN</link></filename> variable
1155 immediately expands with a regular expression used to match files from
1156 <filename>BBFILES</filename> into
1157 a particular layer, in this case by using the base pathname.
1158 The <filename><link linkend='var-BBFILE_PRIORITY'>BBFILE_PRIORITY</link></filename> variable
1159 then assigns different priorities to the files in different layers.
1160 Applying priorities is useful in situations where the same package might appear in multiple
1161 layers and allows you to choose what layer should take precedence.
1162 </para>
1163
1164 <para>
1165 Note the use of the <filename><link linkend='var-LAYERDIR'>LAYERDIR</link></filename>
1166 variable with the immediate expansion operator.
1167 The <filename>LAYERDIR</filename> variable expands to the directory of the current layer and
1168 requires the immediate expansion operator so that BitBake does not wait to expand the variable
1169 when it's parsing a different directory.
1170 </para>
1171
1172 <para>
1173 BitBake can locate where other <filename>.bbclass</filename> and configuration files
1174 are applied through the <filename>BBPATH</filename> environment variable.
1175 For these cases, BitBake uses the first file with the matching name found in
1176 <filename>BBPATH</filename>.
1177 This is similar to the way the <filename>PATH</filename> variable is used for binaries.
1178 We recommend, therefore, that you use unique <filename>.bbclass</filename>
1179 and configuration file names in your custom layer.
1180 </para>
1181
1182 <para>
1183 We also recommend the following:
1184 <itemizedlist>
1185 <listitem><para>Store custom layers in a Git repository that uses the
1186 <filename>meta-prvt-XXXX</filename> format.</para></listitem>
1187 <listitem><para>Clone the repository alongside other <filename>meta</filename>
1188 directories in the Yocto Project source files area.</para></listitem>
1189 </itemizedlist>
1190 Following these recommendations keeps your Yocto Project files area and
1191 its configuration entirely inside the Yocto Project's core base.
1192 </para>
1193 </section>
1194
1195 <section id="usingpoky-changes-commits">
1196 <title>Committing Changes</title>
1197
1198 <para>
1199 Modifications to the Yocto Project are often managed under some kind of source
1200 revision control system.
1201 Because some simple practices can significantly improve usability, policy for committing changes
1202 is important.
1203 It helps to use a consistent documentation style when committing changes.
1204 The Yocto Project development team has found the following practices work well:
1205 <itemizedlist>
1206 <listitem><para>The first line of the commit summarizes the change and begins with the
1207 name of the affected package or packages.
1208 However, not all changes apply to specific packages.
1209 Consequently, the prefix could also be a machine name or class name.</para></listitem>
1210 <listitem><para>The second part of the commit (if needed) is a longer more detailed
1211 description of the changes.
1212 Placing a blank line between the first and second parts helps with
1213 readability.</para></listitem>
1214 </itemizedlist>
1215 </para>
1216
1217 <para>
1218 Following is an example commit:
1219 <literallayout class='monospaced'>
1220 bitbake/data.py: Add emit_func() and generate_dependencies() functions
1221
1222 These functions allow generation of dependency data between functions and
1223 variables allowing moves to be made towards generating checksums and allowing
1224 use of the dependency information in other parts of BitBake.
1225
1226 Signed-off-by: Richard Purdie richard.purdie@linuxfoundation.org
1227 </literallayout>
1228 </para>
1229
1230 <para>
1231 All commits should be self-contained such that they leave the
1232 metadata in a consistent state that builds both before and after the
1233 commit is made.
1234 Besides being a good practice to follow, it helps ensure autobuilder test results
1235 are valid.
1236 </para>
1237 </section>
1238
1239 <section id="usingpoky-changes-prbump">
1240 <title>Package Revision Incrementing</title>
1241
1242 <para>
1243 If a committed change results in changing the package output,
1244 then the value of the
1245 <filename><link linkend='var-PR'>PR</link></filename> variable needs to be increased
1246 (or "bumped") as part of that commit.
1247 This means that for new recipes you must be sure to add the <filename>PR</filename>
1248 variable and set its initial value equal to "r0".
1249 Failing to define <filename>PR</filename> makes it easy to miss when you bump a package.
1250 Note that you can only use integer values following the "r" in the
1251 <filename>PR</filename> variable.
1252 </para>
1253
1254 <para>
1255 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
1256 you can also use the
1257 <filename><link linkend='var-INC_PR'>INC_PR</link></filename> variable to ensure that
1258 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
1259 <filename>.inc</filename> file itself is changed.
1260 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
1261 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
1262 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
1263 If the <filename>.inc</filename> file is changed then its
1264 <filename>INC_PR</filename> should be incremented.
1265 </para>
1266
1267 <para>
1268 When upgrading the version of a package, assuming the
1269 <filename><link linkend='var-PV'>PV</link></filename> changes,
1270 the <filename>PR</filename> variable should be reset to "r0"
1271 (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
1272 </para>
1273
1274 <para>
1275 Usually, version increases occur only to packages.
1276 However, if for some reason <filename>PV</filename> changes but does not
1277 increase, you can increase the
1278 <filename><link linkend='var-PE'>PE</link></filename> variable (Package Epoch).
1279 The <filename>PE</filename> variable defaults to "0".
1280 </para>
1281
1282 <para>
1283 Version numbering strives to follow the
1284 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
1285 Debian Version Field Policy Guidelines</ulink>.
1286 These guidelines define how versions are compared and what "increasing" a version means.
1287 </para>
1288
1289 <para>
1290 There are two reasons for following the previously mentioned guidelines.
1291 First, to ensure that when a developer updates and rebuilds, they get all the changes to
1292 the repository and do not have to remember to rebuild any sections.
1293 Second, to ensure that target users are able to upgrade their
1294 devices using package manager commands such as <filename>opkg upgrade</filename>
1295 (or similar commands for dpkg/apt or rpm-based systems).
1296 </para>
1297
1298 <para>
1299 The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
1300 </para>
1301 </section>
1302
1303 <section id="usingpoky-changes-collaborate">
1304 <title>Using The Yocto Project in a Team Environment</title>
1305
1306 <para>
1307 It might not be immediately clear how you can use the Yocto Project in a team environment,
1308 or scale it for a large team of developers.
1309 The specifics of any situation determine the best solution.
1310 Granted that the Yocto Project offers immense flexibility regarding this, practices do exist
1311 that experience has shown work well.
1312 </para>
1313
1314 <para>
1315 The core component of any development effort with the Yocto Project is often an
1316 automated build and testing framework along with an image generation process.
1317 You can use these core components to check that the metadata can be built,
1318 highlight when commits break the build, and provide up-to-date images that
1319 allow developers to test the end result and use it as a base platform for further
1320 development.
1321 Experience shows that buildbot is a good fit for this role.
1322 What works well is to configure buildbot to make two types of builds:
1323 incremental and full (from scratch).
1324 See <ulink url='http://www.yoctoproject.org:8010'>the buildbot for the
1325 Yocto Project</ulink> for an example implementation that uses buildbot.
1326 </para>
1327
1328 <para>
1329 You can tie incremental builds to a commit hook that triggers the build
1330 each time a commit is made to the metadata.
1331 This practice results in useful acid tests that determine whether a given commit
1332 breaks the build in some serious way.
1333 Associating a build to a commit can catch a lot of simple errors.
1334 Furthermore, the tests are fast so developers can get quick feedback on changes.
1335 </para>
1336
1337 <para>
1338 Full builds build and test everything from the ground up.
1339 These types of builds usually happen at predetermined times like during the
1340 night when the machine load is low.
1341 </para>
1342
1343 <para>
1344 Most teams have many pieces of software undergoing active development at any given time.
1345 You can derive large benefits by putting these pieces under the control of a source
1346 control system that is compatible with the Yocto Project (i.e. Git or Subversion (SVN).
1347 You can then set the autobuilder to pull the latest revisions of the packages
1348 and test the latest commits by the builds.
1349 This practice quickly highlights issues.
1350 The Yocto Project easily supports testing configurations that use both a
1351 stable known good revision and a floating revision.
1352 The Yocto Project can also take just the changes from specific source control branches.
1353 This capability allows you to track and test specific changes.
1354 </para>
1355
1356 <para>
1357 Perhaps the hardest part of setting this up is defining the software project or
1358 the Yocto Project metadata policies that surround the different source control systems.
1359 Of course circumstances will be different in each case.
1360 However, this situation reveals one of the Yocto Project's advantages -
1361 the system itself does not
1362 force any particular policy on users, unlike a lot of build systems.
1363 The system allows the best policies to be chosen for the given circumstances.
1364 </para>
1365 </section>
1366
1367 <section id="usingpoky-changes-updatingimages">
1368 <title>Updating Existing Images</title>
1369
1370 <para>
1371 Often, rather than re-flashing a new image, you might wish to install updated
1372 packages into an existing running system.
1373 You can do this by first sharing the <filename>tmp/deploy/ipk/</filename> directory
1374 through a web server and then by changing <filename>/etc/opkg/base-feeds.conf</filename>
1375 to point at the shared server.
1376 Following is an example:
1377 <literallayout class='monospaced'>
1378 $ src/gz all http://www.mysite.com/somedir/deploy/ipk/all
1379 $ src/gz armv7a http://www.mysite.com/somedir/deploy/ipk/armv7a
1380 $ src/gz beagleboard http://www.mysite.com/somedir/deploy/ipk/beagleboard
1381 </literallayout>
1382 </para>
1383 </section>
1384 </section>
1385
1384</chapter> 1386</chapter>
1385 1387
1386<!-- 1388<!--
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-14 23:03:27 +0000