||<>|| == Creating a Source Package using debhelper == Though there are different ways to create a package for Ubuntu, this article is meant as an intro guide to get the novice packager up and running as soon as possible. As such, the most common packaging method using debhelper tools will be discussed. Please note that the term "Source Package" does not imply any actual source code is being shipped with the product. A Source Package simply builds one or more Binary Packages. That is the process that will be explained here. Before we start, there are some prerequisites that need addressing. First, the environment variables DEBFULLNAME and DEBEMAIL should be set. You can place these in your ~/.bashrc file as such: {{{ DEBFULLNAME='John Smith' DEBEMAIL='foo@bar.com'}}} Next, be sure to install the following packages: {{{ debhelper build-essential lintian fakeroot gnupg dh-make}}} 'Package development often requires installing many packages (especially -dev packages containing headers and other common development files) that are not part of a normal desktop Ubuntu installation. If you want to avoid installing extra packages or would like to develop for a different Ubuntu release (the development one, for instance) from what you currently have, the use of a chroot environment is highly recommended. That topic is beyond the scope of this article, but two popular tools are [[http://www.netfort.gr.jp/~dancer/software/pbuilder-doc/pbuilder-doc.html|pbuilder]] and [[http://julien.danjou.info/buildd.html|sbuild]]''' Let's now jump right in and get our hands dirty. In this example we will be using the GNU {{{hello}}} program as our example. You can download the source tarball from [[http://ftp.gnu.org/gnu/hello/hello-2.1.1.tar.gz|ftp.gnu.org]]. For the purposes of this example, we will be using the {{{~/hello/}}} directory. {{{ mkdir ~/hello cd ~/hello wget http://ftp.gnu.org/gnu/hello/hello-2.1.1.tar.gz}}} After downloading the file, you will need to make a copy of the original (sometimes called "upstream") tarball in the following format: {{{_.orig.tar.gz}}}. {{{ cp hello-2.1.1.tar.gz hello_2.1.1.orig.tar.gz tar -xzvf hello_2.1.1.orig.tar.gz}}} ''The underscore, "_", between the package name (hello) and the version (2.1.1), as opposed to a hyphen, "-", is very important. Your source package will incorrectly be built as a Debian native package.'' We now have a {{{hello-2.1.1}}} directory containing the source files. Now we need to create the customary {{{debian}}} directory where all the packaging information is stored, allowing us to separate the packaging files from the application source files. {{{ cd hello-2.1.1 dh_make}}} dh_make is a handy utility which creates a templatized debian directory automatically. It creates the required packaging files (rules, control, copyright, etc...) as well as provides example files (postinst.ex, preinst.ex, etc...) for other, optional packaging files. For {{{hello}}}, you will not need some of the files created by dh_make in the {{{debian}}} directory: * {{{README.Debian}}}: the README file for specific Debian issues, not the program's README. * {{{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. At this point, you should have only {{{changelog}}}, {{{compat}}}, {{{control}}}, {{{copyright}}}, and {{{rules}}} files in the {{{debian}}} directory. === changelog === You will need to adjust the {{{changelog}}} slightly in this case to reflect that this package is named {{{hello-debhelper}}} rather than just {{{hello}}}: {{{ hello-debhelper (2.1.1-1) edgy; urgency=low * Initial release -- Captain Packager Thu, 6 Apr 2006 10:07:19 -0700}}} === control === By using {{{debhelper}}}, the only things we need to change in {{{control}}} are the name (substituting {{{hello}}} for {{{hello-debhelper}}}) and adding {{{debhelper (>= 4.0.0)}}} to the ''Build-Depends'' field for the source package. The Ubuntu package for {{{hello-debhelper}}} looks like: {{{ Source: hello-debhelper Section: devel Priority: extra Maintainer: Capitan Packager Standards-Version: 3.6.1 Build-Depends: debhelper (>= 4) Package: hello-debhelper Architecture: any Depends: ${shlibs:Depends} Conflicts: hello Provides: hello Replaces: hello 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). . This is the same as the hello package, except it uses debhelper to make the deb. Please see debhelper as to what it is. }}} === rules === In order to be less verbose in this section, please take the time to download an already finished version of this package for reference. {{{ apt-get source hello-debhelper }}} We can copy the {{{copyright}}} file and the {{{postinst}}} and {{{prerm}}} scripts from the Ubuntu {{{hello-debhelper}}} package just downloaded. More information concerning the copyright can be viewed below, while information regarding the {{{postinst}}} and {{{postrm}}} scripts can be found in the section "Maintainer Scripts". We will also copy the {{{rules}}} file so we can inspect it. {{{ cp ../../ubuntu/hello-debhelper-2.1.1/debian/copyright . cp ../../ubuntu/hello-debhelper-2.1.1/debian/postinst . cp ../../ubuntu/hello-debhelper-2.1.1/debian/prerm . cp ../../ubuntu/hello-debhelper-2.1.1/debian/rules .}}} The last file we need to look at is {{{rules}}}, where the power of {{{debhelper}}} scripts can be seen. The {{{rules}}} file looks like this: {{{ #!/usr/bin/make -f package = hello-debhelper 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 # There are no architecture-independent files to be uploaded # generated by this package. If there were any they would be # made here. 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 }}} Notice that tasks like testing if you are in the right directory ({{{dh_testdir}}}), making sure you are building the package with root privileges ({{{dh_testroot}}}), installing documentation ({{{dh_installdocs}}} and {{{dh_installchangelogs}}}), and cleaning up after the build ({{{dh_clean}}}) are handled automatically. Many packages much more complicated than {{{hello}}} have {{{rules}}} files no bigger because the {{{debhelper}}} scripts handle most of the tasks. For a complete list of {{{debhelper}}} scripts, please see the section called “List of debhelper scripts”. They are also well documented in their respective {{{man}}} pages. It is a useful exercise to read the man page (they are well written and not lengthy) for each helper script used in the above {{{rules}}} file. === compat === The compat file is automatically generated by dh_make and basically lists the version of debhelper used when the package was created. It can normally just be left alone. === copyright === This file gives the copyright information. It is also helpful if copyright information is found in the {{{COPYING}}} file in the program's source directory. This file should include such information as the names of the author and the packager, the URL from which the source came, a Copyright line with the year and copyright holder, and the text of the copyright itself. '{{{source}}} does not necessarily mean "source code", but rather the contents of the orig tarball.' === Building the Source Package === Now that we have gone through the files in the {{{debian}}} directory for {{{hello-debhelper}}}, we can build the source (and binary) packages. First, let us move back into the source directory: {{{cd ..}}} Now we build the source package using {{{debuild}}}, a wrapper script for {{{dpkg-buildpackage}}}: {{{debuild -S}}} the binary package, using {{{pbuilder}}}: {{{sudo pbuilder build ../*.dsc}}} and finally check the source package for common mistakes using {{{lintian}}}: {{{ cd .. lintian -i *.dsc}}} <> == Common Mistakes == === dh_make Example Files === When you use dh_make to create the initial "debianization", example files for various tasks are created in the {{{debian/}}} directory. The templates have a .ex extension. If you want to use one, rename it to remove the extension. If you do not need it, remove it to keep the {{{debian/}}} directory clean. <> === Copyright Information === These points are critical to inform users of the copyrighted materials contained in the packages you have uploaded to the commercial repository. * The upstream tarball must contain verbatim copies of all licenses that are used by the files in the tarball. * For all files it must be clear under which license they fall. Source code files should usually have a short comment at the top which points out the license. Common errors: * Not shipping a copy of the LGPL when e. g. the build system is under LGPL * Documentation is actually under GFDL, but `debian/copyright` does not mention it. As of gutsy, the GFDL is in `/usr/share/common-licenses/`, so a pointer there is sufficient for `debian/copyright`. * `debian/copyright` only mentions a license, but no copyright * The source files and/or `debian/copyright` are not clear about which files fall under which license == TODO == * Wikify all debhelper script manpages with editmoin and augment where needed * Create a page describing maintainer scripts ---- CategoryLookMergeDelete