HOWTO create package

You'll find in this document a few notes about packaging in debian. For my first package, I didn't find the official Maintainer's Guide useful so I decided to write down here my tips.

If you have some suggestions or if you see that I'm in the wrong way, please feel free to send an e-mail to pam+deb@nospam.mouraf.org (please erase 'nospam.')

First step

You have to create the orig tarball file:

dhmake -e pam+deb@nospam.mouraf.org -f ../PACKAGENAME-version.tar.gz

Files needed

The needed files are control, copyright, changelog and rules.

Here are my drafts:

control: nothing special to say. The architecture of the file can be found here: http://www.debian.org/doc/maint-guide/ch-dreq.en.html#s-control

copyright:

This package was debianized by Pierre-Alexandre Meyer <pam+deb@nospam.mouraf.org> on DATE.

It was downloaded from URL

Upstream Author: NAME + ADDRESS

Copyright: SEE PACKAGE

License:

You are free to distribute this software under the terms of
the GNU General Public License.
On Debian systems, the complete text of the GNU General Public
License can be found in the file `/usr/share/common-licenses/GPL'.

The Debian packaging is (C) 2006, Pierre-Alexandre Meyer <pam+deb@nospam.mouraf.org>
and is licensed under the GPL, see `/usr/share/common-licenses/GPL'.

IAOI it's under GPL licenses of course...

rules: dh_install moves itself files and directories you specify in the PACKAGENAME.install file. If you want to move directories site/ and install/ in /usr/share/PACKAGENAME for example, just add in PACKAGENAME.install file:

site/ install/ usr/share/PACKAGENAME

TODO: is it in the build directory? Why I have a debian/PACKAGENAME/... clone?

Debconf

Debconf is used to create ncurses to perform a kikoolol installation. You can use it too in the postinst, postrm scripts.

Please have a look to Debian's Tips here.

First of all you have to create a PACKAGENAME.templates file in which you put you questions, descriptions, infos dialogs, etc.

Example:

Template: PACKAGENAME/NAME_OF_THE_QUESTION
Type: select
Choices: Apache, Apache-SSL, Apache2, All, None
Default: Apache
Description: webserver type
 Which kind of web server should be used by PACKAGENAME?
 .
 Select "None" if you would like to configure your webserver by hand.

Here are the possibles types:

Type	Description
string	Holds any arbitrary string of data.
boolean	Holds "`true`" or "`false`".
select	Holds one of a finite number of possible values. These values must be specified in a field named `Choices:`. Separate the possible values with commas and spaces, like this: `Choices: yes, no, maybe`
multiselect	Just like the select data type, except the user can choose any number of items from the list. This means that the `Default:` field and the actual value of the question may be a comma and space delimited list of values, just like the `Choices:` field. Note: For compatability with old versions of Debconf, if you use this data type, please make your package depend on `debconf (>= 0.2.26)`
note	This template is a note that can be displayed to the user. As opposed to text, it is something important, that the user really should see. If debconf is not running interactively, it might be saved to a log file or mailbox for them to see later.
text	This template is a scrap of text that can be displayed to the user. It's intended to be used for mostly cosmetic reasons, touching up around other questions that are asked at the same time. Unlike a note, it isn't treated as something the user should definitely see. Less complex frontends may refuse to ever display this type of element.
password	Holds a password. Use with caution. Be aware that the password the user enters will be written to debconf's database. You should consider clearing that value out of the database as soon as is possible.

Secondly you have to tell how do you want to display your questions. Simply create a PACKAGENAME.config file. You can also add it to the postrm, postinst, etc. files. Here's the basic:

#!/bin/sh

## Source debconf library
. /usr/share/debconf/confmodule


# Which web-server should I use?
db_input high PACKAGENAME/NAME_OF_THE_QUESTION || true


db_go || true

exit 0

You can specify a lot of parameters (prority, ...). See the man: WTF? Where I found it?

Finally add dh_installdebconf in the rules file (section: binary-arch, after dh_install(changelogs|docs|examples|man)).

po-debconf

TODO!

dbconfig-common

If you use *sql tables, everything is already done to configure it, thanks to dbconfig-common. It's better to use it 'cause it knows what to do if you purge, remove, reinstall, etc. the package.

First of all you have to prompt for variables (db server, db user, etc.). So you have to modify your postinst, prerm and postrm files. The example below will also generate a file (debian.php) where the variables will be stored (to be used in the PACKAGENAME.config file for example):

#!/bin/sh
# postinst maintainer script for PACKAGENAME

# source debconf stuff
. /usr/share/debconf/confmodule
db_version 2.0

# source dbconfig-common stuff
. /usr/share/dbconfig-common/dpkg/postinst.mysql

dbc_first_version="FIRST VERSION OF THE PACKAGE USING DBCONFIG"
dbc_generate_include="php:/etc/PACKAGENAME/debian.php"
dbc_generate_include_owner="root:www-data"
dbc_generate_include_perms="0640"
dbc_generate_include_args="--dbname=dbname --dbpass=dbpasswd 
--dbuser=username --dbserver=hostname"

dbc_go PACKAGENAME $@
# done with debconf...
db_stop

exit 0

And here's for the prerm file:

#!/bin/sh

# source debconf stuff
. /usr/share/debconf/confmodule
# source dbconfig-common stuff
. /usr/share/dbconfig-common/dpkg/prerm.mysql
dbc_go PACKAGENAME $@
# done with debconf...
db_stop
exit 0

and for the postrm file:

#!/bin/sh
# postrm maintainer script for PACKAGENAME

# source debconf stuff
. /usr/share/debconf/confmodule
# source dbconfig-common stuff
. /usr/share/dbconfig-common/dpkg/postrm.mysql
dbc_go PACKAGENAME $@
exit 0

You see, it's very easy to use! Everything is already done!

If you want to use variables in the config file:

#!/bin/sh

## Source debconf library
. /usr/share/debconf/confmodule
# Source dbconfig-common stuff
. /usr/share/dbconfig-common/dpkg/config.mysql

dbc_first_version="FIRST VERSION"
dbc_load_include="php:/etc/PACKAGENAME/debian.php"
dbc_load_include_args="--dbname=database_default --dbpass=database_password
--dbuser=database_username --dbserver=database_hostname"
dbc_go PACKAGENAME $@

# Here you can use variables created by the postinst script 
# and stored in the /etc/PACKAGENAME/debian.php file.

db_go || true

exit 0

Note that debconf everywhere IS needed! You have also to add dbconfig-common and debconf to the depends variable in the control file.

The dbc_load_include is the file which will be created (see the postinst script) and in which will be stored dbname, dbpass, dbuser and dbserver variables. dbconfig-common will automatically generate debconf-prompts for each variable. Script language for the file debian.php here is PHP but you can modify it if you want other syntax for your scripts. For languages and variables, have a look to this little HOWTO: http://people.debian.org/~seanius/policy/examples/dbconfig-common/doc/dbconfig-common-using.html.

The following table lists the variables you can hint in your config script, as well as some other variables you can use to have a finer level of control over dbconfig-common. You must use these variables exactly (and only) where directed in this table.

variable name	location(s) specified	purpose	default value
dbc_dbuser	config	name to use when connecting to database	package name
dbc_dbname	config	name of database resource to which to connect	package name
dbc_dbtypes	config	database types supported by the package	empty
dbc_generate_include	postinst	format:outputfile pair for an extra config to be generated by dbconfig-generate-include.	empty
dbc_generate_include_owner	postinst	set the owner:group of include files generated by dbconfig-generate-include	empty
dbc_generate_include_perms	postinst	set the permissions of include files generated by dbconfig-generate-include	empty
dbc_generate_include_args	postinst	arguments passed directly to dbconfig-generate-include	empty
dbc_first_version	config,postinst	the first version in which dbconfig-common was introduced in the package	empty
dbc_load_include	config	format:includefile pair for a config to be read in by dbconfig-load-include	empty
dbc_load_include_args	config	arguments passed directly to dbconfig-load-include	empty

So, you have your database, user and password. You need now to create TABLES and fill it for your program. Simply create a PACKAGENAME.sql script in the root directory of the source and add to the rules file (after the dh_install):

# place the sql script where dbconfig-common wants it
cp PACKAGENAME.sql debian/PACKAGENAME/usr/share/dbconfig-common/data/PACKAGENAME/install/(my|postgre)sql

Finally don't forget to run dh_installdebconf in the rules file and (??? TODO see above ???) usr/share/dbconfig-common/data/PACKAGENAME/install/mysql to you PACKAGENAME.dirs. Simply source the debian.php in your script if the informatios are needed.

Build the package

Simply use the command dpkg-buildpackage -rfakeroot.

Debian

HOWTO create package

Contents

First step

Files needed

Debconf

po-debconf

dbconfig-common

variable name

location(s) specified

purpose

default value

Build the package