Differences between revisions 16 and 17
Revision 16 as of 2006-08-15 12:27:09
Size: 7289
Editor: ?JamesVanZandt
Comment:
Revision 17 as of 2006-12-16 21:37:46
Size: 7305
Comment: English fixes, typos. formatting.
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
This HowTo It is also intended to show that ''Debian packaging is not that hard''. This HowTo is also intended to show that ''Debian packaging is not that hard''.
Line 8: Line 8:
= Contents = === Contents ===
Line 12: Line 12:
=== Why does this page even exist? ===
Line 13: Line 14:
= 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 16:
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 the people that prefer a more pragmatic approach to problems, this HowTo will focus on '''a pragmatic approach on learning how to create Debian packages'''. === Creating the package ===
Line 17: Line 18:
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]
Line 18: Line 20:
= Creating the package = If you want to create an official 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].
Line 20: Line 22:
''If the information below seems scarce, please look in the [http://www.debian.org/doc/maint-guide/ New Maintainer's Guide] and in the [http://www.debian.org/doc/debian-policy/ Debian Policy].''

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

== Initial compilation ==
==== Initial compilation ====
Line 29: Line 27:
  * write down every package you had to install so the package compiled, including those that were already installed on your system (will be added to build dependency; note that objdump -p | grep NEEDED will show exactly the needed libs, the package should depend on all of packages of those libraries)
  * write down quirks and tricks needed for the package to compile (files missing, file modifications, etc.)
  * if you think you need something not packages, make sure that:
  * note every package you had to install so the package compiled, including those that were already installed on your system (will be added to build dependency; note that objdump -p | grep NEEDED will show exactly the needed libs the package should depend on all of packages of those libraries)
   * note quirks and tricks needed for the package to compile (files missing, file modifications, etc.)
 * if you think you need something not packaged, make sure that:
Line 34: Line 32:
   * are you sure it is not packaged? :-)    * are you sure it's not packaged? :-)
Line 36: Line 34:
Note: It is best to create a chroot in which the application shall be built. This could avoid various security and system corruption problems. Additionally, it ensure that any local changes to your machine don't interfere with the build. Note: It is best to create a chroot in which the application will be built. This helps avoid various security and system corruption problems. Additionally, it ensures that any local changes to your machine don't interfere with the build.
Line 38: Line 36:
If the package compiles then it means you '''might''' 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 - proc to be mounted, sys to be mounted). If the package compiles, then it means you '''might''' 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 - proc to be mounted, sys to be mounted).
Line 46: Line 44:
== Debianization == ==== ''Debianization'' ====
Line 48: Line 46:
After the first compilation it is time to create the debian specific part of the package. After the first compilation, it's time to create the Debian specific part of the package.
Line 64: Line 62:
Make sure that in 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. 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.
Line 66: Line 64:
Note: very often the package will be installed under /usr/local. '''DO NOT INSTALL ANY FILES IN THERE'''. Note: very often the upstream package will be installed under /usr/local. '''DO NOT INSTALL ANY FILES IN THERE'''.
Line 68: Line 66:
== Initial compilation of the package == ==== Initial compilation of the package ====
Line 72: Line 70:
=== All tests in chroot === ==== All tests in chroot ====
Line 79: Line 77:
 * missing build dependecies are identified easier, thus avoiding serious [http://en.wikipedia.org/wiki/FTBFS FTBFS] bugs
 * the chroot system is a pure Debian system belonging to one suite only (e.g., Sarge, Etch or Sid if the chroot was build properly with debootstrap or cdebootstrap)
 * 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)
Line 82: Line 80:
== Testing the package == ==== Testing the package ====
Line 86: Line 84:
=== Linda === ==== Linda ====
Line 92: Line 90:
=== Lintian === ==== Lintian ====
Line 98: Line 96:
=== Piuparts === ==== Piuparts ====
Line 104: Line 102:
== Check points for any package == ==== Check points for any package ====
Line 106: Line 104:
 * 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 usualy don't need this) Does it have a .desktop file?
 * 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?
Line 109: Line 107:
 * Does the package compile cleanly? (this does '''not''' mean that you should redirect the errors to /dev/null and doing so will bring problems)  * Does the package compile cleanly? This does '''not''' mean that you should redirect the errors to /dev/null
Line 116: Line 114:

''This page is still incomplete; please help completing it by adding information to it. Do not forget that the information here should be in a concise form.''
''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.''
Line 121: Line 118:
= Advanced Packaging Procedures = === Advanced Packaging Procedures ===
Line 129: Line 126:
= External useful links = === External useful links ===

Introduction

This page is intended to gather a pragmatic and simplistic guide to creating a simple Debian package.

This ?HowTo is also 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?

Contents

?TableOfContents([1])

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.

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 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

Steps:

  • try to compile the package (do not install) - can be done on your system, but is preferably done in a chroot (e.g., pbuilder or sbuild)
    • note every package you had to install so the package compiled, including those that were already installed on your system (will be added to build dependency; note that objdump -p | grep NEEDED will show exactly the needed libs the package should depend on all of packages of those libraries)
    • note quirks and tricks needed for the package to compile (files missing, file modifications, etc.)
  • if you think you need something not packaged, make sure that:

Note: It is best to create a chroot in which the application will be built. This helps avoid various security and system corruption problems. Additionally, it ensures that any local changes to your machine don't interfere with the build.

If the package compiles, then it means you might 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 - proc to be mounted, sys to be mounted).

DO NOT run make install, unless you are absolutely sure. Broken installation scripts are, unfortunetely, very common and you probably don't want to run a test installation yet.

Note: running make on a system can sometimes be a security risk! It is a good idea to check that the Makefile does not contain funny stuff. Obscure applications might rarely fall into this case.

''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 previousely). 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.

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

Delete all the unneeded templates. Don't worry, copies are present on the system and can be copied and modified at any time later.

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.

Note: very often the upstream package will be installed 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

TODO: add notes

Linda

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

linda package-version.changes

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.

Notes: [20060410] EddyPetrisor is working on this; an initial complete page should be ready asap.

Advanced Packaging Procedures