Difference between revisions of "Versioning Policy"

From Openembedded.org
Jump to: navigation, search
(Undo revision 3296 by Yjytalamago (Talk))
(Bring up-to-date with current practice)
Line 2: Line 2:
 
There is general confusion about what a correct PV string should look like. This page attempts to define a standard for packages in OpenEmbedded to follow. Whilst not mandatory, it is strongly recommended.
 
There is general confusion about what a correct PV string should look like. This page attempts to define a standard for packages in OpenEmbedded to follow. Whilst not mandatory, it is strongly recommended.
 
   
 
   
OE's versioning policy aims to follow that from [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version Debian] (and is hence compatible with ipkg).  One key phrase to note is "The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters." This means characters like + and - have a higher priority than alphanumeric characters.
+
OE's versioning policy aims to follow that from [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Version Debian] (and is hence compatible with opkg).  One key phrase to note is "The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters." This means characters like + and - have a higher priority than alphanumeric characters.
If in doubt, experiment with the ipkg-compare-versions program from ipkg-utils.
+
If in doubt, experiment with the opkg-compare-versions program from opkg-utils.
 
 
'''NOTE''': this page was based on a [http://handhelds.org/hypermail/oe/42/4249.html email-thread] from [http://lists.openembedded.org/pipermail/openembedded-devel/ openembedded-devel@lists.openembedded.org] and subsequent dicussions.
 
  
 
== Hyphens ==
 
== Hyphens ==
Line 11: Line 9:
 
Our current policy is:
 
Our current policy is:
  
* PN may contain hypens
+
* PN may contain hyphens
* PV should avoid containing hypens
+
* PV should avoid containing hyphens
 
* PR '''must not''' contain hyphens
 
* PR '''must not''' contain hyphens
  
 
It is a common misconception that hyphens are not allowed in PV. Looking at packages/linux shows they can be used but extreme caution is recommended (see pitfalls below). They wouldn't be allowed under Debian rules if PR wasn't specificed but since OE always sets PR by default, hyphens are allowed by default.
 
It is a common misconception that hyphens are not allowed in PV. Looking at packages/linux shows they can be used but extreme caution is recommended (see pitfalls below). They wouldn't be allowed under Debian rules if PR wasn't specificed but since OE always sets PR by default, hyphens are allowed by default.
 
                
 
                
== Date based packages ==
+
== SCM-based packages ==
 +
 
 +
When building software from a non-release version fetched from git, use the following:
 +
 
 +
<code>
 +
PV = "<version>+git${SRCPV}"
 +
</code>
 +
 
 +
Where <code>&lt;version&gt;</code> is the most recent release version number prior to the revision being fetched. SRCREV should be set to point to the revision to fetch; if the specified revision is not on the master branch, specify the branch in the SRC_URI entry with <code>;branch=&lt;branchname&gt;</code>
  
The current policy is to use the format PV = "1.2+scmYYYYMMDD".
+
The recipe file should be named <code>&lt;basename&gt;_git.bb</code>.
  
* cvs packages should use <latest released version>+cvs<date>, e.g. foo_1.3+cvs20051106
+
Similar patterns should be used for recipes fetched from Subversion and other SCMs.
* svn packages should use <latest released version>+svn<date>, e.g. foo_1.3+svn20051106
 
  
 
== Pitfalls ==
 
== Pitfalls ==
Line 33: Line 38:
 
* foo_2.4.4-pre1
 
* foo_2.4.4-pre1
  
cause a lot of trouble with package managers when ''foo_2.4.4'' gets released. So we should use the following:
+
cause a lot of trouble with package managers when the final ''foo_2.4.4'' gets released. So we should use the following:
  
 
* foo_2.4.3+2.4.4rc2
 
* foo_2.4.3+2.4.4rc2
  
 
[[Category:Policy]]
 
[[Category:Policy]]

Revision as of 12:57, 5 June 2014

Version policy for OE recipes

There is general confusion about what a correct PV string should look like. This page attempts to define a standard for packages in OpenEmbedded to follow. Whilst not mandatory, it is strongly recommended.

OE's versioning policy aims to follow that from Debian (and is hence compatible with opkg). One key phrase to note is "The lexical comparison is a comparison of ASCII values modified so that all the letters sort earlier than all the non-letters." This means characters like + and - have a higher priority than alphanumeric characters. If in doubt, experiment with the opkg-compare-versions program from opkg-utils.

Hyphens

Our current policy is:

  • PN may contain hyphens
  • PV should avoid containing hyphens
  • PR must not contain hyphens

It is a common misconception that hyphens are not allowed in PV. Looking at packages/linux shows they can be used but extreme caution is recommended (see pitfalls below). They wouldn't be allowed under Debian rules if PR wasn't specificed but since OE always sets PR by default, hyphens are allowed by default.

SCM-based packages

When building software from a non-release version fetched from git, use the following:

PV = "<version>+git${SRCPV}"

Where <version> is the most recent release version number prior to the revision being fetched. SRCREV should be set to point to the revision to fetch; if the specified revision is not on the master branch, specify the branch in the SRC_URI entry with ;branch=<branchname>

The recipe file should be named <basename>_git.bb.

Similar patterns should be used for recipes fetched from Subversion and other SCMs.

Pitfalls

Prerelease packages such as

  • foo_2.4.4rc2
  • foo_2.4.4b1
  • foo_2.4.4-git5
  • foo_2.4.4-pre1

cause a lot of trouble with package managers when the final foo_2.4.4 gets released. So we should use the following:

  • foo_2.4.3+2.4.4rc2