summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-04-11 11:55:38 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-04-12 19:35:00 +0100
commit94467d5087ca3b13e7baac670af107550701b333 (patch)
tree61435edce7a9c765669e74b5229478ff97fa45e5 /documentation/dev-manual
parentf9e7fba02f2edefec39894c5d022e8e817cdf074 (diff)
downloadpoky-94467d5087ca3b13e7baac670af107550701b333.tar.gz
dev-manual, ref-manual: Edits to the "Incrementing Binary Package" section.
Fixes [YOCTO #10995] I applied some revisions to the related sections for incrementing a binary package version and revision sections. Mainly clarified terminology and pulled the sections into one single section head. I also cleaned up referencing to all these sections throughout the YP manual set (i.e. the ref-manual). (From yocto-docs rev: 7deda18dd496cc383c5de71a10f2b11b1ca0688f) Signed-off-by: Scott Rifenbark <srifenbark@gmail.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual')
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml284
1 files changed, 170 insertions, 114 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 28a97f14bc..d2bd56dc13 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7792,10 +7792,7 @@
7792 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link> 7792 <link linkend='excluding-packages-from-an-image'>Excluding packages from an image</link>
7793 </para></listitem> 7793 </para></listitem>
7794 <listitem><para> 7794 <listitem><para>
7795 <link linkend='incrementing-a-package-version-number'>Incrementing a package version number</link> 7795 <link linkend='incrementing-a-binary-package-version'>Incrementing a binary package version</link>
7796 </para></listitem>
7797 <listitem><para>
7798 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
7799 </para></listitem> 7796 </para></listitem>
7800 <listitem><para> 7797 <listitem><para>
7801 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link> 7798 <link linkend='handling-optional-module-packaging'>Handling optional module packaging</link>
@@ -7853,43 +7850,102 @@
7853 </para> 7850 </para>
7854 </section> 7851 </section>
7855 7852
7856 <section id='incrementing-a-package-version-number'> 7853 <section id='incrementing-a-binary-package-version'>
7857 <title>Incrementing a Package Version Number</title> 7854 <title>Incrementing a Package Version</title>
7855
7856 <para>
7857 The scheme the OpenEmbedded build system uses for binary
7858 package versioning is a bit involved.
7859 This section provides some background on how binary package
7860 versioning is accomplished and presents some of the services,
7861 variables, and terminology involved.
7862 </para>
7863
7864 <para>
7865 In order to understand binary package versioning, you need
7866 to consider the following:
7867 <itemizedlist>
7868 <listitem><para>
7869 Binary Package: The binary package that is eventually
7870 built and installed into an image.
7871 </para></listitem>
7872 <listitem><para>
7873 Binary Package Version: The binary package version
7874 is composed of two components - a version and a
7875 revision.
7876 <note>
7877 Technically, the "epoch" (i.e.
7878 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>)
7879 is involved but this discussion for the most part
7880 ignores <filename>PE</filename>.
7881 </note>
7882 The version and revision are taken from the
7883 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>
7884 and
7885 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
7886 variables, respectively.
7887 </para></listitem>
7888 <listitem><para>
7889 <filename>PV</filename>: The recipe version, which is
7890 not to be confused with the binary package version.
7891 </para></listitem>
7892 <listitem><para>
7893 <filename>PR</filename>: The recipe revision.
7894 </para></listitem>
7895 <listitem><para>
7896 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCPV'><filename>SRCPV</filename></ulink>:
7897 The Version string of the binary package.
7898 The OpenEmbedded build system uses this string
7899 to help define the value of <filename>PV</filename>.
7900 </para></listitem>
7901 <listitem><para>
7902 <ulink url='https://wiki.yoctoproject.org/wiki/PR_Service'>PR Service</ulink>:
7903 A network-based service that helps automate keeping
7904 package feeds compatible with existing package
7905 manager applications such as RPM, APT, and OPKG.
7906 </para></listitem>
7907 </itemizedlist>
7908 </para>
7858 7909
7859 <para> 7910 <para>
7860 If a committed change results in changing the package output, 7911 Whenever the binary package output changes, the binary package
7861 then the value of the 7912 version must change.
7862 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> 7913 Changing the binary package version is accomplished by changing
7863 variable needs to be increased (or "bumped"). 7914 or "bumping" the <filename>PR</filename> and/or
7864 Increasing <filename>PR</filename> occurs one of two ways: 7915 <filename>PV</filename> values.
7916 Increasing these values occurs one of two ways:
7865 <itemizedlist> 7917 <itemizedlist>
7866 <listitem><para>Automatically using a Package Revision 7918 <listitem><para>Automatically using a Package Revision
7867 Service (PR Service). 7919 Service (PR Service).
7868 </para></listitem> 7920 </para></listitem>
7869 <listitem><para>Manually incrementing the 7921 <listitem><para>Manually incrementing the
7870 <filename>PR</filename> variable. 7922 <filename>PR</filename> and/or
7923 <filename>PV</filename> variables.
7871 </para></listitem> 7924 </para></listitem>
7872 </itemizedlist> 7925 </itemizedlist>
7873 </para> 7926 </para>
7874 7927
7875 <para> 7928 <para>
7876 Given that one of the challenges any build system and its 7929 Given a primary challenge of any build system and its users
7877 users face is how to maintain a package feed that is compatible 7930 is how to maintain a package feed that is compatible with
7878 with existing package manager applications such as 7931 existing package manager applications such as RPM, APT, and
7879 RPM, APT, and OPKG, using an automated system is much 7932 OPKG, using an automated system is much preferred over a
7880 preferred over a manual system. 7933 manual system.
7881 In either system, the main requirement is that package version 7934 In either system, the main requirement is that binary package
7882 numbering increases in a linear fashion and that a number of 7935 version numbering increases in a linear fashion and that a
7883 version components exist that support that linear progression. 7936 number of version components exist that support that linear
7937 progression.
7884 For information on how to ensure package revisioning remains 7938 For information on how to ensure package revisioning remains
7885 linear, see the 7939 linear, see the
7886 "<link linkend='incrementing-a-package-revision-number'>Incrementing a Package Revision Number</link>" 7940 "<link linkend='incrementing-a-binary-package-revision-number'>Incrementing a Binary Package Revision Number</link>"
7887 section. 7941 section.
7888 </para> 7942 </para>
7889 7943
7890 <para> 7944 <para>
7891 The following two sections provide information on the PR Service 7945 The following three sections provide related information on the
7892 and on manual <filename>PR</filename> bumping. 7946 PR Service, the manual method for "bumping"
7947 <filename>PR</filename> and/or <filename>PV</filename>, and
7948 on how to ensure binary package revisioning remains linear.
7893 </para> 7949 </para>
7894 7950
7895 <section id='working-with-a-pr-service'> 7951 <section id='working-with-a-pr-service'>
@@ -7930,9 +7986,10 @@
7930 All the inputs into a given task are represented by a 7986 All the inputs into a given task are represented by a
7931 signature, which can trigger a rebuild when different. 7987 signature, which can trigger a rebuild when different.
7932 Thus, the build system itself does not rely on the 7988 Thus, the build system itself does not rely on the
7933 <filename>PR</filename> numbers to trigger a rebuild. 7989 <filename>PR</filename>, <filename>PV</filename>, and
7990 <filename>PE</filename> numbers to trigger a rebuild.
7934 The signatures, however, can be used to generate 7991 The signatures, however, can be used to generate
7935 <filename>PR</filename> values. 7992 these values.
7936 </para> 7993 </para>
7937 7994
7938 <para> 7995 <para>
@@ -7977,7 +8034,7 @@
7977 </literallayout> 8034 </literallayout>
7978 Once the service is started, packages will automatically 8035 Once the service is started, packages will automatically
7979 get increasing <filename>PR</filename> values and 8036 get increasing <filename>PR</filename> values and
7980 BitBake will take care of starting and stopping the server. 8037 BitBake takes care of starting and stopping the server.
7981 </para> 8038 </para>
7982 8039
7983 <para> 8040 <para>
@@ -7998,8 +8055,8 @@
7998 8055
7999 <para> 8056 <para>
8000 It is also recommended you use build history, which adds 8057 It is also recommended you use build history, which adds
8001 some sanity checks to package versions, in conjunction with 8058 some sanity checks to binary package versions, in
8002 the server that is running the PR Service. 8059 conjunction with the server that is running the PR Service.
8003 To enable build history, add the following to each building 8060 To enable build history, add the following to each building
8004 system's <filename>local.conf</filename> file: 8061 system's <filename>local.conf</filename> file:
8005 <literallayout class='monospaced'> 8062 <literallayout class='monospaced'>
@@ -8013,18 +8070,23 @@
8013 </para> 8070 </para>
8014 8071
8015 <note> 8072 <note>
8016 <para>The OpenEmbedded build system does not maintain 8073 <para>
8017 <filename>PR</filename> information as part of the 8074 The OpenEmbedded build system does not maintain
8018 shared state (sstate) packages. 8075 <filename>PR</filename> information as part of the
8019 If you maintain an sstate feed, its expected that either 8076 shared state (sstate) packages.
8020 all your building systems that contribute to the sstate 8077 If you maintain an sstate feed, its expected that either
8021 feed use a shared PR Service, or you do not run a PR 8078 all your building systems that contribute to the sstate
8022 Service on any of your building systems. 8079 feed use a shared PR Service, or you do not run a PR
8023 Having some systems use a PR Service while others do 8080 Service on any of your building systems.
8024 not leads to obvious problems.</para> 8081 Having some systems use a PR Service while others do
8025 <para>For more information on shared state, see the 8082 not leads to obvious problems.
8026 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>" 8083 </para>
8027 section in the Yocto Project Reference Manual.</para> 8084
8085 <para>
8086 For more information on shared state, see the
8087 "<ulink url='&YOCTO_DOCS_REF_URL;#shared-state-cache'>Shared State Cache</ulink>"
8088 section in the Yocto Project Reference Manual.
8089 </para>
8028 </note> 8090 </note>
8029 </section> 8091 </section>
8030 8092
@@ -8033,7 +8095,7 @@
8033 8095
8034 <para> 8096 <para>
8035 The alternative to setting up a PR Service is to manually 8097 The alternative to setting up a PR Service is to manually
8036 bump the 8098 "bump" the
8037 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink> 8099 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
8038 variable. 8100 variable.
8039 </para> 8101 </para>
@@ -8067,7 +8129,7 @@
8067 </para> 8129 </para>
8068 8130
8069 <para> 8131 <para>
8070 When upgrading the version of a package, assuming the 8132 When upgrading the version of a binary package, assuming the
8071 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> 8133 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
8072 changes, the <filename>PR</filename> variable should be 8134 changes, the <filename>PR</filename> variable should be
8073 reset to "r0" (or "${INC_PR}.0" if you are using 8135 reset to "r0" (or "${INC_PR}.0" if you are using
@@ -8075,7 +8137,7 @@
8075 </para> 8137 </para>
8076 8138
8077 <para> 8139 <para>
8078 Usually, version increases occur only to packages. 8140 Usually, version increases occur only to binary packages.
8079 However, if for some reason <filename>PV</filename> changes 8141 However, if for some reason <filename>PV</filename> changes
8080 but does not increase, you can increase the 8142 but does not increase, you can increase the
8081 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename> 8143 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
@@ -8084,95 +8146,89 @@
8084 </para> 8146 </para>
8085 8147
8086 <para> 8148 <para>
8087 Version numbering strives to follow the 8149 Binary package version numbering strives to follow the
8088 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> 8150 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
8089 Debian Version Field Policy Guidelines</ulink>. 8151 Debian Version Field Policy Guidelines</ulink>.
8090 These guidelines define how versions are compared and what 8152 These guidelines define how versions are compared and what
8091 "increasing" a version means. 8153 "increasing" a version means.
8092 </para> 8154 </para>
8093 </section> 8155 </section>
8094 </section>
8095 8156
8096 <section id='incrementing-a-package-revision-number'> 8157 <section id='incrementing-a-binary-package-revision-number'>
8097 <title>Incrementing a Package Revision Number</title> 8158 <title>Incrementing a Binary Package Revision Number</title>
8098 8159
8099 <para> 8160 <para>
8100 When fetching a repository, BitBake uses the 8161 When fetching a repository, BitBake uses the
8101 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink> 8162 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
8102 variable to determine the specific revision from which to 8163 variable to determine the specific revision from which to
8103 build. 8164 build.
8104 You set the <filename>SRCREV</filename> variable to 8165 You set the <filename>SRCREV</filename> variable to
8105 <ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink> 8166 <ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>
8106 to cause the OpenEmbedded build system to automatically use the 8167 to cause the OpenEmbedded build system to automatically use the
8107 latest revision of the package: 8168 latest revision of the package:
8108 <literallayout class='monospaced'> 8169 <literallayout class='monospaced'>
8109 SRCREV = "${AUTOREV}" 8170 SRCREV = "${AUTOREV}"
8110 </literallayout> 8171 </literallayout>
8111 </para> 8172 </para>
8112 8173
8113 <para> 8174 <para>
8114 Furthermore, the <filename>SRCPV</filename> variable returns 8175 Furthermore, you need to reference <filename>SRCPV</filename>
8115 the version string of the current package. 8176 in <filename>PV</filename> in order to automatically update
8116 This string is used to help define the value of 8177 the binary package version whenever the revision of the
8117 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>. 8178 source code changes.
8118 If your recipe needs to define the package version (i.e. 8179 Here is an example:
8119 <filename>PV</filename>), 8180 <literallayout class='monospaced'>
8120 they do this with the help of <filename>SRCPV</filename>.
8121 Here is an example:
8122 <literallayout class='monospaced'>
8123 PV = "1.0+git${SRCPV}" 8181 PV = "1.0+git${SRCPV}"
8124 </literallayout> 8182 </literallayout>
8125 You can use <filename>SRCPV</filename>, as shown in the 8183 The OpenEmbedded build system substitutes
8126 previous example, to automatically update the package version 8184 <filename>SRCPV</filename> with the following:
8127 whenever the revision of the package changes. 8185 <literallayout class='monospaced'>
8128 The OpenEmbedded build system substitutes 8186 AUTOINC+<replaceable>source_code_revision</replaceable>
8129 <filename>SRCPV</filename> with the following: 8187 </literallayout>
8130 <literallayout class='monospaced'> 8188 The build system replaces the <filename>AUTOINC</filename> with
8131 AUTOINC+<replaceable>source_revision</replaceable> 8189 a number.
8132 </literallayout> 8190 The number used depends on the state of the PR Service:
8133 The build system replaces the <filename>AUTOINC</filename> with 8191 <itemizedlist>
8134 a number. 8192 <listitem><para>
8135 The number used depends on the state of the PR Service: 8193 If PR Service is enabled, the build system increments
8136 <itemizedlist> 8194 the number, which is similar to the behavior of
8137 <listitem><para> 8195 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>.
8138 If PR Service is enabled, the build system increments 8196 This behavior results in linearly increasing package
8139 the number, which is similar to the behavior of 8197 versions, which is desirable.
8140 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>. 8198 Here is an example:
8141 This behavior results in linearly increasing package 8199 <literallayout class='monospaced'>
8142 versions, which is desirable.
8143 Here is an example:
8144 <literallayout class='monospaced'>
8145 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk 8200 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
8146 hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk 8201 hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk
8147 </literallayout> 8202 </literallayout>
8148 </para></listitem> 8203 </para></listitem>
8149 <listitem><para> 8204 <listitem><para>
8150 If PR Service is not enabled, the build system 8205 If PR Service is not enabled, the build system
8151 replaces the <filename>AUTOINC</filename> 8206 replaces the <filename>AUTOINC</filename>
8152 placeholder with zero (i.e. "0"). 8207 placeholder with zero (i.e. "0").
8153 This results in changing the package version since 8208 This results in changing the package version since
8154 the source revision is included. 8209 the source revision is included.
8155 However, package versions are not increased linearly. 8210 However, package versions are not increased linearly.
8156 Here is an example: 8211 Here is an example:
8157 <literallayout class='monospaced'> 8212 <literallayout class='monospaced'>
8158 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk 8213 hello-world-git_0.0+git0+b6558dd387-r0.0_armv7a-neon.ipk
8159 hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk 8214 hello-world-git_0.0+git0+dd2f5c3565-r0.0_armv7a-neon.ipk
8160 </literallayout> 8215 </literallayout>
8161 </para></listitem> 8216 </para></listitem>
8162 </itemizedlist> 8217 </itemizedlist>
8163 </para> 8218 </para>
8164 8219
8165 <para> 8220 <para>
8166 In summary, the OpenEmbedded build system does not track the 8221 In summary, the OpenEmbedded build system does not track the
8167 history of package versions for this purpose. 8222 history of binary package versions for this purpose.
8168 <filename>AUTOINC</filename>, in this case, is comparable to 8223 <filename>AUTOINC</filename>, in this case, is comparable to
8169 <filename>PR</filename>. 8224 <filename>PR</filename>.
8170 If PR server is not enabled, <filename>AUTOINC</filename> 8225 If PR server is not enabled, <filename>AUTOINC</filename>
8171 in the package version is simply replaced by "0". 8226 in the package version is simply replaced by "0".
8172 If PR server is enabled, the build system keeps track of the 8227 If PR server is enabled, the build system keeps track of the
8173 package versions and bumps the number when the package 8228 package versions and bumps the number when the package
8174 revision changes. 8229 revision changes.
8175 </para> 8230 </para>
8231 </section>
8176 </section> 8232 </section>
8177 8233
8178 <section id='handling-optional-module-packaging'> 8234 <section id='handling-optional-module-packaging'>