Differences between revisions 1 and 2
Revision 1 as of 2009-03-15 14:02:15
Size: 600
Editor: hughszg
Comment:
Revision 2 as of 2009-03-15 14:06:53
Size: 12153
Editor: hughszg
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
#language en
||<tablestyle="width: 100%;" style="border: 0px hidden">~-[:DebianWiki/EditorGuide#translation:Translation(s)]: none-~||<style="text-align: right;border: 0px hidden"> (!) [:/Discussion:Discussion]||
#language zh
||<tablewidth="100%"style="border: 0px hidden ;">~-Translation(s): [:HowToPackageForDebian:English] - [:zh CN/HowToPackageForDebian:简体中文] -~ ||<style="border: 0px hidden ; text-align: right;"> (!) ["/Discussion"] ||
Line 4: Line 4:
Describe in one or two lines what your page is about. ## If your page gets really long, uncomment this Table of Contents
## [[TableOfContents(2)]]
= Introduction =
'''A pragmatic guide to creating a simple Debian package.'''
Line 6: Line 9:
## If your page gets really long, uncomment this Table of Contents
## [[TableOfContents(2)]]
This HowTo is intended to show that ''Debian packaging is not that hard''. Since Debian packaging is not that hard, why shouldn't plain beginners understand and do it, too?
Line 9: Line 11:
== Title 1 == As a teaser, here's a short list of some reasons to package a program:
Line 11: Line 13:
=== Sub title ===  * Obviously, you'll need a package if you want the program to be included in Debian.
 * The packaging system takes care of the old version, so if a file is moved in the source, uninstall still works properly (unlike when you use make uninstall with the new Makefile)
 * A package is an easy format to move programs between computers.
== Contents ==
Contents
Line 13: Line 19:
== Title 2 ==  1. [:HowToPackageForDebian#head-326002479229f407952aca03c011f39f5d83abe0:Introduction]
  1. 1. [:HowToPackageForDebian#head-59d6925cf952968c916ded25dba4ed6e8be56724:Contents]
   1. [:HowToPackageForDebian#head-946cf0a5b1ae6f2eee4d9b458609853d51fef528:Why does this page even exist?]
   1. [:HowToPackageForDebian#head-7d99f747157563697430ec1afbef8a60c157d566:Creating the package]
    1. [:HowToPackageForDebian#head-0983bf2eed7d68780c01b3b9acded3768dba6d28:Initial compilation]
    1. [:HowToPackageForDebian#head-fd0e7665b508f6048090ca91f5da595f58e1957f:''Debianization'']
    1. [:HowToPackageForDebian#head-eab1f9e9aca4ee45fef7f95ae7662d346b3e45a4:Initial compilation of the package]
    1. [:HowToPackageForDebian#head-4fdbe83bc4a589a4a44a0a59306c2948f5d6f4da:All tests in chroot]
    1. [:HowToPackageForDebian#head-6d7ce003984dbd8cbd5d70056cff3ab84f819c87:Testing the package]
    1. [:HowToPackageForDebian#head-73dd472ed15560641c791f7ed0a38f29c9a02322:Lintian]
    1. [:HowToPackageForDebian#head-2fd3d67e730c9d54acaeba9491d279b67ef12f1d:Piuparts]
    1. [:HowToPackageForDebian#head-dbfa996f2f4714c2e103706ab59eb53880dfaf31:Check points for any package]
    1. [:HowToPackageForDebian#head-9d71fa173d6d5541f2475003c3a8f40f3381c13e:Examples]
   1. [:HowToPackageForDebian#head-c81c2cb47693c9605718da94626f89843d2d5521:Advanced Packaging Procedures]
   1. [:HowToPackageForDebian#head-a0e5e7ed47b9639c964c6a95b4c16666d7484882:External useful links]
   1. [:HowToPackageForDebian#head-9d79e748a391abee3b924b7875d4e8fecb5e52da:Useful pages]
== Why does this page even exist? ==
Since the [http://www.debian.org/doc/debian-policy/ Debian Policy] and [http://www.debian.org/doc/manuals/maint-guide/index.en.html the Debian New Maintainers' Guide] sometimes are too big to read for people who prefer a more pragmatic approach to problems, this HowTo will focus on '''a pragmatic approach to learning how to create Debian packages'''.
Line 15: Line 38:
The Debian package management chapter of the Debian Reference contains lots of useful information for handling all kinds of problems one runs into with apt and dpkg.

== Creating the package ==
If the information below doesn't answer your questions, please look in the [http://www.debian.org/doc/maint-guide/ New Maintainer's Guide] and in [http://www.debian.org/doc/debian-policy/ Debian Policy]

If you want to create an official debian package, make sure it's not already packaged. If [http://www.us.debian.org/devel/wnpp/being_packaged somebody is working on the package], you should contact them if you intend to make an official package together. More info is in the [http://www.debian.org/doc/maint-guide/ New Maintainer's Guide].

=== Initial compilation ===
Before starting there are some risks you should be aware of:

'''WARNINGS:'''

 * All these operations are preferably done in a chroot environment for safety/security reasons. [http://packages.debian.org/search?suite=default&section=all&arch=any&searchon=names&keywords=pbuilder pbuilder] and [http://packages.debian.org/search?suite=default&section=all&arch=any&searchon=names&keywords=sbuild sbuild] are such evironments. Please consult the pbuilder or sbuild documentation.
 * '''running ''make'' on a system can be a security risk'''! It is recommended to check beforehand that the Makefile does not contain any funny stuff. Obscure/specially crafted applications might fall into this case.
 * '''do NOT run ''make install'', unless you are ''absolutely'' sure is safe to do that (check the install target of the makefile). This is a security risk and you may risk to break and/or compromize your system.'''
Steps:

 * Try to compile the package, but do not install it.
  * most compile failures will be the result of missing dependencies (usually they are mostly missing *-dev packages)
  * note every new package which you needed to install for compilation
   * some of the packages that were already installed on your system might be necessary, too (note: objdump -p | grep NEEDED will show exactly the needed libraries)
   * these packages will end up in the build-dependency list of the package
  * note quirks and tricks needed for the package to compile (missing files, file modifications, etc.), you will need to reproduce later in the package build rules
 * If you think you need specific software not already packaged, make sure that:
  * the needed software is not present in another package
  * the package is not being worked on ([http://www.debian.org/devel/wnpp/being_packaged ITP (Intent To Package) is pending])
  * are you sure it's not packaged? :) You could check other debian based distributions, too.
It is best to create a chroot jail in which to build the application. This mitigates security and system corruption problems. In addition it ensures that any local changes to your machine will not interfere with the build.

If the package compiles, then it means you '''may''' have figured out all the dependencies. Don't worry, this will be checked later in a chroot environment. Try the application in a chroot environment (some things might be needed in the chroot jail - for example, proc may need to be mounted, sys to be mounted, etc.). Broken installation scripts are, unfortunately, very common and you probably don't want to run a test installation yet. You might prefer doing the tests in a qemu virtual machine in snapshot mode - changes are not permanent in snapshot mode and you can keep you development machine safe from malitious/broken makefiles.

=== ''Debianization'' ===
After the first compilation, it's time to create the Debian specific part of the package.

[http://www.debian.org/doc/maint-guide/ch-first.en.html#s-dh_make Debianize] the package by using [http://packages.debian.org/dh-make dh_make].

File debian/control: Add to the Build-Depends (sometimes even Build-Depends-Indep) the list of packages needed to be installed for the application to compile (remember the list done previously). You should leave out any packages that are listed in /usr/share/build-essential/essential-packages-list or /usr/share/build-essential/list and also leave out any packages that listed as dependencies by any of those packages. More detailed information cane be found on the page about [:PkgDevCtrl:control file creation for the new package].

File debian/rules: If any quirking was done then:

 * automate the quirking and the changes needed to be done in the debian/rules file under a patch target
 * make sure there will be an unpatch target that reverses all the changes done in the patch target
 * make the clean target depend on the unpatch target
 * make the build target depend on the patch target
Review each of the template files (debian/*.ex). If your package needs that feature, then customize the file as needed and rename it without the ".ex".

Delete all the unneeded templates. Don't worry, they can be restored at any time with "dh_make -a".

Make sure that all the directories you will place files in are listed in the debian/dirs file without a leading slash (/).

Make sure that the files are installed in the proper place (under a directory, not on the root system). Take care at the install target from the application makefile. If the application uses autoconf and automake, it may be enough to set the environment variable DESTDIR, e.g. "make DESTDIR=$(CURDIR)/debian/packagename". (dh_make will set this up automatically.)

Note: very often the upstream package will install files under /usr/local. '''DO NOT INSTALL ANY FILES IN THERE'''.

=== Initial compilation of the package ===
TODO: add notes

=== All tests in chroot ===
Why is it a good idea to use a chroot?

 * Security
 * Testing
 * No risk to break the developer's system
 * Wrongly installed packages can be identified easily (ls -lR in the root of the chroot before and after the build; diff -u before.list after.list)
 * Missing build dependecies are identified easier, thus avoiding serious [http://en.wikipedia.org/wiki/FTBFS FTBFS] (Fails To Build From Source) bugs
 * The chroot system is a pure Debian system belonging to one suite only (e.g., Sarge, Etch or Sid if the chroot was built properly with debootstrap or cdebootstrap)
=== Testing the package ===
{{{licensecheck -r *}}}

TODO: add notes

=== Lintian ===
Test all the packages with [http://packages.debian.org/lintian lintian].

{{{lintian package-version.changes}}}

=== Piuparts ===
Test all the .deb packages with [http://packages.debian.org/piuparts piuparts].

{{{piuparts binpackage-version.deb}}}

=== Check points for any package ===
 * Is there a man page for every executable file in the package? In some rare cases it makes sense to have one man page for multiple binaries in a package.
 * Does it have a Debian menu entry? (daemons usually don't need this) Does it have a .desktop file?
 * If there are architecture independent things in the package and if they are big enough, are those packaged in a seperate package with [http://www.debian.org/doc/debian-policy/ch-controlfields.html#s-f-Architecture arch all]?
 * Does the package compile cleanly? This does '''not''' mean that you should redirect the errors to /dev/null
 * Does lintian scream when checking the .changes file?
 * What does piuparts have to say about the .debs?
 * http://people.debian.org/~neilm/sponsorship.html
 * http://people.debian.org/~mpalmer/sponsorship_checklist.html
''This page is still incomplete; please help by adding information to it. Do not forget that the information here should be in a concise form.''

=== Examples ===
 * The Oolite package was created following this techinque (actually, this page was written during oolite's initial packaging stage)
 * a somewhat simplistic example which assumes no upstream source when starting the package, can be found at [:PkgNew:Creating a new package from scratch] - this is more useful to upstream developers, not to people doing pure packaging work.
== Advanced Packaging Procedures ==
 * ["Renaming a Package"]
 * BzrBuildpackage/DesignIdeas
 * PackagingWithDarcs
 * PackagingWithGit
 * PbuilderTricks
 * [:PkgDummy:Creating a dummy package]
 * [:PkgSplit:How to split a package into smaller packages]
 * ["RPM"] - Converting a .RPM into .DEB - generally leads to bad results
 * DebugPackage
 * ["Packaging/How To Create A New Package"]
 * [:PackageArchitectureAlmostAny:Creating package without some particular architectures] - for easy porting
== External useful links ==
 * http://www.ibiblio.org/pub/Linux/docs/HOWTO/other-formats/html_single/Debian-Binary-Package-Building-HOWTO.html
 * https://wiki.ubuntu.com/MOTU/Packages/Packaging/Tips
 * http://qref.sourceforge.net/Debian/reference/ch-package.en.html
 * http://www.debian.org/doc/manuals/apt-howto/ and package apt-howto
== Useful pages ==
 * SoftwarePackaging
----
 . CategoryDeveloper
Line 17: Line 156:
##See also:  ##See also:

Translation(s): [:HowToPackageForDebian:English] - [:zh CN/HowToPackageForDebian:简体中文]

(!) ["/Discussion"]


Introduction

A pragmatic guide to creating a simple Debian package.

This ?HowTo is intended to show that Debian packaging is not that hard. Since Debian packaging is not that hard, why shouldn't plain beginners understand and do it, too?

As a teaser, here's a short list of some reasons to package a program:

  • Obviously, you'll need a package if you want the program to be included in Debian.
  • The packaging system takes care of the old version, so if a file is moved in the source, uninstall still works properly (unlike when you use make uninstall with the new Makefile)
  • A package is an easy format to move programs between computers.

Contents

Contents

  1. [:HowToPackageForDebian#head-326002479229f407952aca03c011f39f5d83abe0:Introduction]

    1. 1. [:HowToPackageForDebian#head-59d6925cf952968c916ded25dba4ed6e8be56724:Contents]

      1. [:HowToPackageForDebian#head-946cf0a5b1ae6f2eee4d9b458609853d51fef528:Why does this page even exist?]

      2. [:HowToPackageForDebian#head-7d99f747157563697430ec1afbef8a60c157d566:Creating the package]

        1. [:HowToPackageForDebian#head-0983bf2eed7d68780c01b3b9acded3768dba6d28:Initial compilation]

        2. [:HowToPackageForDebian#head-fd0e7665b508f6048090ca91f5da595f58e1957f:''Debianization'']

        3. [:HowToPackageForDebian#head-eab1f9e9aca4ee45fef7f95ae7662d346b3e45a4:Initial compilation of the package]

        4. [:HowToPackageForDebian#head-4fdbe83bc4a589a4a44a0a59306c2948f5d6f4da:All tests in chroot]

        5. [:HowToPackageForDebian#head-6d7ce003984dbd8cbd5d70056cff3ab84f819c87:Testing the package]

        6. [:HowToPackageForDebian#head-73dd472ed15560641c791f7ed0a38f29c9a02322:Lintian]

        7. [:HowToPackageForDebian#head-2fd3d67e730c9d54acaeba9491d279b67ef12f1d:Piuparts]

        8. [:HowToPackageForDebian#head-dbfa996f2f4714c2e103706ab59eb53880dfaf31:Check points for any package]

        9. [:HowToPackageForDebian#head-9d71fa173d6d5541f2475003c3a8f40f3381c13e:Examples]

      3. [:HowToPackageForDebian#head-c81c2cb47693c9605718da94626f89843d2d5521:Advanced Packaging Procedures]

      4. [:HowToPackageForDebian#head-a0e5e7ed47b9639c964c6a95b4c16666d7484882:External useful links]

      5. [:HowToPackageForDebian#head-9d79e748a391abee3b924b7875d4e8fecb5e52da:Useful pages]

Why does this page even exist?

Since the [http://www.debian.org/doc/debian-policy/ Debian Policy] and [http://www.debian.org/doc/manuals/maint-guide/index.en.html the Debian New Maintainers' Guide] sometimes are too big to read for people who prefer a more pragmatic approach to problems, this ?HowTo will focus on a pragmatic approach to learning how to create Debian packages.

The Debian package management chapter of the Debian Reference contains lots of useful information for handling all kinds of problems one runs into with apt and dpkg.

Creating the package

If the information below doesn't answer your questions, please look in the [http://www.debian.org/doc/maint-guide/ New Maintainer's Guide] and in [http://www.debian.org/doc/debian-policy/ Debian Policy]

If you want to create an official debian package, make sure it's not already packaged. If [http://www.us.debian.org/devel/wnpp/being_packaged somebody is working on the package], you should contact them if you intend to make an official package together. More info is in the [http://www.debian.org/doc/maint-guide/ New Maintainer's Guide].

Initial compilation

Before starting there are some risks you should be aware of:

WARNINGS:

Steps:

  • Try to compile the package, but do not install it.
    • most compile failures will be the result of missing dependencies (usually they are mostly missing *-dev packages)
    • note every new package which you needed to install for compilation
      • some of the packages that were already installed on your system might be necessary, too (note: objdump -p | grep NEEDED will show exactly the needed libraries)
      • these packages will end up in the build-dependency list of the package
    • note quirks and tricks needed for the package to compile (missing files, file modifications, etc.), you will need to reproduce later in the package build rules
  • If you think you need specific software not already packaged, make sure that:
    • the needed software is not present in another package
    • the package is not being worked on ([http://www.debian.org/devel/wnpp/being_packaged ITP (Intent To Package) is pending])

    • are you sure it's not packaged? :) You could check other debian based distributions, too.

It is best to create a chroot jail in which to build the application. This mitigates security and system corruption problems. In addition it ensures that any local changes to your machine will not interfere with the build.

If the package compiles, then it means you may have figured out all the dependencies. Don't worry, this will be checked later in a chroot environment. Try the application in a chroot environment (some things might be needed in the chroot jail - for example, proc may need to be mounted, sys to be mounted, etc.). Broken installation scripts are, unfortunately, very common and you probably don't want to run a test installation yet. You might prefer doing the tests in a qemu virtual machine in snapshot mode - changes are not permanent in snapshot mode and you can keep you development machine safe from malitious/broken makefiles.

''Debianization''

After the first compilation, it's time to create the Debian specific part of the package.

[http://www.debian.org/doc/maint-guide/ch-first.en.html#s-dh_make Debianize] the package by using [http://packages.debian.org/dh-make dh_make].

File debian/control: Add to the Build-Depends (sometimes even Build-Depends-Indep) the list of packages needed to be installed for the application to compile (remember the list done previously). You should leave out any packages that are listed in /usr/share/build-essential/essential-packages-list or /usr/share/build-essential/list and also leave out any packages that listed as dependencies by any of those packages. More detailed information cane be found on the page about [:PkgDevCtrl:control file creation for the new package].

File debian/rules: If any quirking was done then:

  • automate the quirking and the changes needed to be done in the debian/rules file under a patch target
  • make sure there will be an unpatch target that reverses all the changes done in the patch target
  • make the clean target depend on the unpatch target
  • make the build target depend on the patch target

Review each of the template files (debian/*.ex). If your package needs that feature, then customize the file as needed and rename it without the ".ex".

Delete all the unneeded templates. Don't worry, they can be restored at any time with "dh_make -a".

Make sure that all the directories you will place files in are listed in the debian/dirs file without a leading slash (/).

Make sure that the files are installed in the proper place (under a directory, not on the root system). Take care at the install target from the application makefile. If the application uses autoconf and automake, it may be enough to set the environment variable DESTDIR, e.g. "make DESTDIR=$(CURDIR)/debian/packagename". (dh_make will set this up automatically.)

Note: very often the upstream package will install files under /usr/local. DO NOT INSTALL ANY FILES IN THERE.

Initial compilation of the package

TODO: add notes

All tests in chroot

Why is it a good idea to use a chroot?

  • Security
  • Testing
  • No risk to break the developer's system
  • Wrongly installed packages can be identified easily (ls -lR in the root of the chroot before and after the build; diff -u before.list after.list)
  • Missing build dependecies are identified easier, thus avoiding serious [http://en.wikipedia.org/wiki/FTBFS FTBFS] (Fails To Build From Source) bugs

  • The chroot system is a pure Debian system belonging to one suite only (e.g., Sarge, Etch or Sid if the chroot was built properly with debootstrap or cdebootstrap)

Testing the package

licensecheck -r *

TODO: add notes

Lintian

Test all the packages with [http://packages.debian.org/lintian lintian].

lintian package-version.changes

Piuparts

Test all the .deb packages with [http://packages.debian.org/piuparts piuparts].

piuparts binpackage-version.deb

Check points for any package

This page is still incomplete; please help by adding information to it. Do not forget that the information here should be in a concise form.

Examples

  • The Oolite package was created following this techinque (actually, this page was written during oolite's initial packaging stage)
  • a somewhat simplistic example which assumes no upstream source when starting the package, can be found at [:PkgNew:Creating a new package from scratch] - this is more useful to upstream developers, not to people doing pure packaging work.

Advanced Packaging Procedures

Useful pages