Files in a Wigwam Package

Each of these files begins with $PACKAGE-$VERSION.; here we just list the extensions:

archs

List of GNU-style architecture and package-architecture pairs. This lets a package specify exactly which architectures are supported without the package having to know about every GNU type.

For now, you may set WIGWAM_ARCHS_SUPPORTED to a list of package-architectures allowed; this way you can just say WIGWAM_ARCHS_SUPPORTED="i386" and use the standard intel versions; for example:
                  i686-pc-gnu-linux i386
                  i586-pc-gnu-linux i386
                  i486-pc-gnu-linux i386
                  i386-pc-gnu-linux i386

archfiles.$ARCH

List of architecture-dependent files. The $ARCH must correspond to the the right-hand column of the archs file. This lets a package specify exactly which architectures are supported without the package having to know about every GNU type.

For now, you may set WIGWAM_ARCHS_SUPPORTED to a list of package-architectures allowed; this way you can just say WIGWAM_ARCHS_SUPPORTED="i386" and use the standard intel versions.

files

List of files for this package that must be retrieved from the package archive. It should list every file in the source package archive for this package including itself.

This file is mandatory.

type

What type of package this is. This may be make, service, or raw.

options

Options specific to this package's build process, see the Section called Configuring the Build and Install Process.

md5sums

List of md5sums for each file listed in the .files list. This is used to verify that the package is downloaded from the package archive correctly.

This file is mandatory.

prepatch, postpatch

This are small scripts that will be run before and after the patches to the package's source are applied. They are rarely used: generally they are used when a file's permission needs changing, or when a file created by a patch needs non-default permissions.

tar.gz

the source code from the upstream maintainer, or from make dist from your CVS repository.

Though .tar.gz is probably the most common archive format, many others are supported.

Note that there is no required naming convention for upstream sources: you should use the exact name of the file as it is downloaded, unless its filename conflicts with a different file from another package. By common convention, the upstream sources are usually named PACKAGE-UPSTREAM_VERSION.tar.gz.

patch

Patches that should be applied to the upstream source code.

Patch files contain changes generated with the diff -u program. The build system automatically tries to guess the flags needed to patch the source code.

Any files ending in .patch.bz2, .patch.gz, and .patch are applied.

The packaging system tries to guess the right patch flags, but if it gets it wrong, you may need to use patch_flags_PATCH_FILE_CANONICALIZED where PATCH_FILE_CANONICALIZED is the patch's base filename with . converted to _ and - converted to _

predep, dep

Wigwam packages this package depends upon at various points in its lifetime. See the Section called Dependencies.

servicedep, filedep, packagedep

Files or packages that a service provided by a package depends upon. See the Section called Dependencies.

conflict

This is a list of packages which may not be installed concurrently with this package. Two packages conflict if either lists the other in its conflict file; there is no difference between A conflicts with B and B conflicts with A.

This file may list specific version numbers, using a SPACE character to separate the package name from the version number, or it may omit the version number to conflict with any version of that package.

provides

This is a list of packages which this package clones. These should act as reasonable substitutes for the packages they provide.

Each line of this file must start with a package name. After a single space character, there may also be a version number. If no version number is specified, the package can act as any version of the package it provides.

dirs

list of directories that must be available for this package to be installed.

installed_files

List of files that this package affects. This file may be automatically computed from your pacakge with the make-installed-files-list script in any package archive.

Each line in this file consists of an action, a space, and a filename. The action may be any of the following characters and should describe what happened to the file.

>

The file was created by installing this package.

<

The file was removed by installing this package.

~

The file was changed by installing this package.

Dependencies

In general, packages need other packages to operate correctly. The most common type is install dependence, where one package demands that another is installed before it can be installed.

Dependencies can describe which versions of a package are required too. We support intervals. If you use brackets, for example, [0.21,0.95], then the version numbers at the ends of the range are allowed. If you use parentheses, then the ends of the range are not valid for satisfying the dependence. You may also specify an exact version number.

Finally you may have a sequence of allowed ranges separated by semicolon (;). If any range matches, then the version is allowed.

Here are some examples:

Each dependency type has its own file in the package:

For services there are additional kinds of dependencies:

servicedep

For each service, a list of other services that must be running before it can be started. The package should also specify the packages which provide these services in its .dep file.

servicedep will ignore failed dependencies. Its only function is to sort the services when servicectl start or servicectl stop is specified.

When the service is installed, this file gets copied to ext/services/SERVICE-VERSION/servicedep. It can be overridden by a project file services/SERVICE-VERSION/servicedep.

filedep

Many files affect the way a service runs, but often changing those files has no effect until the service is restarted.

The .filedep file contains a list of files which, if changed, will cause the service to be restarted when publishing. Paths are relative to $PLAYPEN_ROOT; shell-type wildcarding is allowed.

When the service is installed, this file gets copied to ext/services/SERVICE-VERSION/filedep. It can be overridden by a project file services/SERVICE-VERSION/filedep or supplemented by services/SERVICE-VERSION/filedep.additional. In both of these files, -VERSION may be omitted.

packagedep

Some services must be restarted after other packages are upgraded; in some cases they cannot have packages on which they depend gone for even a second, in others they will continue using the old package until they are restarted.

The .packagedep file contains a list of packages (without version numbers) which, if changed, will cause the service to be restarted when publishing.

When the service is installed, this file gets copied to ext/services/SERVICE-VERSION/packagedep. It can be overridden by a project file services/SERVICE-VERSION/packagedep or supplemented by services/SERVICE-VERSION/packagedep.additional. In both of these files, -VERSION may be omitted.

Configuring the Build and Install Process

Many package-types allow certain variables to be set in $PACKAGE-$VERSION.options. This file is sourced from a shell. The following variables are recognized by GNU and Perl style packages:

All the standard build types uncompress any tarball present in the .files list into the package's build directory, $PLAYPEN_ROOT/ext/build/$PACKAGE-$VERSION/. For make-style packages, these tarballs should contain the source code from the original ("upstream") authors. For raw- and service-style packages, these tarballs are optional, and may contain support files, usually from the author of the package.

If a package's source files need modifications, for example, for portability or to make them better adapted to wigwam, you may include patches in the package. These should be normal patches, produced with diff -u. They will be automatically found and applied if they end with .patch, .patch.bz2 or .patch.gz.

Sometimes patching sources is not enough to fix them so they build. For example, sometimes a file's permission needs to be changed. To do that, one can put code in the .prepatch file:
     chmod +x configure-helper-script
     chmod +w some-random-file

Makefile-style packages recognized the additional variables:

The following extra configuration options are understood by raw or service packages:

The following extra files are automatically recognized by raw and service style packages:

build

Contains a script to build the binaries and data from the upstream tarball and patches, etc. in ext/build/$package-$version.

install

Contains a script to install the binaries and data from the built package in ext/build/$package-$version to their installed locations in ext.

Service packages also install the file $package-$version.config into ext/services/$service-$version/config and optionally $package-$version.servicedep into ext/services/$service-$version/deps.

Please see
the Section called Writing Custom Build and Install Scripts for more information.

Writing Custom Build and Install Scripts

Writing custom build and install scripts is necessary for most packages that don't use make, and it is the standard practice for service-style packages.

Sometimes minor customizations are all that is needed; you may use a make-style package, but set scripts in various environment variables: $pre_build_script, $post_build_script, $pre_install_script, $post_install_script. All the same rules apply to those scripts.

The following environment variables are set by the packaging system before running custom build and install scripts:

Of course, you may assume $PLAYPEN_ROOT is available too.

Making Non-Relocatable Packages

Most packages are relocatable: this means that once they are installed, you may merely move the $PLAYPEN_ROOT and update that environment version and the package will continue to function. Wigwam-base is an example of a relocatable package.

If a package isn't relocatable, it is a problem for publication, where we generally want to build everything in a temporary $PLAYPEN_ROOT then relocate that as late and fast as possible.

In order to solve that, we need a mechanism for adding hooks when a package is relocated; the external interface to this is:
     packagectl new-playpen-root OLD-PLAYPEN-ROOT

Nonrelocatable packages need special treatment in the .options file. The following variables apply to all package styles:

The various scripts may rely on the following shell variables:

As usual, the environment variables EXT_PACKAGE, EXT_VERSION, EXT_PKGBUILDDIR, EXT_DIR, and PLAYPEN_ROOT are set.

Writing Package Documentation

All packages should have documentation, eventually.

That documentation can be in one of two forms: