NAME

Debian::Package::Make - Perl extension for autobuilding Debian packages

SYNOPSIS

Debian::Package::Make and Debian::Package::Make::* is a set of modules designed to make automatically building Debian packages easier. This can be useful for contents that need to be updated very frequently (i.e. antispam or antivirus patterns) or for software whose author does not permit redistribution of his work in a way that would allow the package to be included in Debian or derived distributions.

DESCRIPTION

(or: Creating your package in seven easy steps)

In a nutshell, Debian::Package::Make and its derived classes provide code and sensible default values and behavior to perform the steps necessary to build a Debian package from source.

1. Create build environment

When a Debian::Package::Make::* object is created through the new constructor, a temporary directory is created. This directory is called the base directory and its path is stored in the object's base_dir attribute. All files that are needed in the package creation process should be put underneath this directory. Since this is a temporary directory, it should be safe to remove it afterwards.

2. Obtain original material

The material from which package(s) will be built may either be supplied as a tarball or provided from a directory.

If a tarball is available on a public Internet host or locally, the download_orig_tarball or copy_orig_tarball method, respectively, should be used for placing this tarball in the base directory. The downloaded or copied file will be named in a scheme that dpkg-buildpackage will recognize. (i.e. foobar_0.3.orig.tar.gz)

If the source material is not available as a tarball, generate_orig_dir can be overloaded. The base method's purpose is to create a directory that can be filled, i.e. by downloading current updates for an antivirus product. The directory for the original material will be named in a scheme that dpkg-buildpackage will recognize. (i.e. foobar-0.3.orig/)

The version number of the package(s) should be determined and set as soon as possible, either from the URL or filename or from the contents that have been downloaded, copied, or generated.

3. Lay out foundation for build directory

The generate_build_dir method creates the build directory (i.e. foobar-0.3/) and fills it with content. The build_dir attribute contains the path of the build directory.

For non-native packages (where Debian-specific changes are applied to the source package), it unpacks the original tarball or copies the content of orig_dir to the build directory.

4. Apply Debian-specific changes to build directory

The generate_files method is used to write out the contents of the files attribute to the build directory.

The contents of files should be set by a prepare_files method. which is not implemented in the Debian::Package::Make base class.

The Debian::Package::Make distribution provides two classes that offer different approaches for adding files to the build directory. Since this is where most of the effort in generating Debian packages goes, a design goal for Debian::Package::Make was to provide the greatest possible flexibility at this stage.

5. Finally build the package(s)

The build_source, build_binary, and build method call dpkg-buildpackage with appropriate options for performing a source-only, binary-only, or source+binary build, respectively.

6. Copy the resulting files to a destination directory

The copy_files method copies resulting files to the a destination directory, defaulting to the current working directory.

7. Clean up temporary files

The cleanup method does no more than removing the contents of build_dir.

ATTRIBUTES

The following attributes are defined in Debian::Package::Make::* objects. If it is necessary to get or set attributes, object methods should be used:

$foobar_generator->version '0.3-2';

Derived classes that need to define additional simple attributes may do so by adding entries to the @ATTRIBUTES array that they inherit from Debian::Package::Make.

Housekeeping for Debian::Package::Make

base_dir

orig_dir

build_dir

orig_tarball

orig_tarball_extension

Variables for debian/control

source

section

priority

maintainer

uploaders

Variables for debian/changelog

version, epoch, upstream_version, debian_revision

A package's version consists of an epoch(optional), the upstream version, and the debian revision(optional). If the version attribute is set, it is parsed into the three components. Vice versa, if any of the three mentioned components is set, the version attribute is updated.

distribution, urgency

The distribution attribute identifies the distribution into which the package should be uploaded (i.e. stable, unstable, experimental.) The urgency attribute is an indicator that tells Debian's archive infrastructure how fast a package should propagate from the unstable distribution to the testing distribution (i.e. low, medium, high.).

changes

A list (ARRAY) of items that will be put into debian/changelog as a bulleted list.

me

Uploader's name and e-mail address.

builddate

verbose

PUBLIC INTERFACE

new

Creates an Debian::Package::Make object and sets up

• a base directory (base_dir attribute)

• a build directory (build_dir attribute) and

• semi-sensible defaults for the priority, distribution, urgency, changes, me, builddate attributes

• defaults for the source, section, and version attributes that are not sensible at all and should be set by a subclass.

It is probably not a good idea to call this method directly in a script; create a subclass instead.

detect_version

Use a regular expression to detect the version number in common filename patterns, e.g.:

• COMset-2.6.28.tar.gz

• BitDefender-scanner-7.5-4.linux-gcc3x.i586.tar.run

• /tmp/downloads/AdobeReader_enu-7.0.9-1.i386.tar.gz

• http://dl.google.com/linux/standalone/picasa-2.2.2820-5.i386.bin

This method is called by the standard copy_orig_tarball and download_orig_tarball methods after they have done their work.

copy_orig_tarball

• file

• extension

  If the extension can't be determined from the URL, it must be specified. gz or bz2.

Put the original tarball into the base directory.

The subclasses' version of this method is probably a good place to determine the version number for the package.

download_orig_tarball

• url

• extension

  If the extension can't be determined from the URL, it must be specified. Debian::Package::Make can currently cope with gz and bz2.

Download url to the base directory and set the orig_tarball attribute to the downloaded file..

generate_orig_dir

Create a directory source-version.orig/ beneath the base directory. The name of this directory is stored in the orig_dir attribute.

copy_orig_tarball download_orig_tarball, or generate_orig_dir methods in derived classes are probably good places to determine and set the version number.

generate_build_dir

Put source files into the build directory, by extracting them from the orig_tarball or by copying them from the orig_dir

test_build_setup

Method that can be used to tet setup before calling dpkg-buildpackage

prepare_files

prepare_files() is not implemented in Debian::Package::Make. Derived classes should populate %$self->{files} (see below) that is used by generate_files() to generate BUILDDIR/debian.

process_templates

This function is used internally to replace macros within files ending with .in. the following macros are currently recognized.

• #SECTION#

• #PRIORITY#

• #POLICY#

• #SOURCE#, #PACKAGE# (synonomous)

• #VERSION# ( #EPOCH#, #UPSTREAMVERSION#, #DEBIANREVISION# )

• #DISTRIBUTION#

• #URGENCY#

• #CHANGES#

• #USERNAME#

• #EMAIL#

• #DATE#

generate_files

generate_files() creates files in build_dir/debian (and possibly other new files) from %$self->{files}.

output_add_changes_file

Expects a .changes file and adds that plus referenced files to output_files.

build_source

Builds a source-only package.

build_binary

Builds one or more binary-only packages.

build

Builds source and binary packages.

call_buildpackage

Calls dpkg-buildpackage from within base_dir.

copy_files

Copies .changes file and source and/or binary files that are referenced in the .changes file to dest_dir.

• dest_dir

  specifies the destination directory. Defaults to the current working directory.

• overwrite

  Normally, copy_files does not overwrite existing files in the destination directory because that may. This switch overrides this.

cleanup

Removes base_dir and all its subdirectories. All those valuable auto-generate package files will be lost. Applications should therefore copy what they need somewhere else before calling cleanup.

file_version

Returns the version of the generated file names. (either upstream_version or upstream_version.debian_version).

HELPER FUNCTIONS

These functions are documented here only for reference. They should not be called from within derived classes.

_run_cmd

Simple wrapper around system that emits warnings if the called program returns with an exit code != 0 or can't be executed.

_rename_source_files

If necessary, this function renames orig_tarball, build_dir, orig_dir so that they are in sync with the source, version, and orig_tarball_extension attributes.

Derived classes should not need to call this method directly nor implement extensions to it.

AUTOLOAD

BUGS

Likely. Please report them, either through the Debian Bug Tracking System or to the author.

KNOWN BUGS

• Error checking needs work.

• Support for native packages isn't well tested yet.

• The template mechanism is under-documented and needs work.

SEE ALSO

• Debian::Package::Make::Debhelper, Debian::Package::Make::TemplateDir, debhelper(7), dpkg-source(1), dpkg-buildpackage(1)

• The examples directory in the Debian::Package::Make distribution.

• Debian Policy Manual and Debian Developer's Reference

AUTHOR

Hilko Bengen, <bengen@debian.org>

COPYRIGHT AND LICENSE

Copyright (C) 2008 by Hilko Bengen

This library is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

cpanm Debian::Package::Make

perl -MCPAN -e shell
install Debian::Package::Make