[pacman-dev] [PATCH] doc: Document pkgver() function
Originally from Jason St. John's patch, This is a much simplified version explaining some basic functions the four vcs's makepkg supports can use to get package version information. Signed-off-by: William Giokas <1007380@gmail.com> --- I know that Allan didn't like this patch last time it was sent in, and neither did I, but I think that this should be documented. I took out the two terrible package versions for the git section, and cut it down to just the commands used to actually print out the pkgver, not the whole pkgver() { cd ... foo bar baz } which makes a lot more sense and keeps things to a minimum. doc/PKGBUILD.5.txt | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index ea280a0..bb185ea 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -450,6 +450,41 @@ The source URL is divided into three components: *svn*;; revision +*pkgver() Function*:: + This function allows 'makepkg' to automatically update the package version of + a package using a script. This is meant to be used with VCS packages. + *Git*:: + *Using git tags*;; + Example output: 1.5.1.g123defa + + git describe --long | sed 's/-/./' + + *Using the total number of commits (used when there are no tags)*;; + Example output: 0.r6283.g123defa + + echo "0.r$(git rev-list --count HEAD).$(git log -1 --format="%h")" + + *Subversion*:: + Example output: 8546 + + svnversion | tr -d [A-z] + + *Mercurial*:: + Example output: 2813.75881cc5391e + + hg identify -ni | awk 'BEGIN{OFS=".";} {print $2 $1}' + + *Bazaar*:: + Example output: 830 + + bzr revno + + *Fallback*:: + If no acceptable version information can be extracted from the + repository, use the current date. + Example output: 20130408 + + date +%Y%m%d Example ------- -- 1.8.2.1.573.g118f60e
On 23/04/13 17:15, William Giokas wrote:
Originally from Jason St. John's patch, This is a much simplified version explaining some basic functions the four vcs's makepkg supports can use to get package version information.
Signed-off-by: William Giokas <1007380@gmail.com> ---
There were a number of other formatting/typo? fixes in that patch that were good to go. I guess I can edit it just to include those bits if Jason does not resubmit.
I know that Allan didn't like this patch last time it was sent in, and neither did I, but I think that this should be documented. I took out the two terrible package versions for the git section, and cut it down to just the commands used to actually print out the pkgver, not the whole
pkgver() { cd ... foo bar baz }
which makes a lot more sense and keeps things to a minimum.
doc/PKGBUILD.5.txt | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+)
diff --git a/doc/PKGBUILD.5.txt b/doc/PKGBUILD.5.txt index ea280a0..bb185ea 100644 --- a/doc/PKGBUILD.5.txt +++ b/doc/PKGBUILD.5.txt @@ -450,6 +450,41 @@ The source URL is divided into three components:
*svn*;; revision +*pkgver() Function*:: + This function allows 'makepkg' to automatically update the package version of + a package using a script. This is meant to be used with VCS packages.
These examples arrive with no introduction. Add something like "Example commands for use with the various supported VCS are:"
+ *Git*:: + *Using git tags*;; + Example output: 1.5.1.g123defa + + git describe --long | sed 's/-/./'
I am not a fan of this formatting. Also, won't the ' in there break formatting. I think we need a [[source,sh]] block. Also, note I added "Example commands" above so the we know these are commands. I'd put the command first (in the source block) and the example output after.
+ *Using the total number of commits (used when there are no tags)*;; + Example output: 0.r6283.g123defa + + echo "0.r$(git rev-list --count HEAD).$(git log -1 --format="%h")" + + *Subversion*:: + Example output: 8546 + + svnversion | tr -d [A-z] + + *Mercurial*:: + Example output: 2813.75881cc5391e + + hg identify -ni | awk 'BEGIN{OFS=".";} {print $2 $1}' + + *Bazaar*:: + Example output: 830 + + bzr revno +
Just delete the fallback bit:
+ *Fallback*:: + If no acceptable version information can be extracted from the + repository, use the current date. + Example output: 20130408 + + date +%Y%m%d
Example -------
On 2013-04-24 15:15 +1000 Allan McRae wrote:
On 23/04/13 17:15, William Giokas wrote:
Originally from Jason St. John's patch, This is a much simplified version explaining some basic functions the four vcs's makepkg supports can use to get package version information.
/snip
Also, note I added "Example commands" above so the we know these are commands. I'd put the command first (in the source block) and the example output after.
I've seen pkgver functions for Git popping up that include hashtags in the version. I expect that this will become a widespread problem for vercmp-based ordering if it is not discouraged. Perhaps you can add a note about that in the documentation, e.g. "The pkgver function should generate a version string that is correctly ordered in all cases by Pacman's vercmp command. For example, Git hash tags should be avoided as these are pseudo-random. Refer to the vercmp man page for information about how Pacman orders different version strings." Regards, Xyne
On Thu, Apr 25, 2013 at 09:54:13PM +0000, Xyne wrote:
On 2013-04-24 15:15 +1000 Allan McRae wrote:
On 23/04/13 17:15, William Giokas wrote:
Originally from Jason St. John's patch, This is a much simplified version explaining some basic functions the four vcs's makepkg supports can use to get package version information.
/snip
Also, note I added "Example commands" above so the we know these are commands. I'd put the command first (in the source block) and the example output after.
I've seen pkgver functions for Git popping up that include hashtags in the version. I expect that this will become a widespread problem for vercmp-based ordering if it is not discouraged. Perhaps you can add a note about that in the documentation, e.g.
Git describe outputs a versionable string. If there are tags, it will take the latest tag (usually a version, say 4.1.0), and combine it with two more parts. The second part is the number of parents between the named tag and the current HEAD. This makes the git describe so far somethinglike:: 4.1.0-15 I usually call this part the revno, as it's similar to what other vcs's use. But now we get to the part you're talking about, which really doesn't matter anymore, the hash. This I keep on the end to be sure of what version was built. I brought up a more complex sed command that can be used if upstream uses tags like:: 1.8.1 -> 1.8.1.1 -> 1.8.2 -> 1.8.2.1 that adds a 'r' in front of the revno, so the original git describe looks something like:: 4.1.0-15-g99b8d78 and after it's run through the sed command it will look like:: 4.1.0.15.g99b8d78 (or alternately) 4.1.0.r15.g99b8d78 so it's completely versionable including the hash. The second version of the git pkgvers that was in there works similar to other vcs's, using the number of parents between the current HEAD and the initial commit:: 0.r5300.g99b8d78 The '0.r' allows a tag such as '0.1' to be greater than the current version. I am more worried about people using the date of the last commit, which is just a stupid way to do it when you have one of these ways to get the pkgver.
"The pkgver function should generate a version string that is correctly ordered in all cases by Pacman's vercmp command. For example, Git hash tags should be avoided as these are pseudo-random. Refer to the vercmp man page for information about how Pacman orders different version strings."
I'll look at adding this to the pkgver description. I, however, think that hashtags should be included at the very least. -- William Giokas | KaiSforza GnuPG Key: 0x73CD09CF Fingerprint: F73F 50EF BBE2 9846 8306 E6B8 6902 06D8 73CD 09CF
William Giokas <1007380@gmail.com> on Thu, 2013/04/25 17:18:
On Thu, Apr 25, 2013 at 09:54:13PM +0000, Xyne wrote:
I've seen pkgver functions for Git popping up that include hashtags in the version. I expect that this will become a widespread problem for vercmp-based ordering if it is not discouraged. Perhaps you can add a note about that in the documentation, e.g.
Git describe outputs a versionable string. If there are tags, it will take the latest tag (usually a version, say 4.1.0), and combine it with two more parts. The second part is the number of parents between the named tag and the current HEAD. This makes the git describe so far somethinglike::
4.1.0-15
I usually call this part the revno, as it's similar to what other vcs's use.
But now we get to the part you're talking about, which really doesn't matter anymore, the hash. This I keep on the end to be sure of what version was built.
I brought up a more complex sed command that can be used if upstream uses tags like::
1.8.1 -> 1.8.1.1 -> 1.8.2 -> 1.8.2.1
that adds a 'r' in front of the revno, so the original git describe looks something like::
4.1.0-15-g99b8d78
and after it's run through the sed command it will look like::
4.1.0.15.g99b8d78 (or alternately) 4.1.0.r15.g99b8d78
so it's completely versionable including the hash. The second version of the git pkgvers that was in there works similar to other vcs's, using the number of parents between the current HEAD and the initial commit::
0.r5300.g99b8d78
The '0.r' allows a tag such as '0.1' to be greater than the current version.
That is a really good hint! I was suffering this problem from time to time... Thanks a lot! Passing the option '--long' to 'git describe' makes it print the revision and hash even if last commit has a tag.
I am more worried about people using the date of the last commit, which is just a stupid way to do it when you have one of these ways to get the pkgver.
The only case I do this is if the repository has no tags at all. Any better choice then? -- main(a){char*c=/* Schoene Gruesse */"B?IJj;MEH" "CX:;",b;for(a/* Chris get my mail address: */=0;b=c[a++];) putchar(b-1/(/* gcc -o sig sig.c && ./sig */b/42*2-3)*42);}
On Apr 24, 2013 1:15 AM, "Allan McRae" <allan@archlinux.org> wrote:
On 23/04/13 17:15, William Giokas wrote:
Originally from Jason St. John's patch, This is a much simplified version explaining some basic functions the four vcs's makepkg supports can use to get package version information.
Signed-off-by: William Giokas <1007380@gmail.com> ---
There were a number of other formatting/typo? fixes in that patch that were good to go. I guess I can edit it just to include those bits if Jason does not resubmit.
I can resubmit the patch later tonight. Should I base the patch on William's? Or should I just resubmit my original patch with the bad parts removed? Sorry in advance if this isn't sent in plain text. I'm on my mobile now. Jason
On Thu, Apr 25, 2013 at 06:08:10PM -0400, Jason St. John wrote:
On Apr 24, 2013 1:15 AM, "Allan McRae" <allan@archlinux.org> wrote:
On 23/04/13 17:15, William Giokas wrote:
Originally from Jason St. John's patch, This is a much simplified version explaining some basic functions the four vcs's makepkg supports can use to get package version information.
Signed-off-by: William Giokas <1007380@gmail.com> ---
There were a number of other formatting/typo? fixes in that patch that were good to go. I guess I can edit it just to include those bits if Jason does not resubmit.
I can resubmit the patch later tonight. Should I base the patch on William's? Or should I just resubmit my original patch with the bad parts removed?
I think that would be good. If you could just split it up into multiple parts and submit a few patches at a time, that would be best. (I'm no good with asciidoc, to be honest, so I'll leave it to people that know) Thanks, -- William Giokas | KaiSforza GnuPG Key: 0x73CD09CF Fingerprint: F73F 50EF BBE2 9846 8306 E6B8 6902 06D8 73CD 09CF
participants (5)
-
Allan McRae
-
Christian Hesse
-
Jason St. John
-
William Giokas
-
Xyne