summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--documentation/dev-manual/dev-manual-common-tasks.xml260
1 files changed, 211 insertions, 49 deletions
diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index e9555e6168..479362fca5 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1974,71 +1974,233 @@
1974 </itemizedlist> 1974 </itemizedlist>
1975 </para> 1975 </para>
1976 1976
1977 <section id="usingpoky-changes-prbump"> 1977 <section id='incrementing-a-package-revision-number'>
1978 <title>Incrementing a Package Revision Number</title> 1978 <title>Incrementing a Package Revision Number</title>
1979 1979
1980 <para> 1980 <para>
1981 If a committed change results in changing the package output, 1981 If a committed change results in changing the package output,
1982 then the value of the 1982 then the value of the
1983 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PR'>PR</ulink></filename> 1983 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
1984 variable needs to be increased 1984 variable needs to be increased (or "bumped").
1985 (or "bumped") as part of that commit. 1985 Increasing <filename>PR</filename> occurs one of two ways:
1986 For new recipes you should add the <filename>PR</filename> 1986 <itemizedlist>
1987 variable and set its initial value equal to "r0", which is the default. 1987 <listitem><para>Automatically using a Package Revision
1988 Even though the default value is "r0", the practice of adding it to a new recipe makes 1988 Service (PR Service).</para></listitem>
1989 it harder to forget to bump the variable when you make changes 1989 <listitem><para>Manually incrementing the
1990 to the recipe in future. 1990 <filename>PR</filename> variable.</para></listitem>
1991 </itemizedlist>
1991 </para> 1992 </para>
1992 1993
1993 <para> 1994 <para>
1994 If you are sharing a common <filename>.inc</filename> file with multiple recipes, 1995 Given that one of the challenges any build system and its
1995 you can also use the 1996 users face is how to maintain a package feed that is compatible
1996 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename> 1997 with existing package manager applications such as
1997 variable to ensure that 1998 RPM, APT, and OPKG, using an automated system is much
1998 the recipes sharing the <filename>.inc</filename> file are rebuilt when the 1999 preferred over a manual system.
1999 <filename>.inc</filename> file itself is changed. 2000 In either system, the main requirement is that version
2000 The <filename>.inc</filename> file must set <filename>INC_PR</filename> 2001 numbering increases in a linear fashion and that a number of
2001 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename> 2002 version components exist that support that linear progression.
2002 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
2003 If the <filename>.inc</filename> file is changed then its
2004 <filename>INC_PR</filename> should be incremented.
2005 </para> 2003 </para>
2006 2004
2007 <para> 2005 <para>
2008 When upgrading the version of a package, assuming the 2006 The following two sections provide information on the PR Service
2009 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename> 2007 and on manual <filename>PR</filename> bumping.
2010 changes, the <filename>PR</filename> variable should be reset to "r0"
2011 (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
2012 </para> 2008 </para>
2013 2009
2014 <para> 2010 <section id='working-with-a-pr-service'>
2015 Usually, version increases occur only to packages. 2011 <title>Working With a PR Service</title>
2016 However, if for some reason <filename>PV</filename> changes but does not
2017 increase, you can increase the
2018 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
2019 variable (Package Epoch).
2020 The <filename>PE</filename> variable defaults to "0".
2021 </para>
2022 2012
2023 <para> 2013 <para>
2024 Version numbering strives to follow the 2014 As mentioned, attempting to maintain revision numbers in the
2025 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'> 2015 <ulink url='&YOCTO_DOCS_DEV_URL;#metadata'>Metadata</ulink>
2026 Debian Version Field Policy Guidelines</ulink>. 2016 is error prone, inaccurate and causes problems for people
2027 These guidelines define how versions are compared and what "increasing" a version means. 2017 submitting recipes.
2028 </para> 2018 Conversely, the PR Service automatically generates
2019 increasing numbers, particularly the revision field,
2020 which removes the human element.
2021 <note>
2022 For additional information on using a PR Service, you
2023 can see the
2024 <ulink url='&YOCTO_WIKI_URL;/wiki/PR_Service'>PR Service</ulink>
2025 wiki page.
2026 </note>
2027 </para>
2029 2028
2030 <para> 2029 <para>
2031 There are two reasons for following the previously mentioned guidelines. 2030 The Yocto Project uses variables in order of
2032 First, to ensure that when a developer updates and rebuilds, they get all the changes to 2031 decreasing priority to facilitate revision numbering (i.e.
2033 the repository and do not have to remember to rebuild any sections. 2032 <ulink url='&YOCTO_DOCS_REF_URL;#var-PE'><filename>PE</filename></ulink>,
2034 Second, to ensure that target users are able to upgrade their 2033 <ulink url='&YOCTO_DOCS_REF_URL;#var-PV'><filename>PV</filename></ulink>, and
2035 devices using package manager commands such as <filename>opkg upgrade</filename> 2034 <ulink url='&YOCTO_DOCS_REF_URL;#var-PR'><filename>PR</filename></ulink>
2036 (or similar commands for dpkg/apt or rpm-based systems). 2035 for epoch, version and revision, respectively).
2037 </para> 2036 The values are highly dependent on the policies and
2037 procedures of a given distribution and package feed.
2038 </para>
2038 2039
2039 <para> 2040 <para>
2040 The goal is to ensure the Yocto Project has packages that can be upgraded in all cases. 2041 Because the OpenEmbedded build system uses "signatures",
2041 </para> 2042 which are unique to a given build, the build system
2043 knows when to rebuild packages.
2044 All the inputs into a given task are represented by a
2045 signature, which can trigger a rebuild when different.
2046 Thus, the build system itself does not rely on the
2047 <filename>PR</filename> numbers to trigger a rebuild.
2048 The signatures, however, can be used to generate
2049 <filename>PR</filename> values.
2050 </para>
2051
2052 <para>
2053 The PR Service works with both
2054 <filename>OEBasic</filename> and
2055 <filename>OEBasicHash</filename> generators.
2056 The value of <filename>PR</filename> bumps when the
2057 checksum changes and the different generator mechanisms
2058 change signatures under different circumstances.
2059 </para>
2060
2061 <para>
2062 As implemented, the build system includes values from
2063 the PR Service into the <filename>PR</filename> field as
2064 an addition using the form "<filename>.x</filename>" so
2065 <filename>r0</filename> becomes <filename>r0.1</filename>,
2066 <filename>r0.2</filename> and so forth.
2067 This scheme allows existing <filename>PR</filename> values
2068 to be used for whatever reasons, which include manual
2069 <filename>PR</filename> bumps should it be necessary.
2070 </para>
2071
2072 <para>
2073 By default, there is no server that runs the PR Service.
2074 Thus, the packages generated are just "self consistent".
2075 The build system adds and removes packages and
2076 there are no guarantees about upgrade paths.
2077 </para>
2078
2079 <para>
2080 The simplest form for a PR Service is for it to exist
2081 for a single host development system that builds the
2082 package feed (building system).
2083 For this scenario, you can enable the PR Service by adding
2084 the following to your <filename>local.conf</filename>
2085 file in the
2086 <ulink url='&YOCTO_DOCS_DEV_URL;#build-directory'>Build Directory</ulink>:
2087 <literallayout class='monospaced'>
2088 PRSERV_HOST = "localhost:0"
2089 </literallayout>
2090 Once the service is started, packages will automatically
2091 get increasing <filename>PR</filename> values and
2092 BitBake will take care of starting and stopping the server.
2093 </para>
2094
2095 <para>
2096 If you have a more complex setup where multiple host
2097 development systems work against a common, shared package
2098 feed, you have a single PR Service running and it is
2099 connected to each building system.
2100 For this scenario, you need to start the PR Service using
2101 the <filename>bitbake-prserv</filename> command:
2102 <literallayout class='monospaced'>
2103 bitbake-prserve &dash;&dash;host &lt;ip&gt; &dash;&dash;port &lt;port&gt; &dash;&dash;start
2104 </literallayout>
2105 In addition to hand-starting the service, you need to
2106 update the <filename>local.conf</filename> file of each
2107 building system as described earlier so each system
2108 points to the server and port.
2109 </para>
2110
2111 <para>
2112 It is also recommended you use build history, which adds
2113 some sanity checks to package versions, in conjunction with
2114 the server that is running the PR Service.
2115 To enable build history, add the following to each building
2116 system's <filename>local.conf</filename> file:
2117 <literallayout class='monospaced'>
2118 # It is recommended to activate "buildhistory" for testing the PR service
2119 INHERIT += "buildhistory"
2120 BUILDHISTORY_COMMIT = "1"
2121 </literallayout>
2122 For information on build history, see the
2123 "<ulink url='&YOCTO_DOCS_REF_URL;#maintaining-build-output-quality'>Maintaining Build Output Quality</ulink>"
2124 section in the Yocto Project Reference Manual.
2125 </para>
2126
2127 <note>
2128 The OpenEmbedded build system does not maintain
2129 <filename>PR</filename> information as part of the
2130 shared state (sstate) packages.
2131 If you maintain an sstate feed, its expected that either
2132 all your building systems that contribute to the sstate
2133 feed use a shared PR Service, or you do not run a PR
2134 Service on any of your building systems.
2135 Having some systems use a PR Service while others do
2136 not leads to obvious problems.
2137 </note>
2138 </section>
2139
2140 <section id='manually-bumping-pr'>
2141 <title>Manually Bumping PR</title>
2142
2143 <para>
2144 If a committed change results in changing the package output,
2145 then the value of the PR variable needs to be increased
2146 (or "bumped") as part of that commit.
2147 For new recipes you should add the <filename>PR</filename>
2148 variable and set its initial value equal to "r0", which is the default.
2149 Even though the default value is "r0", the practice of adding it to a new recipe makes
2150 it harder to forget to bump the variable when you make changes
2151 to the recipe in future.
2152 </para>
2153
2154 <para>
2155 If you are sharing a common <filename>.inc</filename> file with multiple recipes,
2156 you can also use the
2157 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-INC_PR'>INC_PR</ulink></filename>
2158 variable to ensure that
2159 the recipes sharing the <filename>.inc</filename> file are rebuilt when the
2160 <filename>.inc</filename> file itself is changed.
2161 The <filename>.inc</filename> file must set <filename>INC_PR</filename>
2162 (initially to "r0"), and all recipes referring to it should set <filename>PR</filename>
2163 to "$(INC_PR).0" initially, incrementing the last number when the recipe is changed.
2164 If the <filename>.inc</filename> file is changed then its
2165 <filename>INC_PR</filename> should be incremented.
2166 </para>
2167
2168 <para>
2169 When upgrading the version of a package, assuming the
2170 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PV'>PV</ulink></filename>
2171 changes, the <filename>PR</filename> variable should be reset to "r0"
2172 (or "$(INC_PR).0" if you are using <filename>INC_PR</filename>).
2173 </para>
2174
2175 <para>
2176 Usually, version increases occur only to packages.
2177 However, if for some reason <filename>PV</filename> changes but does not
2178 increase, you can increase the
2179 <filename><ulink url='&YOCTO_DOCS_REF_URL;#var-PE'>PE</ulink></filename>
2180 variable (Package Epoch).
2181 The <filename>PE</filename> variable defaults to "0".
2182 </para>
2183
2184 <para>
2185 Version numbering strives to follow the
2186 <ulink url='http://www.debian.org/doc/debian-policy/ch-controlfields.html'>
2187 Debian Version Field Policy Guidelines</ulink>.
2188 These guidelines define how versions are compared and what "increasing" a version means.
2189 </para>
2190
2191 <para>
2192 There are two reasons for following the previously mentioned guidelines.
2193 First, to ensure that when a developer updates and rebuilds, they get all the changes to
2194 the repository and do not have to remember to rebuild any sections.
2195 Second, to ensure that target users are able to upgrade their
2196 devices using package manager commands such as <filename>opkg upgrade</filename>
2197 (or similar commands for dpkg/apt or rpm-based systems).
2198 </para>
2199
2200 <para>
2201 The goal is to ensure the Yocto Project has packages that can be upgraded in all cases.
2202 </para>
2203 </section>
2042 </section> 2204 </section>
2043 2205
2044 <section id="usingpoky-configuring-DISTRO_PN_ALIAS"> 2206 <section id="usingpoky-configuring-DISTRO_PN_ALIAS">