Chakra Packaging Standards

From Chakra | Wiki
(Redirected from Packaging Standards)
Jump to: navigation, search
Utilities-file-archiver.pngChakra Packaging Standards
These packaging standards should be always followed when packaging for Chakra, either for the official repositories or for the Chakra Community Repository.

Editing PKGBUILDs

  • Always use standard indentation of four (4) spaces per tab. Tip: Use Kate and its builtin filelist plugin.
  • If a PKGBUILD requires special stuff (workarounds, sed lines), always document that with comments.
  • If you include a workaround, mark it with WORKAROUND in a comment, so we can grep it when someone has a fixing-spree or so
  • If you think something needs to be fixed, mark it with FIXME in a comment, so we can grep it when someone has a fixing-spree or so
  • Don't modify the PKGBUILD layout because you think it's better for you or improves "editability". PKGBUILDs should be rather readable and understandable than "easy to edit" for us packagers

Committing PKGBUILDs

  • Never commit something that does not work
  • Test your changes before committing
  • Double-check what you commit before committing
  • Always write a proper description for your commits, just describe what you have done (no novels needed, just a useful description)...
  • Commit messages should be of the form $pkgname: $message, e.g. nano: Upgrade from 2.4.2 to 2.4.3
  • If you make big changes, announce them to the other packagers in IRC or on the packager mailing list - preferably before committing

Uploading Packages

  • Always test the packages and the database before uploading

Modifying the buildsystem

  • Always talk to the repository owner (listed on git.chakraos.org) before committing any changes to the _buildsystem directory. This especially concerns the makepkg script. If you need to edit the skel files for the builder to include a new KDE module or the like, just do it, those are trivial changes.

General Standards

When building packages or build packages for Chakra, you should adhere to the package standards below, especially if you would like to contribute your new package or source package to Chakra.

PKGBUILD Body Prototype

File: PKGBUILD
pkgname=NAME
pkgver=VERSION
pkgrel=1
pkgdesc=""
arch=('i686' 'x86_64')
url="http://ADDRESS/"
screenshot="http://address"
license=('GPL')
groups=()
depends=()
makedepends=()
optdepends=()
provides=()
conflicts=()
replaces=()
backup=()
options=()
hooks=()
install=
changelog=
source=($pkgname-$pkgver.tar.gz)
noextract=()
md5sums=() #generate with 'makepkg -g'

build() {
  cd $srcdir/$pkgname-$pkgver
  ./configure --prefix=/usr
  make
}

package() {
  cd $srcdir/$pkgname-$pkgver
  make DESTDIR=$pkgdir install
}

Between the body and the header there should be one line of separation, uncommented. The header content will depend on the place where the PKGBUILD will be used: official repositories or CCR.

When a variable is not needed, remove its line from the PKGBUILD (provides, replaces, etc.). It is common practice to preserve the order of the PKGBUILD fields as shown above. Also, try to keep the line length in the PKGBUILD below ~100 characters.

Package Name

Package names should consist of alphanumeric characters only; all letters should be lowercase.

Development versions (alphas, betas, etc.) should be named like $pkgname-dev, and treated like an alternate version of the stable package.

Package Version

Package versions should be the same as the version released by the author. Versions can include letters if need be. Version tags may not include hyphens! Letters, numbers, and periods only.

When original version number includes an hyphen, it's a common practice to replace it with an underscore. Example: 1.0-beta3 becomes 1.0_beta3.

Package Release

Package releases are specific to Chakra packages. These allow users to differentiate between newer and older package builds. When a new package version is first released, the release count starts at 1. Then as fixes and optimizations are made, the package will be re-released to the public and the release number will increment. When a new version comes out, the release count resets to 1. Package release tags follow the same naming restrictions as version tags.

Package Description

When writing a description for a package, do not include the package name in a self-referencing way. For example, "Nedit is a text editor for X11" could be simplified to "Text editor for X11". Also try to keep the descriptions to ~80 characters or less.

Architectures

The arch array should contain 'i686' and/or 'x86_64' depending on which architectures it can be built on. You can also use 'any' for architecture independent packages.

Licenses

The license should be always used. You can use it as follows:

  • If the license is already in /usr/share/licenses/common, you can refer to it using it's directory name.
    Example: license=('GPL3')
  • If the appropriate license is not included in the official licenses package, several things must be done:
    • The license file(s) should be included in /usr/share/licenses/$pkgname/.
    • If the source archive does not contain the license details and the license is only displayed on a website for example, then you need to copy the license to a file and include it. Remember to call it something appropriate too.
    • Add 'custom' to the licenses array. Optionally, you can replace 'custom' with 'custom:<name of license>'.
    • Once a license is used in two or more packages in an official repository, it becomes common.
    • The MIT, BSD, zlib/libpng and Python licenses are special cases and cannot be included in the 'common' licenses pkg. For the sake of the license variable, it's treated like a common license (license=('BSD'), license=('MIT'), license=('ZLIB') or license=('Python')) but for the sake of the file-system, it's a custom license, because each one has its own copyright line. Each MIT, BSD, zlib/libpng or Python licensed package should have its unique license stored in /usr/share/licenses/$pkgname/.
    • Some packages may not be covered by a single license. In these cases multiple entries may be made in the license array e.g. license=("GPL" "custom:some commercial license"). For the majority of packages these licenses apply in different cases, as opposed to applying at the same time.
    • The (L)GPL has many versions and permutations of those versions. For (L)GPL software, the convention is:
      • (L)GPL - (L)GPLv2 or any later version
      • (L)GPL2 - (L)GPL2 only
      • (L)GPL3 - (L)GPL3 or any later version

It's preferred to set license to the exact version when it applies. For example, you should better set the license to GPL2 instead of just GPL. This is because just writing GPL as license can be understood as "Not sure which version of the license".

Dependencies

Dependencies are the most common packaging error. Verify dependencies by looking at source documentation and the program website.

Optional Dependencies

Any optional dependencies that aren't needed to run the package or have it generally function shouldn't be included; instead the information should be added to the optdepends array like this:

optdepends=('package: functionality it provides'
            'package2: functionality it provides')

The optdepends information will automatically be printed out on installation/upgrade from Pacman.

Alternate Versions of Packages

If you just provide an alternate version of an already existing package, use conflicts array to reference to the original package, and any other alternate packages. Use also provides=<original package name> if that package is required by others.

Renaming packages

If you want to rename your package, change the name in the PKGBUILD and define the old one in the replaces array.

Important messages

All important messages should be echoed during install using an .install file. For example, if a package needs extra setup to work, directions should be included.

New Variables

In general, no new variables should be introduced in the PKGBUILD file. Nevertheless, there are some accepted variables which might be used in certain cases:

$_pkgname
When the $pkgname value is not the real name of the package (used i.e. in the source URLs), this alternative variable can be added right after the $pkgname and set to the real name. Example:
pkgname=rekonq-git
_pkgname=rekonq
$_pkgver
When the $pkgver value is different from the one used in source URLs or paths, this alternative variable can be added right after the $pkgver. Example:
pkgver=1.0_rc2
_pkgver=1.0-rc2

Any other new variable, which should be added only if absolutely required to build the package, has to be prefixed with an underscore (_). Example: _customvariable=.

Moving Files

When moving files from the $srcdir to the $pkgdir, the preferred way is to do it by using the install command. It's really easy to use, just have a look at any PKGBUILD using it and also run this:

install --help

Building Packages Without Compilation

With certain software there's no compilation process, just a packaging process (downloaded files are just moved to the right path). In those cases, build() function should be deleted, and all the process should be defined inside the package() function.

Directories

Configuration files should be placed in the /etc directory. If there's more than one configuration file, it's customary to use a subdirectory in order to keep the /etc area as clean as possible. Use /etc/$pkgname/, where $pkgname is the name of your package (or a suitable alternative, e.g., apache uses /etc/httpd/).

Package files should follow these general directory guidelines:

/etc
System-essential configuration files.
/etc/$pkgname
Configuration files for $pkgname.
/usr/bin
Application binaries.
/usr/include
Header files.
/usr/lib
Libraries.
/usr/lib/$pkgname
Modules, plug-ins, etc.
/usr/sbin
System binaries.
/usr/share/doc/$pkgname
Application documentation.
/usr/share/info
GNU Info system files.
/usr/share/man
Manpages.
/usr/share/$pkgname
Application data.
/var/lib/$pkgname
Persistent application storage.
/opt/$pkgname
Large self-contained packages such as Java, etc.

Package should not contain following directories:

/dev
/home
/srv
/media
/mnt
/proc
/root
/selinux
/sys
/tmp
/var/tmp

Repository-specific Standards

Chakra Official Repositories

Chakra Official Repositories PKGBUILD Header

The PKGBUILD should have the following header:


File: PKGBUILD
# Maintainer: <Maintainer contact information>

# Only for DESKTOP:
# include global config
source ../_buildscripts/${current_repo}-${_arch}-cfg.conf
<Repo>
This should be replaced according to the repository: core, desktop, gtk.
<Maintainer contact information>
Maintainer contact information should include a name, an alias and an e-mail address, e.g.:
Complete Name (alias) <name@example.org>

If there are several maintainers, there is to be one maintainer line per maintainer, and the difference between them should be explained this way:

# Maintainer (difference): Complete Name <name@example.org>

As an example:

# Maintainer (i686): Complete Name <name@example.org>
# Maintainer (x86_64): Complete Name <name@example.org>

Right after the maintainer line(s), there is to be a list of previous contributors.

Chakra Community Repository

Packages Already in the Official Repositories

The submitted source packages must not build applications already in any of the official repositories under any circumstances. New features or patches for packages already in the Chakra repositories must be sent to the packagers.

Only if those are rejected by the Chakra, a package with them could be uploaded to the CCR. It has to have a different name reflecting the difference to the one in the repositories, like kernel-libre for an alternative to kernel with no privative components. Additionally the provides=('kernel') PKGBUILD array must be used in order to avoid conflicts with the official package.

The Chakra packages allow an URL to an screenshot of the package, this image should be creative-commons or any other general-use license. This field is optional.

Chakra Community Repository PKGBUILD Header

The PKGBUILD should have the following header:


File: PKGBUILD
# Maintainer: <Maintainer contact information>
<Maintainer contact information>
Maintainer contact information should include a name, an alias and an e-mail address, e.g.:
Complete Name (alias) <name@example.org>

If there are several maintainers, there is to be one maintainer line per maintainer, and the difference between them should be explained this way:

# Maintainer (difference): Complete Name <name@example.org>

As an example:

# Maintainer (i686): Complete Name <name@example.org>
# Maintainer (x86_64): Complete Name <name@example.org>

Previous contributors should be referenced right after maintainers lines, and their contributions should be logged in a $pkgname.changelog file whenever possible, linked from the PKGBUILD with the changelog=$pkgname.changelog line. Here you have a ChangeLog prototype:


File: /usr/share/pacman/ChangeLog.proto
2017-05-24 Complete Name <account@doma.in>

	* pkgver-pkgrel :
	new upstream release.
	Reason we changed stuff.
	Another reason we changed stuff.

	* gcc-4.1.patch :
	Removed, no longer needed.

2010-05-17 Complete Name <account[at]doma[dot]in>

	* 1.0-5 :
	added ChangeLog.
	the last line should end with just one newline.
	you can cat the file to check it displays fine.

Remember to leave an empty line at the end of the changelog. Also, remember to use the UTC time, not the one in your local timezone.

Groups

The groups array in the PKGBUILD should not be used by CCR build packages.

Binary files

Source packages uploaded to the CCR may not contain binary files, images included. They should be downloaded through the PKGBUILD file instead.

Software-specific Standards

CMake PKGBUILDs

When using CMake, DCMAKE_BUILD_TYPE=RelWithDebInfo option should be added. This way debug information is included, so Chakra users can properly report bugs to help upstream developers to fix them.

This is an example of the build() and package() funtions for CMake-based PKGBUILDs:

build() {
  cd $srcdir/$pkgname-$pkgver
  [[ -d build ]] && rm -r build
  mkdir build && cd build
  cmake \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    ..
  make
}
 
package() {
  cd $srcdir/$pkgname-$pkgver/build
  make DESTDIR=$pkgdir install
}

SVN PKGBUILDs

When making a PKGBUILD for a SVN version of a package:

  • Suffix pkgname with -svn.
  • When makepkg is run, by default it will check for newer revisions and then update the pkgver in the PKGBUILD. Use the parameter --holdver when calling makepkg if you want otherwise. Run man makepkg for additional documentation.
  • Check for package conflicts. For example fluxbox-svn will conflict with fluxbox. In this case, you need to use conflicts=('fluxbox').
  • Use the provides field if there are packages that require the non-SVN package, so those can be installed too (provides=('fluxbox')).
  • You should avoid using replaces=... as it generally causes unnecessary problems.
  • When using/defining the svnroot, use anonymous:@ rather than anonymous@ to avoid a password prompt and having to enter a blank password OR use anonymous:password@ if a password is required.
  • Though it is often unnecessary to use the pkgrel field when building SVN packages (changes to the package are usually often and will be reflected in the pkgver), makepkg will require it.
  • Don't forget to include subversion in makedepends=....
  • To preserve the integrity of the checked-out code consider copying the original build directory if you have to make edits. For example, you can use:
  cp -r $srcdir/$_svnmod src/$_svnmod-build
  cd $srcdir/$_svnmod-build

This is an example of a SVN PKGBUILD (without header):

pkgname=zaz-svn
_pkgname=zaz
pkgver=154
pkgrel=1
pkgdesc="Puzzle game where the player has to arrange balls in triplets."
arch=('i686' 'x86_64')
url="http://sourceforge.net/projects/zaz/"
license=('GPL3' 'CCPL:by-sa')
depends=('ftgl' 'sdl' 'sdl_image' 'libvorbis' 'libtheora')
conflicts=('zaz')
changelog=ChangeLog
 
_svntrunk="https://$_pkgname.svn.sourceforge.net/svnroot/$_pkgname/trunk"
_svnmod="$_pkgname"
 
build() {
  cd $srcdir

  if [ -d $_svnmod/.svn ]; then
    (cd $_svnmod && svn up -r $pkgver)
  else
    svn co $_svntrunk --config-dir ./ -r $pkgver $_svnmod
  fi

  msg "SVN checkout done or server timeout"
  msg "Starting make..."

  rm -rf $srcdir/$_svnmod-build
  cp -r $srcdir/$_svnmod $srcdir/$_svnmod-build
  cd $srcdir/$_svnmod-build

  ./configure \
    --prefix=/usr

  make
}

package() {
  cd $srcdir/$_svnmod-build
  make DESTDIR=$pkgdir install
}

Git PKGBUILDs

This is an example of a Git PKGBUILD (without header):

pkgname=knights-git
_pkgname=knights
pkgver=20110122
pkgrel=1
pkgdesc="Chess board with XBoard protocol support."
arch=('i686' 'x86_64')
url="http://kde-apps.org/content/show.php/Knights?content=122046"
license=('GPL2')
depends=('kdegames-common')
optdepends=('gnuchess: for playing against the computer.')
makedepends=('automoc4' 'cmake' 'docbook-xsl' 'git')
changelog=ChangeLog

_gitroot="git://anongit.kde.org/$_pkgname"
_gitname="$_pkgname"

build() {
  cd $srcdir

  msg "Connecting to GIT server...."

  if [ -d $_gitname ] ; then
    cd $_gitname && git pull origin
    msg "The local files are updated."
  else
    git clone $_gitroot $_gitname --depth=1
  fi

  msg "GIT checkout done or server timeout"
  msg "Starting make..."

  rm -rf $srcdir/$_gitname-build
  cp -R $srcdir/$_gitname $srcdir/$_gitname-build
  cd $srcdir/$_gitname-build

  cmake -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` \
        -DCMAKE_BUILD_TYPE=RelWithDebInfo \
        .
  make
}

package() {
  cd $srcdir/$_gitname-build

  make DESTDIR=$pkgdir install
}

See Also


Packaging rules