Each of these files begins with $PACKAGE-$VERSION.; here we just list the extensions:
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 |
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.
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.
What type of package this is. This may be make, service, or raw.
Options specific to this package's build process, see the Section called Configuring the Build and Install Process.
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.
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.
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.
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 _
Wigwam packages this package depends upon at various points in its lifetime. See the Section called Dependencies.
Files or packages that a service provided by a package depends upon. See the Section called Dependencies.
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.
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.
list of directories that must be available for this package to be installed.
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.
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:
Any version between A and B, including A and B, will satify the dependency.
Any version between A and B, including A but not B, will satify the dependency.
Any version between A and B, not including A not including B, will satify the dependency.
Any version between A and B, not including A or B, will satify the dependency.
Any version strictly greater than A will satify the dependency.
Any version greater or equal to A will satify the dependency.
Any version strictly less than B will satify the dependency.
Any version lesser or equal to B will satify the dependency.
Version B will satify the dependency.
Version A or version B will satify the dependency.
Each dependency type has its own file in the package:
Packages that must be installed before this package can be downloaded or unpacked. For example, if wigwam-base gets extended to support another compression type, then packages which ship using that compression will have to predepend on the appropriate version of wigwam-base.
This is implemented by downloading predep file first after the .files file. Then before proceeding, installing all the predep packages. If wigwam-base was upgraded, the install system reexecs itself to use the new version.
Packages that must be installed before this package can be built or installed.
This file consists of lines containing:
package_name package_version |
Use dep instead of predep wherever possible, because predep prevents us from being able to download all the packages and then analyze them. What this really means is that predep packages are not handled by the (TODO: unimplemented) planner.
For services there are additional kinds of dependencies:
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.
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.
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.
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:
Options to be given during source configuration, either passed to configure in the case of autoconf'd packages, or passed to perl Makefile.PL for perl "MakeMaker" packages.
Passed as standard input to the source configuration process.
A script which gets eval'd before the source configuration is done by perl Makefile.PL or configure.
If set to 1, this package has no meaningful build phase.
The pre_build_script and post_build_script are run whether or not no_build_phase is set.
A script which gets eval'd before the build target is made.
A script which gets eval'd after the build target is made.
If building and installing should take place in a subdirectory, set that here. Sometimes packages put everything in src.
Options to be given during the make process. These options are repeated in the install phase.
Options to be given during the make process, but not during the install phase.
Options to be given during the install process.
If set to 1, this package has no meaningful install phase.
The pre_install_script and post_install_script are run whether or not no_install_phase is set.
A script which gets eval'd before the install target is made.
A script which gets eval'd after the install target is made.
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 mechanism used to generate the source code configuration script.
packages use ExtUtils::MakeMaker to produce a Makefile.
The package uses GNU autoconf or automake or otherwise obeys the GNU GNU coding standard.
The package has a configure script, by default named configure, but take only the --prefix option.
the package has a configure script, but doesn't take --prefix. So the configure_options variable should be set to the equivalent of --prefix.
the package has no source code configuration phase.
A different script to run instead of ./configure or perl Makefile.PL.
The following extra configuration options are understood by raw or service packages:
If set to 1, don't automatically unpack tarballs that are found in the package.
The following extra files are automatically recognized by raw and service style packages:
Contains a script to build the binaries and data from the upstream tarball and patches, etc. in ext/build/$package-$version.
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.
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:
The basename of the package, e.g. wigwam-base.
The version number of the package, including the release number.
The "build" directory for the package. This is just $PLAYPEN_ROOT/ext/build/$PACKAGE-$VERSION.
This is where tarballs are automatically unpacked. If there is only one tarball included with the package, and all of its contents are in a single subdirectory, then the subdirectory's contents will be moved into EXT_PKGBUILDDIR for convenience. Otherwise, the tarball(s) will simply be unpacked.
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:
All packages which require any action other than just moving the files must set this to 1.
This package must be entirely rebuilt and reinstalled when the playpen is moved. This flag is highly discouraged.
This is a script that is run to relocate the build-directory.
This is a script that is run to relocate the installed image.
The various scripts may rely on the following shell variables:
Whether the package must be rebuilt.
Whether the package must be reinstalled.
The previous $PLAYPEN_ROOT; the location from which we are switching.
All packages should have documentation, eventually.
That documentation can be in one of two forms:
This file should be a DocBook SGML chapter -- it will be checked into the wigwam-package-archive CVS tree.
Such documentation must be freestanding text -- if you need other files you must make a tarball out of them.
If the package contains its own SGML documentation, it should be referenced in its .options file, by
The package's documentation directory; all the data needed by the sgml file to build should be contained within this directory.
The sgml file relative to the documentation directory.
Set this if you have toplevel build targets that should be made before the documentation can be extracted [this makes building the documentation repository much slower but is needed in some cases]
Set this to 1 to omit POD files from the autogenerated documentation.
Set this to a list of file in POD format that are not automatically found. (Either because they do not end in .pod or because package_doc_skip_pod is set to 1.)
If you include a file PACKAGE-VERSION.synopsis with the package (it must be listed in the .files list), then it will be interpreted as a one sentence description of the package. For example, the synopsis for wigwam says:
A framework for developing projects that provide services. |
If you include a file PACKAGE-VERSION.description with the package (it must be listed in the .files list), then it will be interpreted as brief, but complete, description of the package. It will usually be several paragraphs long.
Alternately, the description may be stored as project_doc_description in the package's .options file.
We also support installing ChangeLog files, which are just lists of changes and in which version they were made. wigwam-base contains a ChangeLog which you may use as an example.
You may include a PACKAGE-VERSION.changelog file with your package, or it the changelog is contained in the tarball, you may use the package_doc_changelog_file shell variable to store the location of this file within the tarball.
Put important news that should go on your autogenerated homepage in this file.
You may include a PACKAGE-VERSION.news file with your package, or it the NEWS file is contained in the tarball, you may use the package_doc_news_file shell variable to store the location of this file within the tarball.