NAME

pkgwrite - Make RedHat and Debian packages from the same source.


SYNOPSIS

 pkgwrite  (--tarball=TARBALL | --srcdir=SRCDIR) \
          [--pkgwriteinfo-file=pkgwriteinfo] \
          --arch=ARCH \
          --format={redhat,debian}
          [options]
 pkgwrite --query-list=LISTNAME


DESCRIPTION

pkgwrite takes a standard automake package, either from a source directory or from a distributed tarball, and a pkgwrite input file and makes either RedHat or Debian packages.

The actual package source code must be specified either by directory (using --srcdir) or from a tarball created with `make dist' (using --tarball).

Additional packaging information is taken from pkgwriteinfo. If --pkgwriteinfo-file is omitted, pkgwriteinfo from the source directory or tarball is taken instead. (after configure is run, so you might generally use a pkgwriteinfo.in).

There are a few command-line parameters which affect the package-making:

--no-strict-changelog
Don't force the user's changelog and pkgwriteinfo file to have the same version. (If the packaging system requires that the changelog's latest entry be equal to the package's version, then pkgwrite will generate a changelog entry. This happens under Debian.)

--no-cleanup
Don't remove the temporary directory (which will be /tmp/mkpkg-###-$USER). Useful for debugging.

--debian-dist=DIST
Generate packaging for the given debian distribution: this mostly affects the changelog so setting DIST to stable or unstable is recommended.

--skip-sanity-check
Disable the usual checks that the package is valid. The package may still partially work, even if a sanity-check would normally fail.


TERMINOLOGY

package
A family of packages for various distributions which all come from one tarball and one pkgwriteinfo file.

build
A compilation of the source code into binaries. Some packages require multiple builds, for example, to make debugging and nondebugging versions of a libraries. Generally you just use the {MAIN} build.

target
A single set of installed files in a package. Simple packages only have a single target {MAIN} because the package is an all-or-nothing proposition.

Some packages contain many parts, not all applicable to all users. These packages should be broken in to different targets.

For example, a client/server based application might be conveniently packaged foo-server, foo-client-curses, foo-client-gtk. That way, users without X can use the curses version without installing gtk+, often the clients and servers are run exclusively on different machines, so installing both is a waste of disk space.

Another important note is that if you derive from a Build other than {MAIN}, then your target's name will include the build name.

If it you use Target: {MAIN}, the resulting system package will be named: PACKAGE-BUILD Otherwise, for Target: *, you'll get: PACKAGE-BUILD-*


MAINTAINING CHANGELOGS

We recommend that you maintain a changelog in debian format, here is an example:


 gdam (0.934-1) unstable; urgency=low
   * many bug fixes
   * split into many packages
  -- David Benson <daveb@ffem.org>  Wed, 17 Jan 2000 13:09:36 -0800

(No spaces for each version banner; 2 spaces on each bullet; 1 space before the packager byline.)

If you don't maintain a changelog, we will generate a changelog with just this version of the package in it.

You should specify the changelog using the Changelog: directive.


EXAMPLES

Here are a few examples of common types of packages. The pkgwrite distribution includes these packages inside the examples/tiny directory.

EXAMPLE: SINGLE-TARGET PACKAGE

The most common type of package has one set of files it installs or uninstalls: there are no packaged bits or pieces. (A Target in pkgwrite terminology is the installed set of files.)

Here is the pkgwrite file from the single-target example included with the pkgwrite distribution:

  Package: aa
  Section: text
  Group: Applications/Text
  Priority: low
  Home-Page: NONE
  Source-Url: NONE
  Author: David Benson <daveb@ffem.org>
  Version: 0.0.1
  Release: 1
  Synopsis: test package aa
  Packager: daveb
  Packager-Email: daveb@ffem.org
  License: NONE
  Description: test package (aa).
  Build: {MAIN}
  Target: {MAIN}
  Files: /usr/bin/dummy-*
  Synopsis: test a (single-target package)

This package's name is aa; this file will produce a binary RPM named aa-0.0-1.$ARCH.rpm.

EXAMPLE: MULTI-TARGET PACKAGE

A multi-target, single-build package is a package that need only be compiled once, but which must be separated into several system packages, because the targets appeal to different users or have different dependencies.

Here is the pkgwriteinfo file from the example multi-target single-build package:

  Package: bb
  Section: text
  Group: Applications/Text
  Priority: low
  Home-Page: NONE
  Source-Url: NONE
  Author: David Benson <daveb@ffem.org>
  Version: 0.0
  Release: 1
  Synopsis: test package bb
  Packager: daveb
  Packager-Email: daveb@ffem.org
  License: NONE
  Description: test package (bb).
  Build: {MAIN}
  Target: a
  Files: /usr/bin/bb-a
  Synopsis: part a of package bb
  Description: whatever (bb-a)
  Target: b
  Files: /usr/bin/bb-b
  Synopsis: part b of package bb
  Description: whatever (bb-b)

In this package, only a single default Build: is required. Some packages may require the Configure-Flags or Configure-Envars fields in order to compile correctly.

By default, all the targets use the {MAIN} Build.

Then each package contains a default file list, a description and a synopsis.

EXAMPLE: MULTI-BUILD PACKAGE

The most complex type of package must be built multiple times, with different configure or make flags. Each target must then refer to the build from which it was produced, using the Which-Build field (the default is {MAIN}).

Here is the example of such a package from the pkgwrite distribution:

  Package: cc
  Section: text
  Group: Applications/Text
  Priority: low
  Home-Page: NONE
  Source-Url: NONE
  Author: David Benson <daveb@ffem.org>
  Version: 0.0
  Release: 1
  Synopsis: test package cc
  Packager: daveb
  Packager-Email: daveb@ffem.org
  License: NONE
  Description: test package (cc).
  Build: nond
  Configure-Flags: --program-suffix=-nondebug
  Build: d
  Configure-Flags: --program-suffix=-debug
  Target: nondebug
  Which-Build: nond
  Files: /usr/bin/test-nondebug
  Synopsis: nondebug package cc
  Description: whatever (cc-nondebug)
  Target: debug
  Which-Build: d
  Files: /usr/bin/test-debug
  Synopsis: debug package cc
  Description: whatever (cc-debug)

Each Build section corresponds to a complete configure, build, install phase. In this package, the nond build just wants configure to be run configure --program-suffix=-nondebug ... whereas for the d build, configure --program-suffix=-debug ... (Note that the ... will be somewhat different from distribution to distribution)

Also, it is often convenient to use the same names for the builds and the targets. We would rename nond as nondebug and d as debug if this were a real package -- we did this to discuss it more conveniently.

It is perfectly possible to have more than one Target pointing to the same Build, just as multi-target single-build packages do. But the opposite is not allowed: a Target must specify exactly one Build.


HARDCODED VALUES

Many lists and values are hardcoded into pkgwrite. You may query these lists through the --query-list flag. Here are the lists you may obtain in this manner:

deb-sections
Known allowed Section: fields for debian packages.

rpm-groups
Known allowed Group: fields for redhat packages.

deb-priority
Known allowed Priority: fields for debian packages.

For example to get a list of allowed values for the Section: field, use pkgwrite --query-list=deb-sections.


PKGWRITE'S pkgwriteinfo FORMAT

This (long) section describes the file that describes the targets to build from a tarball. This description file is called a pkgwriteinfo file.

The pkgwriteinfo file consists of one package description part, then a number of Build sections, then a number of Target sections.

PER-PACKAGE INFO

The package file should begin with a section that describes the overall source code of the package:

   Package: gdam
   Section: sound
   Group: Multimedia/Sound
   Priority: optional
   Home-Page: http://ffem.org/gdam
   Source-Url: http://ffem.org/gdam/downloads/gdam-0.0.930.tar.gz
   Version: 0.0.930
   Release: 1
   Author: David Benson <daveb@ffem.org>

Here is a description of each allowed field:

Package
Name of the source package.

Version
The version number given to this version of the package by its maintainer.

Release
Increment this each time a new package is released without a corresponding upstream version-number change.

Section
The debian section this package belongs in.

Group
The redhat group this package belongs in.

Priority
Priority of this package (debian-style).

Home-Page
A URL giving the home page for this package or project.

Source-Url
A URL describing how to download this package.

Author
An author of this package, with email optional.

Synopsis
Under one line summary of this target.

Description
Multiple-line description of this target.

Packager
Full name of the person who made this packaging.

Packager-Email
Email address at which to reach the packager.

Changelog
Specify the location of a Debian format changelog to include with the package (it will be converted to another standard format, if needed)

PER-TARGET INFO

For each output binary package there must be a ``target'' section:

  Target: xmms-plugins
  Depends: gdam-clients-gtk, gdam-server, xmms
  Synopsis: GDAM XMMS plugin support
  Description: use XMMS visualization plugins with GDAM.
  Files: /usr/bin/gdamxmmsvishelper
Target
Name of this target. The name of the package that results will be prepended with SOURCE-; in this example the package's name is gdam-xmms-plugins.

Platform-Independent
Set this to yes if this package will be installable on any architecture (it contains no system-specific or compiled code).

Set this to no for packages containing compiled, architecture-specific binaries.

Depends
Debian-formatted dependency lists for this package.

Redhat-Requires
Specify the redhat packages that this one depends on.

Synopsis
Under one line summary of this target.

Man-Page
The basename of a man page, for example pkgwrite.1. It will automatically be installed into the correct section directory based on its extension.

Doc
Miscellaneous documentation. Each path is assumed to be inside the installed area.

It will be always be copied into the distribution's documentation area, and it will be gzip'd if that is needed. Also, whole directories will be recursively copied, if the entry ends with a /, for example,

   Doc: /usr/share/doc/gdam/example-configs/

Source-Doc
Miscellaneous documentation that is not normally installed by this package's makefile:

These must be files directly from the distributed tarball. They will be always be copied into the distribution's documentation area and will be gzip'd if that is needed. Whole directories will be recursively copied, if the entry ends with a /.

Description
Multiple-line description of this target.

Which-Build
Name of the build whose files should be used. (Defaults to {MAIN}).

Files
A wildcard matching ordinary files to be distributed with this target.

PER-BUILD INFO

Build
The name of this build. The default build should be named {MAIN}.

Configure-Flags
Options to be passed to the configure script.

Configure-Envars
Space-separated environment variables to add when configuring.

Make-Flags
Extra parameters to the make program during both the build and the install phase.

Build-Flags
Extra parameters to the make program during just the build phase.

Install-Flags
Extra parameters to the make program during just the install phase.


AUTHOR

Written by Dave Benson <daveb@ffem.org>.