summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-04-10 10:30:36 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-04-12 19:35:00 +0100
commitf9e7fba02f2edefec39894c5d022e8e817cdf074 (patch)
tree459171f4d9993994d9c565a68fc3fc8fe6275cfd /documentation/dev-manual
parent7f47526f5c99b09b5c3edc52290729e9303b3030 (diff)
downloadpoky-f9e7fba02f2edefec39894c5d022e8e817cdf074.tar.gz
dev-manual, ref-manual: Created new section on linear revision for packages
Fixes [YOCTO #10995] For the dev-manual, I added a new section on incrementing package revision numbers that explains how the build system uses various variables to create linearly numbered revisions for packages. For the ref-manual, I cross-referenced into the new section from the AUTOSRC and SRCREV variables. (From yocto-docs rev: 53c3092e0f0293f4db0a88659abb4cf1c93f208c) 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.xml101
1 files changed, 96 insertions, 5 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index a6e14bb93c..28a97f14bc 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -7792,6 +7792,9 @@
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>
7796 </para></listitem>
7797 <listitem><para>
7795 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link> 7798 <link linkend='incrementing-a-package-revision-number'>Incrementing a package revision number</link>
7796 </para></listitem> 7799 </para></listitem>
7797 <listitem><para> 7800 <listitem><para>
@@ -7850,8 +7853,8 @@
7850 </para> 7853 </para>
7851 </section> 7854 </section>
7852 7855
7853 <section id='incrementing-a-package-revision-number'> 7856 <section id='incrementing-a-package-version-number'>
7854 <title>Incrementing a Package Revision Number</title> 7857 <title>Incrementing a Package Version Number</title>
7855 7858
7856 <para> 7859 <para>
7857 If a committed change results in changing the package output, 7860 If a committed change results in changing the package output,
@@ -7861,9 +7864,11 @@
7861 Increasing <filename>PR</filename> occurs one of two ways: 7864 Increasing <filename>PR</filename> occurs one of two ways:
7862 <itemizedlist> 7865 <itemizedlist>
7863 <listitem><para>Automatically using a Package Revision 7866 <listitem><para>Automatically using a Package Revision
7864 Service (PR Service).</para></listitem> 7867 Service (PR Service).
7868 </para></listitem>
7865 <listitem><para>Manually incrementing the 7869 <listitem><para>Manually incrementing the
7866 <filename>PR</filename> variable.</para></listitem> 7870 <filename>PR</filename> variable.
7871 </para></listitem>
7867 </itemizedlist> 7872 </itemizedlist>
7868 </para> 7873 </para>
7869 7874
@@ -7873,9 +7878,13 @@
7873 with existing package manager applications such as 7878 with existing package manager applications such as
7874 RPM, APT, and OPKG, using an automated system is much 7879 RPM, APT, and OPKG, using an automated system is much
7875 preferred over a manual system. 7880 preferred over a manual system.
7876 In either system, the main requirement is that version 7881 In either system, the main requirement is that package version
7877 numbering increases in a linear fashion and that a number of 7882 numbering increases in a linear fashion and that a number of
7878 version components exist that support that linear progression. 7883 version components exist that support that linear progression.
7884 For information on how to ensure package revisioning remains
7885 linear, see the
7886 "<link linkend='incrementing-a-package-revision-number'>Incrementing a Package Revision Number</link>"
7887 section.
7879 </para> 7888 </para>
7880 7889
7881 <para> 7890 <para>
@@ -8084,6 +8093,88 @@
8084 </section> 8093 </section>
8085 </section> 8094 </section>
8086 8095
8096 <section id='incrementing-a-package-revision-number'>
8097 <title>Incrementing a Package Revision Number</title>
8098
8099 <para>
8100 When fetching a repository, BitBake uses the
8101 <ulink url='&YOCTO_DOCS_REF_URL;#var-SRCREV'><filename>SRCREV</filename></ulink>
8102 variable to determine the specific revision from which to
8103 build.
8104 You set the <filename>SRCREV</filename> variable to
8105 <ulink url='&YOCTO_DOCS_REF_URL;#var-AUTOREV'><filename>AUTOREV</filename></ulink>
8106 to cause the OpenEmbedded build system to automatically use the
8107 latest revision of the package:
8108 <literallayout class='monospaced'>
8109 SRCREV = "${AUTOREV}"
8110 </literallayout>
8111 </para>
8112
8113 <para>
8114 Furthermore, the <filename>SRCPV</filename> variable returns
8115 the version string of the current package.
8116 This string is used to help define the value of
8117 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>.
8118 If your recipe needs to define the package version (i.e.
8119 <filename>PV</filename>),
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}"
8124 </literallayout>
8125 You can use <filename>SRCPV</filename>, as shown in the
8126 previous example, to automatically update the package version
8127 whenever the revision of the package changes.
8128 The OpenEmbedded build system substitutes
8129 <filename>SRCPV</filename> with the following:
8130 <literallayout class='monospaced'>
8131 AUTOINC+<replaceable>source_revision</replaceable>
8132 </literallayout>
8133 The build system replaces the <filename>AUTOINC</filename> with
8134 a number.
8135 The number used depends on the state of the PR Service:
8136 <itemizedlist>
8137 <listitem><para>
8138 If PR Service is enabled, the build system increments
8139 the number, which is similar to the behavior of
8140 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>.
8141 This behavior results in linearly increasing package
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
8146 hello-world-git_0.0+git1+dd2f5c3565-r0.0_armv7a-neon.ipk
8147 </literallayout>
8148 </para></listitem>
8149 <listitem><para>
8150 If PR Service is not enabled, the build system
8151 replaces the <filename>AUTOINC</filename>
8152 placeholder with zero (i.e. "0").
8153 This results in changing the package version since
8154 the source revision is included.
8155 However, package versions are not increased linearly.
8156 Here is an example:
8157 <literallayout class='monospaced'>
8158 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
8160 </literallayout>
8161 </para></listitem>
8162 </itemizedlist>
8163 </para>
8164
8165 <para>
8166 In summary, the OpenEmbedded build system does not track the
8167 history of package versions for this purpose.
8168 <filename>AUTOINC</filename>, in this case, is comparable to
8169 <filename>PR</filename>.
8170 If PR server is not enabled, <filename>AUTOINC</filename>
8171 in the package version is simply replaced by "0".
8172 If PR server is enabled, the build system keeps track of the
8173 package versions and bumps the number when the package
8174 revision changes.
8175 </para>
8176 </section>
8177
8087 <section id='handling-optional-module-packaging'> 8178 <section id='handling-optional-module-packaging'>
8088 <title>Handling Optional Module Packaging</title> 8179 <title>Handling Optional Module Packaging</title>
8089 8180