Creating Debian packages

Creating digital signatures

Use GnuPG to digitally sign the packages. So, we will install it:

sudo apt-get install gnupg

When installation is complete, we must generate a set of public and private keys with which operates the mechanism of digital signature. So, we run into a terminal:

gpg --gen-key

The program will ask first about the algorithm used to generate the keys, we accept the default algorithm. The next question is the key length, and we continue to accept the default option. Then it asked the time during which these codes are valid. For practical purposes, 6 months or a year may be fine, but it is possible that other organizations or projects using different periods for security reasons. Then, the program asks some user data to record the identification of who signs: The name, aliases and a comment or an email address.

Finally, it asks a password that is used to sign. The password should ideally be long, combining upper and lower case.

You can also follow the official handbook, which will better explain each step and their alternatives GnuPG HOWTOs.

To see our keys list at any time, we can run the following command:

gpg --list-keys

Requirements for the creation of Debian packages

Perhaps many of these packages and you will find on your system depending on its importance:

  • dh-make
  • fakeroot
  • build-essential
  • debian-policy
  • developers-reference
  • dpkg-dev
  • devscripts
  • lintian
  • debchange

Creating Debian packages from source

In this section we will understand the contents of a Debian package, and how it creates step by step from our software project. In the next paragraphs, let us create a package using Ant, valid tool for Java projects, and creating a Debian package from the binary files (the creation of the last step process debianization from source, manually).

We can follow the textual explanation with a simple conceptual map:

descripcion

Step 1: Temporal copy and dh_make

To produce the package from source, we get a copy of the source code of our project in a temporary directory (eg /tmp/solbcn-1.0). The directory should follow the convention: [project-name]-[version] in lowercase. In the directory where is the copy of the source, we run the following command:

dh_make -c gpl -e user@mail.com -s --createorig

The tool dh_make add files with the extra information to produce the package into a directory debian in the current directory. The parameter -c indicates the type of license to use (the options are GPL, LGPL, among others). The user mail who produced the package is specified with the -e option. To sign the package we have used the -s.

The program leaves behind a debian directory with a set of files containing information of the package that should change, and in the top directory, a compressed file (with tar and gzip) with the contents of the directory before the debianization, a changes file and a extra file.

Step 2: Files debian directory

We'll show the changes to be made in the files created by the dh_make tool. The dh_make tool has created within the directory debian the following files, that we analyze step by step according to our project:

changelog
compat
control
copyright
cron.d.ex
dirs
docs
emacsen-install.ex
emacsen-remove.ex
emacsen-startup.ex
init.d.ex
init.d.lsb.ex
manpage.1.ex
manpage.sgml.ex
manpage.xml.ex
menu.ex
postinst.ex
postrm.ex
preinst.ex
prerm.ex
README.Debian
rules
watch.ex

There are files more important for the generation of the package. These files are as follows and will study it more carefully: control, changelog and rules, where it will have its own section.

Unnecessary files (to delete)

The entire list of the following files will be deleted:

  • cron.d.ex: This file only what we use in the event that our package needs to use cron. As our program does not need it, so, we can delete.
  • dirs: we must include the path of special directories that use our application
  • emacsen*: Files relating to Emacs, do not need them.
  • init.d*: In case you need or want that our program is started every time you reboot our PC.
  • README.Debian: It is a file notices of changes or special touches that were made when we debianizing the package. We do not need it
  • postinst.ex The script runs when we install the package.
  • postrm.ex: The script runs when we uninstall the package.
  • preinst.ex and prerm.ex: Are scripts that would run before installing and the uninstall package.
  • watch.ex: This file helps us to verify if there are updates to the package. For this task using a program called uscan. Once the file is edited, we have to rename from watch.ex to watch.

Quick changes to files

  • compat: it has relationship with the state debhelper compatibility, for example, suppose that this package is compatible with version 7 of debhelper, then, in this file we write the number 7.
  • menu.ex: Is the description of our application menu. In "section" is the path where you want to put the icon in the menu, in "title" the title of the application in the menu, in "command" should go the name to running the application, in the end we can tell the path where is the icon of the application. It is very important to rename the file from menu.ex to menu.
    ?package(solbcn):needs=X11 section=Apps/Graphics\
      title="solBCN" command="/opt/solBCN/solbcn"\
      icon="/usr/share/pixmaps/GEARS.png"
    
  • docs: The documentation files that we to include, for example: README, INSTALL, COPYING...
  • copyright: Every package must be accompanied by a verbatim copy of its copyright and distribution license in the file /usr/share/doc/package/copyright.

Man page

There are three files to create a man page:

  • manpage.1.ex
  • manpage.sgml.ex
  • manpage.xml.ex

These files are a template for creating a man page. You can write the man page with nroff or using others applications as sgml or xml. After we rename from manpage.* to package.1. The file name also includes ".1" as the first suffix, which means it's a manual page for a user command. See Man Pages from Debian New Maintainers' Guide.

Control file

The control file contains the most vital (and version-independent) information about the packages. The fields in the file are several and we can see exactly the description of each within the Debian Policy Documentation (Source package control files).

Our file content control would correspond to following text:

Source: solbcn
Section: free
Priority: extra
Maintainer: Alex Bravo <abravo@lsi.upc.edu>
Build-Depends: debhelper (>= 7), java2-runtime, junit, libcommons-cli-java
Standards-Version: 3.7.3
Homepage: http://floss.lsi.upc.edu/

Package: solbcn
Architecture: all
Depends: ${shlibs:Depends}, ${misc:Depends}, java2-runtime, libjdom1-java
Description: A constraint-based two dimensional geometric editor.
 solBCN is an experimental constraint-based 2D geometric editor
 based on the research of the Geometric Constraint Solving Group
 of the Universitat Polit├Ęcnica de Catalunya. 

The empty line between Hompepage and Package is very important!

Changelog file

Changes in the Debian version of the package should be briefly explained in the Debian changelog file debian/changelog. This includes modifications made in the Debian package compared to the upstream one as well as other changes and updates to the package.

The format of the debian/changelog allows the package building tools to discover which version of the package is being built and find out other release-specific information.

That format is a series of entries like this:

package (version) distribution(s); urgency=urgency
    [optional blank line(s), stripped]
* change details
 more change details
    [blank line(s), included in output of dpkg-parsechangelog]
* even more change details
    [optional blank line(s), stripped]
-- maintainer name <email address>[two spaces]  date

For more information, see Debian Changelog.

Rules file

The file debian/rules is actually a makefile (a file with instructions for GNU Make), which follows a certain pattern of commands that correspond to a large number of tasks performed by installing a software package in our system: from installing the documentation (man pages...) install icons in the applications menu, install libraries... This file will use our Makefile to create a template of the main functions:

  • Build
  • Clean
  • Install

We will make specific changes, to the file debian/rules can be accessed properly to each of our targets in Makefile, for example, dh_make will not find any target called "build", so, it will leave a blank space for us complete with the correct objective , which in our case is jar. The most important part of our file, has the following contents:

build: build-stamp

build-stamp: configure-stamp  
	dh_testdir

	# Add here commands to compile the package.
	$(MAKE) jar
	#docbook-to-man debian/solbcn.sgml > solbcn.1

	touch $@

clean: 
	dh_testdir
	dh_testroot
	rm -f build-stamp configure-stamp

	# Add here commands to clean up after the build process.
	$(MAKE) clean

	dh_clean 

install: build
	dh_testdir
	dh_testroot
	dh_clean -k 
	dh_installdirs

	# Add here commands to install the package into debian/solbcn.
	$(MAKE) DESTDIR=$(CURDIR)/debian/solbcn install

We can see the three targets that will conduct the file debian/rules, entering our Makefile.

Desktop file

Now let's create the shortcut for our program is run from a graphical menu. We create a .desktop file and it will be installed in /usr/share/applications. Then, the content of the file would be the following :

[Desktop Entry]
Encoding=UTF-8
Name=solBCN
Comment=A constraint-based two dimensional geometric graphical editor
Exec=/opt/solBCN/solbcn
Icon=GEARS.png
Terminal=false
Type=Application
Categories=Application;Graphics;
StartupNotify=true

Name is the name of the program, Comment is the comment of it, Exec is the path to the executable program, Icon is the path to the icon that you assign to our program by default, Terminal is where we specify whether by terminal opens or not (false / true, is a Boolean value). Type where we want it to appear on the menu, in this case in Applications. Categories where we want to display our icon in the menu defined in Type. See Free Desktop Policy.

Step 3: Creating package!

To produce the package signed, we need the short ID of the digital signature and we execute the following command:

dpkg-buildpackage -sgpg -kXXXXXXXX -rfakeroot

The options are used to use signature -sgpg GnuPG. The option -k is the identifier of the key to use. To create the packages is required to emulate root user, for which the tool is used fakeroot.

The process to create the file packet may take a little time and write a large amount of text on the screen. Finally, if no errors in construction, it will ask the password used to create our GnuPG keys to be able to sign some files that are part of the package.

Step 4: Valid packaging with lintian

After so much work, you may have missed a step, some information, or in general, minor errors that make the package does not conform to the policies and conventions for the installation of Software Debian.

To check the compliance of our software packages with these restrictions and conventions, we will use the herramnienta lintian, which performs these tasks and report errors and warnings that contain our packages.


Creating Debian packages with Ant and CDBS from Java source

Ant is the alternative to GNUMake in Java. The syntax of the Makefiles is very complicated and very easy to fall into errors difficult to detect.Ant uses an XML file (build.xml) with the same idea that a Makefile, set objectives and dependencies: compile, clean files, create Jar files...

In essence, the Common Debian Build System attempts to provide a modular yet very powerful build system for Debian packages. You can use it to create a build system for typical GNU autotools packages in 4 lines, or you can just reuse the CDBS core to implement your own build systems.

Step 1: Temporal copy and dh_make

To produce the package from source, we get a copy of the source code of our project in a temporary directory (eg /tmp/solbcn-1.0). The directory should follow the convention: [project-name]-[version] in lowercase. In the directory where is the copy of the source, we run the following command:

dh_make -c gpl -e user@mail.com -s --createorig

Step 2: Files DEBIAN directory

We'll show the changes to be made in the files created by the dh_make tool. All files are the same as in the previous paragraph, except the rules file, that it is different because now we will use Ant and CDBS.

Rules file

Thanks to Ant and CDBS this file is easier to create. We write the new directories where our application will be installed and copy all the files needed. The contents of the file is as follows:

#!/usr/bin/make -f

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/ant.mk

JAVA_HOME := /usr/lib/jvm/java-6-openjdk
ANT_HOME := /usr/share/ant

install/solbcn::
	install -d $(DEB_FINALDIR)/usr/bin
	install -d $(DEB_FINALDIR)/opt/solbcn
	install -d $(DEB_FINALDIR)/opt/solbcn/lib
	install -m 755 $(CURDIR)/solbcn /usr/bin/
	install -m 755 $(CURDIR)/solbcn /opt/solbcn/
	install -m 755 $(CURDIR)/classes/solBCN/xUI/view/img/GEARS.gif /opt/solbcn/GEARS.gif
	install -m 755 $(CURDIR)/debian/bin/solbcn.desktop /usr/share/applications/solbcn.desktop
	install -m 644 $(CURDIR)/lib/solBCN.jar /opt/solbcn/lib/solBCN.jar

The first two lines are very important in this process. The line where is incluied ant.mk gives instructions for perform certain tasks with Ant and the build.xml file which should take my Java project. Later, we will speak of the build.xml file.

include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/ant.mk

These variables are necessary, and will only be used at the time of packaging, so, we have to customize them to our system.

JAVA_HOME := /usr/lib/jvm/java-6-openjdk
ANT_HOME := /usr/share/ant

These instructions indicate the directories creation, where our application will be installed. The election, as we have previously explained, the application has been installed in /opt.

install -d $(DEB_FINALDIR)/usr/bin
install -d $(DEB_FINALDIR)/opt/solbcn
install -d $(DEB_FINALDIR)/opt/solbcn/lib

They are all files that are going to copy the installation directory:

  • The solbcn shell
  • The icon application GEARS.gif
  • The desktop file
  • The source in a Jar file
  • The JSAP library
install -m 755 $(CURDIR)/solbcn /usr/bin/
install -m 755 $(CURDIR)/solbcn /opt/solbcn/
install -m 755 $(CURDIR)/classes/solBCN/xUI/view/img/GEARS.gif /opt/solbcn/GEARS.gif
install -m 755 $(CURDIR)/debian/bin/solbcn.desktop /usr/share/applications/solbcn.desktop
install -m 644 $(CURDIR)/lib/solBCN.jar /opt/solbcn/lib/solBCN.jar
install -m 644 $(CURDIR)/lib/JSAP-2.0.jar /opt/solbcn/lib/JSAP-2.0.jar

Step 3: Creating Build.xml file (the other Makefile) and creating package

This file is the "Makefile" which used implementation Ant to compile and create to source code package. This file must to be in the root directoy from the proyect. This file has 3 rules:

  • Clean
  • Compile
  • Jar
<?xml version="1.0" encoding="UTF-8"?>
<project name="solBCN" default="jar">

   <property name="src" value="src"/>

   <target name="clean">
       <delete dir="classes" failonerror="false"/>
   </target>

   <target name="compile">
     <mkdir dir="classes"/>
     <javac srcdir="src" destdir="classes">
	<classpath>
		<!-- download from -->
		<!-- http://downloads.sourceforge.net/sourceforge/jsap/JSAP-2.1.jar -->
		<pathelement location="lib/JSAP-2.1.jar"/>
		<!--
		install with
		$ apt-get install libjdom1-java junit libcommons-cli-java libcommons-lang-java
		 -->
		<pathelement location="/usr/share/java/jdom1.jar"/>
		<pathelement location="/usr/share/java/junit.jar"/>
		<pathelement location="/usr/share/java/commons-cli.jar"/>
		<pathelement location="/usr/share/java/commons-lang.jar"/>
	</classpath>
     </javac>

     <!-- images copy -->
     <mkdir dir="classes/solBCN/xUI/view/img"/>
     <copy todir="classes/solBCN/xUI/view/img">
         <fileset dir="src/solBCN/xUI/view/img" includes="*.gif"/>
     </copy>
   </target>

   <target name="jar" depends="clean,compile">
     <mkdir dir="lib"/>
     <jar jarfile="lib/solBCN.jar" basedir="classes" compress="true">
         <fileset dir="classes"/>
         <manifest>
             <attribute name="Main-Class" value="solBCN.xUI.XUIFrame"/>
         </manifest>
      </jar>
    </target>

</project>

We clearly see the different parts of the targets, are encapsulated as follows (for example in jar tatget):

<target name="jar" depends="clean,compile">
   ...
</target>

To create the objective Jar, we depend on a clean and compile a project, because ANT does not resolve dependencies of the project.

To produce the package signed, we need the short ID of the digital signature and we execute the following command:

dpkg-buildpackage -sgpg -kXXXXXXXX -rfakeroot

Step 4: Valid packaging with lintian

After so much work, you may have missed a step, some information, or in general, minor errors that make the package does not conform to the policies and conventions for the installation of Software Debian.

To check the compliance of our software packages with these restrictions and conventions, we will use the lintian tool, which performs these tasks and report errors and warnings that contain our packages.


Creating Debian packages from binaries files

Let's give a quick instructions set, in order to create a Debian package from compiled code (in my case a set of *.class files scattered in differents Jar packages).

If you look at the conceptual map attached on this page, what will we do in this section is to make the yellow-green part. This part makes it automatically with dpkg tool,but on the basis of source files. Now we already have compiled the source files and we are going to mount the directory tree of the last part manually, to be able to generate our package.

Step1: Creating directories

To begin to make a debian package, we first have to create an organization of directories.

First, we create a different directory to the working directory named for example Packages, and within a new directory with a name that refers to our project, for example solbcnProject. In this case we would have:

/home/username/Packages/solbcnProject

Now we go into the directory solbcnProject and create the set of directories where our program will to be installed. In Debian we have two directories possible to install programs:

  • /usr/share
  • /opt

We have chosen the second option, because our package was not found in any official Debian repository, so within the solbcnProject directory, we will create a new one called opt:

/home/username/Packages/solbcnProject/opt

Entered into the opt directory and we copy the work directory of all our project. In our case, copy the solbcn directory:

/home/username/Packages/solbcnProject/opt/solbcn

Now we will go to the directory solbcnProject to create a new directory called DEBIAN (is very important that is written in uppercase). And now we would have something like this:

/home/username/Packages/solbcnProject/opt
/home/username/Packages/solbcnProject/opt/DEBIAN

The directory DEBIAN is very important because it will contain the files necessary for the creation of a debian package.

If we look, we see that solbcnProject is the debian folder that we had in the first section within the directory solbcn-1.0.

Step 2: Files DEBIAN directory

Control file

The control file contains the most vital (and version-independent) information about the packages. The fields in the file are several and we can see exactly the description of each within the Debian Policy Documentation (Binary package control files).

Our control file would be as follows:

Package: solbcn
Version: 1.0
Architecture: all
Maintainer: Alex Bravo <abravo@lsi.upc.edu>
Installed-Size: 840
Depends: java2-runtime, libjdom1-java
Section: free
Priority: extra
Homepage: http://floss.lsi.upc.edu/
Description: A constraint-based two dimensional geometric editor.
 solBCN is an experimental constraint-based 2D geometric editor
 based on the research of the Geometric Constraint Solving Group
 of the Universitat Politecnica de Catalunya.

md5sums file

The creation of this file will be explained later, because it is necessary to create it at the end of everything, before the creation of the Debian package, in Creating package! section.

Desktop file

Now let's create the shortcut for our program is run from a graphical menu, in our case for Gnome. To do so will create the path /usr/share/applications within the directory solbcnProject. Then we would have the following three path:

/home/username/Packages/solbcnProject/opt
/home/username/Packages/solbcnProject/opt/DEBIAN
/home/username/Packages/solbcnProject/usr/share/applications

Within the third path will create a new file called programname.desktop, in our case solbcn.desktop. See the content in Debian file section from Creating Debian packages from source

Step 3: Creating package!

Now we must create the file md5sum. For that we open a terminal, we move to correct path (/home/username/Packages/solbcnProject), and run the following command:

find . -type f -print0 | xargs -0 md5sum > md5sums

Now we open md5sums file and do the following:

  1. Delete the lines that refer to the md5sums file and DEBIAN directory.
  1. Replace the ./ By / and what we save. Finally move to the folder DEBIAN.
  1. And the final step, creating the deb package with the tools dpkg and fakeroot.
fakeroot dpkg-deb -b package_path_to_create package_path_to_save/name_package.deb

In our case:

fakeroot dpkg-deb -b /home/username/Packages/solbcnProject /home/username/Packages/solbcnProject/solBCN_1.0_all.deb

The dpkg instruction should be done without root permissions, the -b option is an abbreviation of build so that we build the package. If we put -i installed.

Step 4: Valid packaging with lintian

After so much work, you may have missed a step, some information, or in general, minor errors that make the package does not conform to the policies and conventions for the installation of Software Debian.

To check the compliance of our software packages with these restrictions and conventions, we will use the lintian tool, which performs these tasks and report errors and warnings that contain our packages.


References

Attachments