wiki:monza/pkgtools

Lintrack package tools

Fakebox comes with the following Lintrack package tools (pkgtools/ directory in the source code):

  • makepkg - builds package using description in ./PKGBUILD file
    • genmd5 - downloads all package source tarballs and outputs their MD5 sums in form suitable for PKGBUILD
  • pkg - Lintrack package manger (like apt-get), uses:
    • installpkg - installs package and updates package database (like dpkg -i)
    • upgradepkg - symbolic link on installpkg, upgrades packages
  • genpkglist - scans ./*.pkg.tar.gz and generates package.list and package.md5 files

Package description format

PKGBUILD file

Take a look at bridge-utils as an exemplary Lintrack package. The most important file of it is PKGBUILD. This is a Bash shell script which defines a few variables and a function called build().

PKGBUILD is interpreted (using Bash source command) by makepkg, which automatically downloads required sources, verifies them against MD5 sums, unpacks sources to src/, runs build() and finally packs pkg/ after build() is finished. There are two kinds of packages that makepkg builds: a stripped-down, normal version and a -big one, with all headers, static libraries, binaries with debugging symbols, and so on.

Following variables are necessary:

  • pkgname - contains a UNIX name of the package,
  • pkgver - version of the package, usually the same as the version of the software we're packaging,
  • pkgrel - package release number - an integer number starting with 1 and increased on each change to the package (that is, editing PKGBUILD, adding new patches, etc.),
  • implicit fixrel=1 - this will be explained later.

Note: you cannot use hyphens in any of the above variables, as they are used to create the final package name, which is: $pkgname-$pkgver-$pkgrel-$fixrel.pkg.tar.gz (or ...-big.pkg.tar.gz in case of a -big package).

Optional variables:

  • source - an array of URLs to download; tarballs will be extracted automatically in src/ subdirectory
    • md5sums - an array of MD5 sums of files referenced in source - required if source is present in order to verify the authenticity of downloaded files
  • smalldel - an array of relative (e.g. 'usr/share/gconv' - no slash at the beginning) paths not to include in the final, stripped-down packages,
  • perms - an array of strings in the following format, defining what permissions files in the package should have:
    • '<path> <mode> <user> <group>' - e.g. 'usr/bin/sudo 4755 root root':
      • <path> - relative path to file in package (as in smalldel),
      • <mode> - octal number representing the file permissions (see man chmod),
      • <user> - file owner,
      • <group> - file group owner.

The build() function does all that is needed to compile the software from src/ and install it in a virtual root directory of pkg/. A few tips for writing build()s:

  • make your PKGBUILDs easy to update - e.g. use $pkgver instead of hardcoding version strings everywhere,
  • the absolute path to package description directory is available under $startdir,
  • feel free to put any files in $startdir,
    • there are 2 special names of directories to create in $startdir: patches/ and files/ - they are used to easily apply patches and to install/overwrite custom files in pkg/, respectively; following special functions are available which do that:
      • patches [<source>=$startdir/patches] [<patch options>=-p1] - patches cwd with *.diff, *.diff.gz, *.diff.bz2 from patches/,
      • files [<source>=$startdir/files] [<destination>=$startdir/pkg] - copies files/ into pkg/
  • make install in Autoconf-powered build systems usually accepts DESTDIR

A very important rule to remember is to remove all unnecessary files from the final package, as Lintrack is usually installed on size-constrained CF cards and similar devices. makepkg will usually do most of the work for you, but please remember about removing:

  • headers (/usr/include),
  • static libraries (*.a, *.la),
  • debugging symbols,
  • i18n files,
  • manual and info pages, documentation,
  • unneeded files in /usr/share.

It's not about making 1MB package a 700KB package, but e.g. making 25MB a 2MB one. Feel free to leave everything in the -big packages, they are intended for development and debugging.

INSTALL file

INSTALL files are optional and let you write scripts to run on various events related to installing, upgrading and removing packages on the target system. Take a look at the kernel INSTALL file as an example. It updates boot/ so GRUB boots new kernel on package installation and upgrade.

The events are self-explanatory and are handled in the following functions:

  • pre_install()
  • post_install()
  • pre_upgrade()
  • post_upgrade()
  • pre_remove()
  • post_remove()

Remember:

  • each function has to return true (ie. exit code of 0) on success; otherwise e.g. package installation can be cancelled,
  • each of the above functions have to exist if you decide to include an INSTALL file, even with just '/bin/true' contents,
  • you always have to include the following code at the end of INSTALL files in order to let installpkg call individual functions contained in it:
    op=$1
    shift
    $op $*
    

Fixrels

A fixrel is a special, hot-fix release of a package. It contains only the files that have changed since last package release (usually the fixrel=1 version), plus a special script which is run after installing the updated files. Fixrels are installed incrementally, that is, in order to install a fixrel=3 version of a package, first the full fixrel=1 package is installed, than fixrel=2, and finally the fixrel=3.

When you call makepkg with -F <fixrel> (where fixrel > 1), it wil make a tarball of pkg/ and copy the fixrel script - FIX-$fixrel - to /.FIX in the package.

See also: ticket #160.

Package tarball format

Lintrack package is just a tarball (ie. tar.gz) of files to extract in / on the target system, plus following, additional files:

  • /.FILELIST - contains all the files in the package,
  • /.PKGINFO - holds package information in form of '<variable>="<value>"', e.g.:
    # Generated by makepkg 0.21 (Fakebox)
    # Sun Mar 16 20:29:43 CET 2008
    pkgname="syslibs"
    pkgver="3.0-2-1-big"
    builddate="Sun Mar 16 19:29:43 2008"
    packager="Lintrack (http://www.lintrack.org/)"
    size="26125345"
    arch="i686"
    
  • /.INSTALL - the INSTALL file from package description,

In a fixrel>1 package:

  • /.FIX - (optional) a shell script to be run after the upgrade.

Package manager - pkg

pkg is the Lintrack package manager. It can install, upgrade and remove packages, downloading necessary files from Internet if necessary. You can get usage information on pkg by running it with --help as the only argument.

pkg has a filesystem-based database in /var/pkg, where it store information on installed and available package versions. Information of a particular package is stored in /var/pkg/$pkgname directory, which may contain following files:

  • directly managed by pkg:
    • latest - latest available package version
    • repo - name of the repository that information on the latest available version has been fetched from,
  • managed by installpkg
    • installed - installed package version
    • PKGINFO - /.PKGINFO from package tarball
    • INSTALL - /.INSTALL from package tarball

pkg has a configuration file in /etc/pkg/repos.conf, which configures remote package repositories. Exemplary repos.conf:

#
# Format: "<name> <url>"
#

reponame http://somewhere.com/mypackages

Repositories

Repository is a directory containing *.pkg.tar.gz Lintrack package files and following two files:

  • package.list - index file, in the format of:
    # comment
    <pkgname> <pkgver> <pkgrel> <fixrel>
    
  • package.md5 - supporting file for package.list, in the format of:
    # comment
    <filename> <MD5 sum> <SHA1 sum> <file SIZE>
    
    Note: <filename> is the tarball filename, e.g. foobar-3.24-15-3.tar.gz

The package.list references only the latest version of one $pkgname, whereas package.md5 lists all the files available in the repository. Specifically, this is important for fixrels, e.g. if the latest fixrel=2, we still need to fetch the fixrel=1 version first and verify it.

Both files can be generated by running genpkglist in the directory with *.pkg.tar.gz files.

Last modified 11 years ago Last modified on 03/22/08 22:00:46