Difference between revisions of "VCS package guidelines"

From ArchWiki
Jump to: navigation, search
m (Mercurial)
(SVN packages that try to get their revision number: no longer needed since 4.1.1)
(33 intermediate revisions by 8 users not shown)
Line 5: Line 5:
 
{{Package Guidelines}}
 
{{Package Guidelines}}
  
[[Wikipedia:Revision_control|Version control systems]] can be used for retrieval of source code for both usual statically versioned packages and latest (trunk) version of packages. This article covers both cases.
+
[[Wikipedia:Revision_control|Version control systems]] can be used for retrieval of source code for both usual statically versioned packages and latest (trunk) version of a development branch. This article covers both cases.
  
 
== Prototypes ==
 
== Prototypes ==
Line 25: Line 25:
 
* When using the cvsroot, use {{Ic|anonymous:@}} rather than {{Ic|anonymous@}} to avoid having to enter a blank password or {{Ic|anonymous:password@}}, if one is required.
 
* When using the cvsroot, use {{Ic|anonymous:@}} rather than {{Ic|anonymous@}} to avoid having to enter a blank password or {{Ic|anonymous:password@}}, if one is required.
  
* Include the appropriate VCS tool in {{Ic|1=makedepends}} ({{pkg|cvs}}, {{pkg|subversion}}, {{pkg|git}}, ...).
+
* Include the appropriate VCS tool in {{Ic|1=makedepends=()}} ({{pkg|cvs}}, {{pkg|subversion}}, {{pkg|git}}, ...).
  
 
=== VCS sources ===
 
=== VCS sources ===
Line 44: Line 44:
  
 
=== The pkgver() function ===
 
=== The pkgver() function ===
The {{ic|pkgver}} autobump is now achieved via a dedicated {{ic|pkgver()}} function. This allows for better control over the {{ic|pkgver}}, and maintainers should favor a {{ic|pkgver}} that makes sense. Following are some examples for several VCS.
+
The {{ic|pkgver}} autobump is now achieved via a dedicated {{ic|pkgver()}} function. This allows for better control over the {{ic|pkgver}}, and maintainers should favor a {{ic|pkgver}} that makes sense. Following are some examples showing the ''intended'' output:
  
 
==== Git ====
 
==== Git ====
With tags:
 
  
pkgver() {
+
Using the tag of the last commit:
  cd local_repo
+
  git describe --always | sed 's|-|.|g'
+
}
+
  
Without tags:
+
{{hc|<nowiki>pkgver() {
 +
  cd local_repo
 +
  git describe --always | sed 's|-|.|g'
 +
}</nowiki>|
 +
2.0.6.a17a017
 +
}}
  
pkgver() {
+
If there are no annotated tags:
  cd local_repo
+
  echo "0.$(git rev-list --count HEAD).$(git describe --always)"
+
}
+
  
Using the last commit date:
+
{{hc|<nowiki>pkgver() {
 
+
  cd local_repo
pkgver() {
+
  echo $(git rev-list --count HEAD).$(git rev-parse --short HEAD)
  cd local_repo
+
}</nowiki>|
  git log -1 --format="%cd" --date=short | tr -d '-'
+
1142.a17a017
}
+
}}
 
+
Using the timestamp of the last commit:
+
pkgver() {
+
  cd local_repo
+
  git log -1 --format=%cd --date=raw | awk '{print $1}'
+
}
+
  
 
==== Subversion ====
 
==== Subversion ====
pkgver() {
+
{{hc|<nowiki>pkgver() {
  cd "$SRCDEST"/local_repo
+
  cd local_repo
  svnversion |tr -d [A-z]
+
  svnversion | tr -d [A-z]
}
+
}</nowiki>|
 
+
8546
{{Note|The copy inside {{ic|$srcdir}} is made using {{ic|svn export}} which does not create working copies. Any {{ic|svn}} related command has to be used in the local repo, hence {{ic|$SRCDEST}}.}}
+
}}
  
 
==== Mercurial ====
 
==== Mercurial ====
pkgver() {
+
{{hc|<nowiki>pkgver() {
  cd local_repo
+
  cd local_repo
  hg identify -ni | awk 'BEGIN{OFS=".";} {print $2,$1}'
+
  echo $(hg identify -n).$(hg identify -i)
}
+
}</nowiki>|
 +
2813.75881cc5391e
 +
}}
  
 
==== Bazaar ====
 
==== Bazaar ====
pkgver() {
+
{{hc|<nowiki>pkgver() {
  cd "$srcdir"/local_repo
+
  cd local_repo
  bzr revno
+
  bzr revno
}
+
}</nowiki>|
 +
830
 +
}}
  
 
==== Fallback ====
 
==== Fallback ====
The following can be used in case no satisfactory {{ic|pkgver}} can be extracted from the repo:
+
The current date can be used, in case no satisfactory {{ic|pkgver}} can be extracted from the repo:
  
pkgver() {
+
{{hc|<nowiki>pkgver() {
  date +"%Y%m%d"
+
  date +%Y%m%d
}
+
}</nowiki>|
 +
20130408
 +
}}
  
 
== Tips ==
 
== Tips ==
  
=== A sample Git PKGBUILD for pacman 4.1 ===
+
=== A sample Git PKGBUILD ===
 
  # Maintainer: Dave Reisner <d@falconindy.com>  
 
  # Maintainer: Dave Reisner <d@falconindy.com>  
 
  # Contributor: William Giokas (KaiSforza) <1007380@gmail.com>
 
  # Contributor: William Giokas (KaiSforza) <1007380@gmail.com>
Line 119: Line 117:
 
  conflicts=('expac')
 
  conflicts=('expac')
 
  provides=('expac')
 
  provides=('expac')
  # Here is the fun bit. Makepkg knows it's a git repo because the URL starts with 'git'
+
  # The git repo is detected by the 'git:' or 'git+' beginning. The branch
  # it then knows to checkout the branch 'pacman41' upon cloning, expediating versioning:
+
  # 'pacman41' is then checked out upon cloning, expediating versioning:
 
  #source=('git+https://github.com/falconindy/expac.git'
 
  #source=('git+https://github.com/falconindy/expac.git'
 
  source=('git://github.com/falconindy/expac.git'
 
  source=('git://github.com/falconindy/expac.git'
Line 129: Line 127:
 
   
 
   
 
  pkgver() {
 
  pkgver() {
   cd "$srcdir/$_gitname"
+
   cd $_gitname
 +
  # Use the tag of the last commit
 
   git describe --always | sed 's|-|.|g'
 
   git describe --always | sed 's|-|.|g'
  # To give the total count of commits and the hash of the last one
 
  # (useful if you're making a repository with git packages so that they can have
 
  # sequential version numbers, else a "pacman -Syu" may not update the package):
 
  #echo "0.$(git rev-list --count $branch).$(git describe --always)"
 
  # Using the last commit date:
 
  #git log -1 --format="%cd" --date=short | sed 's|-||g'
 
 
  }
 
  }
 
   
 
   
 
  build() {
 
  build() {
   cd "$srcdir/$_gitname"
+
   cd $_gitname
 
   make
 
   make
 
  }
 
  }
 
   
 
   
 
  package() {
 
  package() {
   cd "$srcdir/$_gitname"
+
   cd $_gitname
 
   make PREFIX=/usr DESTDIR="$pkgdir" install
 
   make PREFIX=/usr DESTDIR="$pkgdir" install
 
   install -Dm644 "$srcdir/expac_icon.png" "$pkgdir/usr/share/pixmaps/expac.png"
 
   install -Dm644 "$srcdir/expac_icon.png" "$pkgdir/usr/share/pixmaps/expac.png"
 
  }
 
  }
 
=== Removing VCS leftovers ===
 
To make sure that there are no VCS leftovers use the following at the end of the {{ic|package()}} function (replacing {{ic|'''.git'''}} with {{ic|.svn}}, {{ic|.hg}}, etc.):
 
find "$pkgdir" -type d -name "'''.git'''" -exec rm -r '{}' +
 
 
=== SVN packages that try to get their revision number ===
 
If the build system for the program you are packaging calls {{ic|svnversion}} or {{ic|svn info}} to determine its revision number, you can add a {{ic|prepare()}} function similar to this one to make it work:
 
 
prepare() {
 
  cp -a "$SRCDEST/$_svnmod/.svn" "$srcdir/$_svnmod/"
 
}
 
 
== Troubleshooting ==
 
 
=== Bazaar limitation ===
 
Currently, bazaar URLs only work in the form of {{ic|http://bazaar.launchpad.net/}}, e.g.:
 
source=('project_name::bzr+http://bazaar.launchpad.net/~project_team/project_path')
 
 
Using any other {{ic|http://}}, {{ic|https://}} or {{ic|ssh://}} URL (including {{ic|lp:project_name}}) will prevent makepkg from updating the local repo.
 
 
The correct URL can be obtained with:
 
$ bzr config parent_location
 

Revision as of 07:03, 15 May 2013

Template:Package Guidelines

Version control systems can be used for retrieval of source code for both usual statically versioned packages and latest (trunk) version of a development branch. This article covers both cases.

Prototypes

The ABS package provides prototypes for cvs, svn, git, mercurial, and darcs PKGBUILDs. When abs is installed, you can find them in /usr/share/pacman. Latest versions can be found in the prototypes directory in the ABS Git repository.

Guidelines

  • Suffix pkgname with -cvs, -svn, -hg, -darcs, -bzr, -git etc. unless the package fetches a specific release.
  • If the resulting package is different after changing the dependencies, URL, sources, etc. increasing the pkgrel is mandatory. Touching the pkgver isn't.
  • Include what the package conflicts with and provides (e.g. for fluxbox-gitAUR: conflicts=('fluxbox') and provides=('fluxbox')).
  • replaces=() generally causes unnecessary problems and should be avoided.
  • When using the cvsroot, use anonymous:@ rather than anonymous@ to avoid having to enter a blank password or anonymous:password@, if one is required.
  • Include the appropriate VCS tool in makedepends=() (cvs, subversion, git, ...).

VCS sources

Note: Pacman 4.1 supports the following VCS sources: bzr, git, hg and svn. See the fragment section of man PKGBUILD or PKGBUILD(5) for a list of supported VCS.

Starting with pacman 4.1, the VCS sources should be specified in the source=() array and will be treated like any other source. makepkg will clone/checkout/branch the repo into $SRCDEST (same as $startdir if not set in makepkg.conf(5)) and copy it to $srcdir (in a specific way to each VCS). The local repo is left untouched, thus invalidating the need for a -build directory.

The general format of a VCS source=() array is:

source=('[folder::][vcs+]url[#fragment]')
  • folder (optional) is used to change the default repo name to something more relevant (e.g. than trunk) or to preserve the previous sources
  • vcs+ is needed for URLs that do not reflect the VCS type, e.g. git+http://some_repo.
  • url is the URL to the distant or local repo
  • #fragment (optional) is needed to pull a specific branch or commit

An example Git source array:

source=('project_name::git+http://project_url#branch=project_branch')

The pkgver() function

The pkgver autobump is now achieved via a dedicated pkgver() function. This allows for better control over the pkgver, and maintainers should favor a pkgver that makes sense. Following are some examples showing the intended output:

Git

Using the tag of the last commit:

pkgver() {
  cd local_repo
  git describe --always | sed 's|-|.|g'
}
2.0.6.a17a017

If there are no annotated tags:

pkgver() {
  cd local_repo
  echo $(git rev-list --count HEAD).$(git rev-parse --short HEAD)
}
1142.a17a017

Subversion

pkgver() {
  cd local_repo
  svnversion | tr -d [A-z]
}
8546

Mercurial

pkgver() {
  cd local_repo
  echo $(hg identify -n).$(hg identify -i)
}
2813.75881cc5391e

Bazaar

pkgver() {
  cd local_repo
  bzr revno
}
830

Fallback

The current date can be used, in case no satisfactory pkgver can be extracted from the repo:

pkgver() {
  date +%Y%m%d
}
20130408

Tips

A sample Git PKGBUILD

# Maintainer: Dave Reisner <d@falconindy.com> 
# Contributor: William Giokas (KaiSforza) <1007380@gmail.com>

pkgname=expac-git
_gitname=expac
pkgver=0.0.0
pkgrel=1
pkgdesc="Pacman database extraction utility"
arch=('i686' 'x86_64')
url="https://github.com/falconindy/expac"
license=('MIT')
depends=('pacman')
makedepends=('git' 'perl')
conflicts=('expac')
provides=('expac')
# The git repo is detected by the 'git:' or 'git+' beginning. The branch
# 'pacman41' is then checked out upon cloning, expediating versioning:
#source=('git+https://github.com/falconindy/expac.git'
source=('git://github.com/falconindy/expac.git'
        'expac_icon.png')
# Because the sources are not static, skip Git checksum:
md5sums=('SKIP'
         '020c36e38466b68cbc7b3f93e2044b49')

pkgver() {
  cd $_gitname
  # Use the tag of the last commit
  git describe --always | sed 's|-|.|g'
}

build() {
  cd $_gitname
  make
}

package() {
  cd $_gitname
  make PREFIX=/usr DESTDIR="$pkgdir" install
  install -Dm644 "$srcdir/expac_icon.png" "$pkgdir/usr/share/pixmaps/expac.png"
}