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
-
- Variables for debian/control
-
- 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"
- "version", "epoch", "upstream_version", "debian_revision"
-
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"
-
-
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"
-
-
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.
- "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.
- "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.
COPYRIGHT AND LICENSE
Copyright (C) 2008 by Hilko BengenThis 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.