||<>|| == Introduction == === What is Packaging? === Software applications in Ubuntu are distributed as packages via repositories. Package management tools in Ubuntu search the repositories for updates and new applications to install. Package managers include apt, Synaptic, and the Application Center. Package maintainers manage the software in the Ubuntu repositories. To learn more about installing applications on Ubuntu, see https://help.ubuntu.com/community/InstallingSoftware. ## You can package without submitting it to Ubuntu ## By "building", do you mean the source or binary package (or both)? Packaging is the process of creating an archive of the files and directories an application needs for installation on an Ubuntu system. Building packages involves using tools that automate most of the process. This process includes compiling the package source and updating the information files that describe the application in package management tools. The complete package can then be submitted to the Ubuntu repository for review. === Who is this Guide For? === The Packaging Guide targets intermediate Ubuntu users who are comfortable with the Command Line Interface and have installed applications on Ubuntu. The Packaging Guide is ideal for: * Ubuntu users who want to learn more about how Ubuntu works. * Ubuntu users who would like to contribute to the Ubuntu community. * Ubuntu developers who would like to contribute their own applications or downstream patches to the Ubuntu repository. == The Packaging Environment == === Overview === The packaging environment in Ubuntu is a set of applications and scripts that streamline the packaging process. === Packaging Tools === ## What makes an application an "Ubuntu application"? ## Good question. These instructions are specific to packaging applications in Ubuntu versus other distros or operating systems. I can just say "applications" and drop the Ubuntu if it comes off as redundant. -augustina To get started with packaging Ubuntu applications, install the following packages from the Ubuntu repository. Each is discussed in more detail in its own section below. * build-essential * devscripts * debhelper * dh_make * gnupg * pbuilder The tools in this section are not required, but they do make the packaging process easier. Additional tools are discussed in the Advanced section. (Provide link once section is available) ==== Build-Essential ==== ## You might want to look at and link to http://www.debian.org/doc/packaging-manuals/build-essential The [[apt:build-essential|build-essential]] package is a collection of standard development tools. Tools in other packages depend on these tools to create packages. For more information on the build-essential package, see the entry for build-essential in the Debian Packaging Manual - [[http://www.debian.org/doc/packaging-manuals/build-essential]] ==== Devscripts ==== ## Link to the section The [[apt:devscripts|devscripts]] package contains scripts for automating packaging tasks. The primary tool used in this package is `debuild`. See the section Package the Application with Automation Tools to learn more about `debuild`. ==== Ubuntu-Dev-Tools ==== The [[apt:ubuntu-dev-tools|ubuntu-dev-tools]] package is a collection of scripts specific for Ubuntu packagers. ==== Debhelper ==== The [[apt:debhelper|debhelper]] package contains scripts that perform common packaging tasks. ==== Dh_Make ==== [[apt:dh-make|dh_make]] creates the debian directory and generates files that describe the package. ==== GnuPG ==== All packages submitted to Ubuntu must be signed with a [[apt:gnupg|GnuPG]], or GPG, signature. To set up a GPG key, follow the instructions labeled "Using GnuPG to generate a key" here: https://help.ubuntu.com/community/GnuPrivacyGuardHowto ==== Pbuilder ==== Pbuilder is one of several tools available to test packages. Other tools, including sbuilder and the Personal Package Archives (PPA), are discussed in the "Advanced Packaging" reference. Pbuilder uses chroot to construct a minimal Ubuntu installation for building and validating packages. Pbuilder was developed for package maintainers because `chroot` environments can be difficult to set up. This section covers installing Pbuilder. See the section "Safe Packaging with Chroot and Pbuilder" for instructions for a minimal Pbuilder setup. See the PbuilderHowTo to learn more about Pbuilder: https://wiki.ubuntu.com/PbuilderHowto === Safe Packaging with Chroot and Pbuilder === Pbuilder uses Chroot to create an isolated Ubuntu environment with a minimal installation for building and validating packages. Chroot keeps the development environment separate from your desktop environment, preventing conflicts in your desktop environment from affecting packages in the development environment. This section walks through a basic `pbuilder` setup. For more details, including how to target multiple versions of Ubuntu with `pbuilder`, see the PbuilderHowTo: https://wiki.ubuntu.com/PbuilderHowto ## Why bother duplicating information that already exists? Info on creating a pbuilder chroot is on the wiki page you link to. If you want it on this page as well, you should look into the 'Include' feature for the wiki ## Does <> have a way to include just a line or a section from another wiki? I want to highlight this particular information for the reader and am concerned that just referencing the other wiki will potentially create a frustrating situation. I emailed you about this issue. -augustina Create the chroot environment with pbuilder. {{{ sudo pbuilder create -debootstrapopts -variant=build }}} `pbuilder` creates a base tar file in `/var/cache/pbuilder` that contains the `chroot` environment. The "`--variant=build`" option includes the build-essential package in the chroot environment which contains tools required for packaging. == Basic Packaging == === Overview === The packaging process involves the following steps: 1. Get application source code 1. Edit files to describe the package. 1. Package the application with automation tools 1. Optionally, submit the package to the Ubuntu repository Each of these steps is explained in detail in its corresponding section below. See the tutorials under Basic Packaging Examples to apply the concepts described in each section. === Get Application Source Code === The source code for an application is required for the packaging process because the application needs to be built on the Ubuntu platform. Building on Ubuntu ensures compatibility and allows the package maintainer the opportunity to address any dependency issues. The Basic Packaging section of the Packaging Guide covers three ways to get the application source code: * Tar - For creating a new package that does not exist in the Ubuntu repository. * Apt-get source - For working with a package that exists in the Ubuntu repository. * Dget - For targeting a different version of Ubuntu than what is on your system. ==== Source Package Contents ==== A package contains the following file types: * .dsc - Debian Source Control file containing information about the source package. * .orig.tar.gz - The original source code, referred to as "upstream". * .diff.gz - Changes, or patches, made to the original source code. The .dsc file contains information that describes the package. The .dsc also contains md5 checksums that validate the integrity of the package. Md5 checksums are used by the installation process to ensure the archived source code isn’t corrupted. debuild, discussed in the section "Package the Application with Automation Tools", creates the .dsc file from a series of files dh_make generates during the packaging process. Ubuntu runs its own version of applications, including Gnome and Debian packages. The upstream version of an application is the version provided by the original developers. The downstream version of an application is the version modified for use in Ubuntu. The .orig.tar.gz file is the original source code provided by the developer, or the upstream code. The .diff.gz file contains a history of modifications that have been applied to the original source code. When you download the source package from a repository, an extraction utility applies the .diff.gz file to the original source code extracted from .orig.tar.gz. apt and dget do this automatically on download. Applying the .diff.gz file creates the downstream version of the application Ubuntu users install from the repositories. See the Extraction section for alternate ways to apply the .diff.gz file. ==== Source Code from a Tar File ==== Download an existing tar file or create a tar file from files on your system. See Example 2 for one way to download a tar file. If you are packaging software that is not available as a tar file, create the tar file from an unpacked source directory. Make a directory labeled with the name of the application, a dash, and the version number of the application. {{{ mkdir hello-2.4 }}} Copy the files for the application into the newly created application directory. {{{ cp myhello/* hello-2.4 }}} Run Tar on the on directory to create the tar file. {{{ tar czf hello-2.4.tar.gz hello-2.4 }}} Tar creates a file labeled hello-2.4.tar.gz. Create a copy of the tar file with the “orig” extension to designate it as the .orig.tar.gz file in the package. {{{ cp hello-2.4.tar.gz hello_2.4.orig.tar.gz tar -xzvf hello_2.4.orig.tar.gz }}} Note the use of the underscore between the package name and the version number. This format is required by the Debian packaging tools. Without it, the tools do not recognize the original source and the package is built as a Debian native package. ==== Apt-get Source ==== Use `apt` to download source code that exists in the Ubuntu repositories. Modify the Software Sources list to include source repositories either by modifying the sources.list file or by changing the Repositories settings in Synaptic. To modify the sources.list file, open `/etc/apt/sources.list` with root privileges. {{{ sudo gedit /etc/apt/sources.list }}} Uncomment lines starting with "deb-src" by deleting the hash "#" character at the beginning of the line. {{{ # deb-src http://us.archive.ubuntu.com/ubuntu/ jaunty main restricted }}} For more information on using Synaptic to enable source downloads, visit https://help.ubuntu.com/community/InstallingSoftware. Navigate to the directory where you want `apt` to download the source. From the terminal, run the apt-get source command with regular user privileges. NOTE: Most apt commands involve modifying files at the system level which requires root privileges. If you run apt-get source with root privileges, i.e. sudo, the resulting files will only be modifiable by a user with root privileges. {{{ cd ~/hello apt-get source hello-debhelper }}} `apt` downloads the source to the location where you run the command and extracts it. ==== Dget ==== `dget`, a tool in the devscripts package, downloads the source from a path you specify. Use `dget` to download packages from a different version than your system installation. For instance, if you want to build a package from a previous version of Ubuntu, use `dget` to download the package from the correct repository. `dget` requires either the package name or a URL to a .dsc file. For more details on `dget`, from the command line, either type `dget --h` or type `man dget`. Look up packages at http://packages.ubuntu.com for Ubuntu packages and http://packages.debian.org for Debian packages. Select the distribution version from the list shown. This returns a list of package sections. If you don’t know which section your package is in, click on the link for all packages at the bottom of the page. This returns a list of all packages and can take a few seconds to load. Use Control-F to find your package. Click on its name to view the package information. The link to the .dsc file is on the far right column under "Ubuntu Resources". Click on the link to the .dsc file and copy the URL. {{{ dget http://archive.ubuntu.com/ubuntu/pool/main/h/hello-debhelper/hello-debhelper_2.2-3.dsc }}} ==== Extraction ==== `dget` and `apt-get source` extract the package from the source files automatically on download. If you downloaded the individual archives through other means, unpack them using `dpkg-source`. {{{ dpkg-source -x *.dsc }}} === Edit the Source Files === Use `dh_make` to create the debian directory and the packaging information files. The debian directory separates the packaging information files from the application source files. ==== Run Dh_Make ==== From the source directory, run dh_make and specify an email address. This email address should be the same as the one the GPG certificate is assigned to. The packaging tools will verify this later in the build process. {{{ cd hello-2.4 dh_make -e gpgemail@domain.com }}} Specify the type of package. * Single Binary * Multiple Binary * Library * Kernel Module * CDBS {{{ Type of package: single binary, multiple binary, library, kernel module or cdbs? [s/m/l/k/b] }}} dh_make fills out the rest of the information based on system variables and values present in the source files. {{{ Maintainer name : Your Name Email-Address : gpgemail@domain.com Date : Thu, 6 Apr 2006 10:07:19 -0700 Package Name : hello Version : 2.4 License : blank Using dpatch : no Using quilt : no Type of Package : Single Hit to confirm: }}} Press the enter key. `dh_make` confirms it created the files. Only run dh_make once. If you need to change any of the values you entered, remove the source directory and extract the tar file again. Repeat the steps to run `dh_make`. {{{ cd .. rm -r hello-2.4 tar -xzvf hello_2.4.orig.tar.gz }}} ==== The Debian Directory ==== `dh_make` creates the `debian` directory containing the package information files and several template files ending in .ex. The basic packaging information files dh_make creates are: * Changelog * Control * Copyright * Rules * Compat Each file is discussed in the corresponding subsection below. See the Debian New Maintainer’s Guide for more detail on each of these files: http://www.debian.org/doc/manuals/maint-guide/ch-dreq.en.html Additional files `dh_make` adds that are not covered in this section: * README.Debian: Debian and Ubuntu end-user documentation file. * dirs: Used by dh_installdirs to create needed directories. * docs: Used by dh_installdocs to install program documentation. * info: Used by dh_installinfo to install the info file. For more information about these files, see the section `dh_make` example files. Also see the Debian New Maintainers’ Guide section that discusses these files in detail: http://www.debian.org/doc/manuals/maint-guide/ch-dother.en.html ==== Changelog ==== The Changelog file lists changes made in each version of the application. The specific format provides the package name, version, distribution, changes, and who made the changes. Use your GPG Key name and email address in the Changelog. Look at the contents of the Changelog by using any text viewer. Here is a sample of what a new Changelog looks like: {{{ cat changelog hello (2.4-0ubuntu1) jaunty; urgency=low *Initial release (Closes: #1234) --GPG Username Sun, 26 Jul 2009 10:44:53 -0700 }}} To add an entry to the Changelog, use `dch`. {{{ cd ~/hello/hello-2.4 dch -i }}} `dch` opens a text editor of your choice with a new entry in the Changelog file. `nano` is the easiest to use. Press Enter to use `nano`. {{{ Select an editor. To change later, run ‘select-editor’. /usr/bin/vim.tiny /bin/ed /bin/nano <---- easiest Choose 1-3 [3]: }}} `dch` populates the new entry with your GPG name, GPG email address, the date in RFC822 format, and the incremented version number. Write a brief explanation for the new release. Use a dash "-" for minor changes; use an asterisk "*" for major changes. Change the Ubuntu distribution name after the version number to the distribution you are targeting, if different. Notice that the version has -0ubuntu1 appended to it. This is the distro revision, used so that the packaging can be updated with new uploads within the same source release version, e.g. for bug fixes. Ubuntu and Debian have slightly different package versioning schemes to avoid conflicting packages with the same source version. If a Debian package has been changed in Ubuntu, it has "ubuntu" and the Ubuntu version number appended to the end of the Debian version. For example, the Debian hello 2.4-1 package would be 2.4-1ubuntu1. If a package for the application does not exist in Debian, then the Debian revision is 0 (e.g. 2.4-0ubuntu1). {{{ hello (2.4-1ubuntu1) jaunty; urgency=low * Major change explanation. - Minor change explanation. -- gpg name Tue, 28 Jul 2009 01:01:22 -0700 hello (2.4-0ubuntu1) jaunty; urgency=low *Initial release (Closes: #1234) --GPG Username Sun, 26 Jul 2009 10:44:53 -0700 }}} Press Control-X to exit and type Y when prompted to save. Type N if you don’t want to save. If you didn’t edit the entry dch generated, nano will close the Changelog without committing any changes. Consult the Debian Changelog Policy for more information about proper Changelog format: http://www.debian.org/doc/debian-policy/ch-source.html#s-dpkgchangelog ==== Control ==== The Control file contains information the package manager uses to display the package description, for managing package installation, and for determining dependent packages that also need to be installed. The Control file is separated into two sections by a blank line. The first section contains basic information about the package. The second section contains information on how to build the package. If the package includes multiple binaries, each binary gets its own entry in the second section separated by a blank line. See the Debian Policy Manual for more details on what fields are required and what the options mean: http://www.debian.org/doc/debian-policy/ch-controlfields.html Source The source field contains the name of the source package. See the "Package" entry for a note about naming. {{{ Source: hello }}} Section The `apt` repositories are organized in sections for ease of browsing and categorization of software. {{{ Section: devel }}} Priority The priority field indicates the importance of the package. "Optional" is sufficient for new packages. For details on what different priorities are available and what they mean, see the Debian Policy Guide: http://www.debian.org/doc/debian-policy/ch-archive.html#s-priorities {{{ Priority: optional }}} Maintainer The maintainer field contains the name of the package maintainer and their email address. In Ubuntu the Maintainer field is set to a general address because anyone can change any package. This differs from Debian where changing packages is usually restricted to an individual or a team. {{{ Maintainer: Santiago Vila }}} Standards-Version Standards-Version indicates the version of the Debian Policy the package uses. {{{ Standards-Version: 3.8.0 }}} Use apt-cache to get the current version. Use everything to the left of ".1ubuntu2". {{{ apt-cache show debian-policy | grep Version Version: 3.8.0.1ubuntu2 }}} Build-Depends Build-Depends lists the binary packages required to create the binary package from the source package. {{{ Build-Depends: debhelper (>= 7), autotools-dev }}} Do not include packages that are part of build-essential. Refer to the list of build-essential packages at `/usr/share/doc/build-essential/list`. Homepage Homepage is an optional field that provides a URL for the software. {{{ Homepage: http://www.gnu.org/hello }}} Package Package is the first entry in the second section of the Control file. It contains the name for the binary package. Often the source and binary package names are identical. NOTE: Regarding package naming, the source and binary packages should have an appropriately descriptive name. The name should not clutter the namespace (such as "editor") nor should the name be nonsensical (such as "new-stuff-manager"). {{{ Package: hello }}} Architecture The architectures the package is built for, including: * All - The source is not architecture-dependent. Programs that use Python or other interpreted languages would use this. The resulting binary package would end with _all.deb. * Any - The source is architecture dependent, but compiles on all architectures supported by Ubuntu. The packaging process will create a .deb file for each architecture, e.g. _i386.deb. If the source does not work for all architectures supported by Ubuntu, provide a list of the architectures it does support in this field. {{{ Architecture: any }}} Depends Depends provides the list of packages the package depends on for functionality. ${shlibs:Depends} is a variable that is used by dpkg-shlibdeps to add the shared library packages needed by the binaries to Depends. See the dpkg-source(1) and dpkg-shlibdeps(1) man page for more information about variables used in this field. {{{ Depends: ${shlibs:Depends} }}} Recommends Recommends provides a list of packages that should be installed with the package, but are not required. Some package managers, including apt, automatically install recommended packages. {{{ Recommends: package }}} Suggests Suggests provides a list of packages that are similar or useful when this package is installed. {{{ Suggests: hello }}} Conflicts Conflicts provides a list of packages that could negatively impact functionality of the package. Conflicting packages cannot be installed at the same time. If a conflicting package is installed, the package manager will suggest removal of it. {{{ Conflicts: hello }}} Description The package managers use descriptions to display information about the package to the user browsing the repository. The description field consists of a short description and a long description. Include one space at the beginning of each line in the long description. For more information on writing descriptions, see http://people.debian.org/~walters/descriptions.html {{{ Description: The classic greeting, and a good example The GNU hello program produces a familiar, friendly greeting. }}} ==== Copyright ==== The Copyright file includes the names of both the author and the packager, the URL the source came from, a Copyright line with the year and copyright holder, and the text of the copyright itself. Dh_make generates an example copyright you can view in the debian directory. {{{ cat ~/hello/hello-2.4/debian/copyright }}} All files, including documentation, must be covered by a license statement. Copyright information is in the COPYING file in the program's source directory. See the Copyright section of this guide for more information. ==== Rules ==== The rules file provides instructions to `debuild` for creating the package. It is a Makefile that contains definitions for compile targets, instructions for installing the application, instructions for creating the .deb package from the installed files, and a target for cleaning up the build files. The Debian New Maintainers Guide discusses the rules file in detail: http://www.debian.org/doc/manuals/maint-guide/ch-dreq.en.html#s-rules This is a simplified version of the rules file `dh_make` created: {{{ package = hello CC = gcc CFLAGS = -g -Wall ifeq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) CFLAGS += -O2 endif #export DH_VERBOSE=1 clean: dh_testdir dh_clean rm -f build -$(MAKE) -i distclean install: build dh_clean dh_installdirs $(MAKE) prefix=$(CURDIR)/debian/$(package)/usr \ mandir=$(CURDIR)/debian/$(package)/usr/share/man \ infodir=$(CURDIR)/debian/$(package)/usr/share/info \ install build: ./configure --prefix=/usr $(MAKE) CC="$(CC)" CFLAGS="$(CFLAGS)" touch build binary-indep: install binary-arch: install dh_testdir -a dh_testroot -a dh_installdocs -a NEWS dh_installchangelogs -a ChangeLog dh_strip -a dh_compress -a dh_fixperms -a dh_installdeb -a dh_shlibdeps -a dh_gencontrol -a dh_md5sums -a dh_builddeb -a binary: binary-indep binary-arch .PHONY: binary binary-arch binary-indep clean checkroot }}} The Rules file consists of the following sections: * Variable declarations * Build * Clean * Install * Binary-indep * Binary-arch Variable declarations The variables in this section set the flags for the compiler and handle the noopt options for debugging. {{{ package = hello CC = gcc CFLAGS = -g -Wall ifeq (,$(findstring noopt,$(DEB_BUILD_OPTIONS))) CFLAGS += -O2 endif #export DH_VERBOSE=1 }}} Build The build rule runs ./configure and make which creates a build file. {{{ build: ./configure --prefix=/usr $(MAKE) CC="$(CC)" CFLAGS="$(CFLAGS)" touch build }}} Clean The clean rule runs `make -i distclean` and removes extra files that are generated in the build step. {{{ clean: dh_testdir dh_clean rm -f build -$(MAKE) -i distclean }}} Binary-indep Some packages do not contain files that are specific to the processor. These are architecture-independent packages. Python and artwork packages are examples of this; their packages end with _all.deb. Use the binary-arch field for architecture-independent packages. The default value is "install". Keep the default value if the package is not architecture-independent. {{{ binary-indep: install }}} Binary-arch Packages that must be compiled for each processor are architecture-dependent. The packages end with _i386.deb for 32-bit architectures, _amd64.deb for 64-bit architectures, _lpia.deb for MIDs, to name a few examples. Use the binary-arch field for architecture-dependent packages: {{{ binary-arch: install dh_testdir -a dh_testroot -a dh_installdocs -a NEWS dh_installchangelogs -a ChangeLog dh_strip -a dh_compress -a dh_fixperms -a dh_installdeb -a dh_shlibdeps -a dh_gencontrol -a dh_md5sums -a dh_builddeb -a }}} This rule runs debhelper scripts which to create the .deb packages. While a few of the scripts are discussed here, for further detail see The Debian New Maintainers’ Guide: http://www.debian.org/doc/manuals/maint-guide/ch-dreq.en.html#s-rules 1. dh_testdir checks that the current working directory is the top level source directory. 1. dh_testroot checks that script is run with the correct permissions, i.e. root. 1. dh_installdocs copies the documentation files specified in the .doc file. 1. dh_installchangelogs copies the files specified in the .changelog file. 1. dh_strip removes debugging code from the application files to make them smaller. 1. dh_compress compresses documentation files using gzip. 1. dh_shlibdeps adds library dependencies to the Depends: ${shlibs:Depends} field in debian/control. 1. dh_builddeb builds the .deb package. ==== Compat ==== Compat contains the version number for the debhelper scripts. A conflicting version number can cause problems with the debhelper scripts. === Package the Application with Automation Tools === `debuild` builds the binary packages. 1. `debuild` checks that all the build-depends packages specified under "Depends" in the Control file are installed. 1. `dpkg-buildpackage` compiles, installs, and builds the package using the rules defined in the Rules file. 1. `lintian` checks the package for errors. 1. `debsign` signs the packages using your GPG key. To digitally sign packages, start `debuild` with the "-k" flag followed by your GPG key ID. {{{ debuild -k }}} Append "k" to any of the options below, e.g. `debuild -Sk`. To build a .deb package locally, enter the source directory and run `debuild`. This creates a .deb package in the directory above the source directory. {{{ cd ~/hello/hello-2.4 debuild }}} While this is sufficient for creating .deb files that can be installed on your own system, Ubuntu packages must be built from source. Use debuild to create a .dsc package, then use pbuilder to package it in a clean chroot environment. See the Packaging Environment section to set up pbuilder. {{{ cd ~/hello/hello-2.4 debuild -S }}} The `-S` flag tells `debuild` to build a source package using additional scripts, `dpkg-buildpackage` and `fakeroot`. debuild creates a .diff.gz archive and a .dsc file from the .orig.tar.gz file. The .dsc and *_source.changes (used for uploading the source package) files are signed using your GPG key. `debuild` runs `lintian` to check the source package for common mistakes. Lines beginning with "W:" are warnings. Lines beginning with "E:" are errors and are followed by lines beginning with "N:" which contain explanations for the errors. You can also run `lintian` manually: {{{ cd ~/hello lintian -Ivi *.dsc }}} Once debuild builds the source package, use the .dsc file to build the corresponding package in the pbuilder environment: {{{ sudo pbuilder build ~/hello/hello.dsc }}} The importance of building packages in a clean chroot environment with `pbuilder` are discussed in the section, "Safe Packaging with chroot and pbuilder". Because `pbuilder` provides a minimal environment, all build-time dependencies are determined by the Control file. `pbuilder` builds the .deb package as follows: 1. Extracts the base tarball and creates the chroot environment. 1. Checks dependencies and installs those packages into the chroot environment. 1. Runs make. 1. Cleans the chroot environment. `pbuilder` creates the package as a .deb file in `/var/cache/pbuilder/result`. === Submit the Application to the Ubuntu Repository === First follow the instructions in the New Packages guide to submit your package for inclusion in the Ubuntu repositories: https://wiki.ubuntu.com/UbuntuDevelopment/NewPackages Upload packages to Launchpad’s Personal Package Archives (PPA). More information about setting up a PPA is here: https://help.launchpad.net/Packaging/PPA The source package is held in the "new" queue until it is reviewed by the ubuntu-archive team: https://launchpad.net/~ubuntu-archive === Basic Packaging Examples === ==== Example 1: Examine an Existing Package ==== To understand more about package structures, we can compare our package to one that is already packaged in the Ubuntu repository called hello-debhelper. Create a directory in your home directory called hello-debhelper. Get the source code for debhelper using apt-get. If you are unable to get the source code using apt-get, either see the Apt-get Source section above or follow the instructions above for dget. {{{ mkdir ~/hello-debhelper cd ~/hello-debhelper apt-get source hello-debhelper }}} View the contents of the directory with the same label as the package you downloaded. Enter the debian directory. {{{ cd debian }}} View the contents of each of the files discussed in the above section. A few are highlighted below. View the contents of the changelog file. {{{ less changelog }}} Notice that in this case the distribution is unstable (a Debian branch), because the Debian package has not been changed by Ubuntu. View the contents of the copyright file. {{{ cat copyright }}} Notice that the Ubuntu package's copyright includes a license statement for the manual. For further study, download source for applications you are familiar with to see how the packages are structured. ==== Example 2: Package GNU Hello From Scratch ==== Make a directory called hello and download the the GNU hello program source tar file from ftp.gnu.org to that directory. {{{ mkdir ~/hello cd ~/hello wget http://ftp.gnu.org/gnu/hello/hello-2.4.tar.gz }}} Copy the original source code into the orig file. {{{ cp hello-2.4.tar.gz hello_2.4.orig.tar.gz tar -xzvf hello_2.4.orig.tar.gz }}} NOTE: Use an underscore ('_') between the package name (hello) and the version number (2.4) in the orig.tar.gz, as opposed to a hyphen ('-'). This format is required by the packaging tools to identify the original source. We now have a hello-2.4 directory containing the source files. Change to hello’s root directory, i.e. hello-2.4 {{{ cd ~/hello/hello-2.4 }}} Run dh_make and specify an email address. This email address should be the same as the one the Gnupg certificate is assigned to. {{{ dh_make -e gpgemail@domain.com }}} For hello, specify a single binary. {{{ Type of package: single binary, multiple binary, library, kernel module or cdbs? [s/m/l/k/b] s }}} {{{ Maintainer name : Your Name Email-Address : your.maintainer@address Date : Thu, 6 Apr 2006 10:07:19 -0700 Package Name : hello Version : 2.4 License : blank Type of Package : Single Hit to confirm: Enter }}} Press the enter key once the values have been entered. {{{ Skipping creating ../hello_2.4.orig.tar.gz because it already exists Done. Please edit the files in the debian/ subdirectory now. Hello uses a configure script, so you probably don’t have to edit the Makefiles. }}} Remove extra files unneeded for the hello application: {{{ cd cd ~/hello/hello-2.4/debian rm *.ex *.EX }}} At this point, you should have only changelog, compat, control, copyright, and rules files in the debian directory. Here is a sample Changelog file for hello: {{{ hello (2.4-0ubuntu1) jaunty; urgency=low * New upstream release with lots of bug fixes and feature improvements. -- Captain Packager Wed, 5 Jan 2009 22:38:49 -0700 }}} Here is the Control file for the Ubuntu hello package: {{{ Source: hello Section: devel Priority: optional Maintainer: Ubuntu MOTU Developers XSBC-Original-Maintainer: Captain Packager Standards-Version: 3.7.3 Build-Depends: debhelper (>= 5) Homepage: http://www.gnu.org/software/hello/ Package: hello Architecture: any Depends: ${shlibs:Depends} Description: The classic greeting, and a good example The GNU hello program produces a familiar, friendly greeting. It allows non-programmers to use a classic computer science tool which would otherwise be unavailable to them. Seriously, though: this is an example of how to do a Debian package. It is the Debian version of the GNU Project's `hello world' program (which is itself an example for the GNU Project). }}} hello is released under the GPL license. In this case it is easiest to copy the copyright file from the Ubuntu package downloaded in Example 1. {{{ cp ~/hello-debhelper/debian/copyright }}} Optionally, edit the remaining files. The default templates are sufficient to create the package with debuild. Build a local binary using debuild. {{{ cd cd ~/hello/hello-2.4 debuild }}} The finished .deb package is in the directory above the source (i.e. in ~/hello/). Build the package using pbuilder and the chroot environment. Run debuild to create the .dsc file. {{{ cd ~/hello/hello-2.4 debuild -S }}} We can check the source package for common mistakes using `lintian`: {{{ cd ~/hello lintian -Ivi *.dsc }}} Use the newly created .dsc file to build the corresponding binary package in a clean `pbuilder` environment: {{{ sudo pbuilder build cd ~/hello/*.dsc }}} The finished .deb package is at `/var/cache/pbuilder/result`. {{{ cd /var/cache/pbuilder/result ls *.deb }}} Install the package using dpkg. {{{ sudo dpkg --install hello_2.4-1_i386.deb }}} Finally, run your application by typing "hello" on the command prompt.