TL;DR
This blog post will cover some basics about debian package names and version strings, and how to build debian packaging boilerplate using dh_make
to streamline the creation of packages.
Install the packaging essentials
$ sudo apt-get install build-essential dh-make
Understanding the package name and version
Let’s assume we have an upstream source with the archive name of newprogram-0.12.7.tar.gz
. We’ll use newprogram
as the package name and 0.12.7
as the upstream version.
It’s important to remember the following about package names:
- Consists of only lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.)
- Must be at least two (2) characters long
- Must start with an alphanumeric character
- Recommended to be less than 30 characters, if possible.
and upstream versions:
- Must start with a digit (0-9)
- Must consist only of alphanumeric characters (0-9A-Za-z), plus signs (+), tildes (~) and periods (.)
- Recommended to be less than 8 characters, if possible.
If an upstream version does not use a versioning scheme recognized by the deb toolchain (i.e 0.12.7
), remove the invalid values from the upstream version. These removed values can be recorded in the debian/changelog
file. If you need to create a version string, use the YYYYMMDD format (i.e 20150713).
Setting up dh_make
Create the $DEBEMAIL
and $DEBFULLNAME
shell environment variables. These will be used to generate values in control and changelog entries.
$ cat >>~/.bashrc <<EOF
DEBEMAIL="person@company.tld"
DEBFULLNAME="Testy McTester"
export DEBEMAIL DEBFULLNAME
EOF
$ . ~/.bashrc
Setting up the directory structure
1) Create the top-level directory and then change directory into the new folder:
$ mkdir newprogram; cd newprogram/
2) Retreive and unpack upstream source:
$ wget https://example.org/newprogram-0.12.7.tar.gz
$ tar -xvzf newprogram-0.12.7.tar.gz
3) Change into the unpacked directory:
$ cd newprogram-0.12.7/
Create the initial package using the original source archive
From inside the unpacked source directory (i.e. ./newprogram-0.12.7
), run the following:
$ dh_make -f ../newprogram-0.12.7.tar.gz
The -f
flag sets the filepath
as the original (newprogram_0.12.7.orig.tar.gz
) source archive, which skips the copying of the current program tree.
Some dh-make
action
After calling dh_make -f <filepath>
, you will be prompted to select the type of package you are creating.
Type of package: single binary, indep binary, multiple binary, library, kernel module, kernel patch?
[s/i/m/l/k/n] s
For this example, we can assume that newprogram-0.12.7
is a single binary.
Next, if you set your shell environment variables $DEBEMAIL
and $DEBFULLNAME
, you should see the output of a control
file with the relevant fields already completed. If not, you will have to edit the control
file manually. (See this post)
Maintainer name : Testy McTester
Email-Address : person@company.tld
Date : Mon, 13 Jul 2015 10:44:12 -0700
Package Name : newprogram
Version : 0.12.7
License : blank
Type of Package : Single
Hit <enter> to confirm:
Piecing it all together
After running dh_make -f
, a copy of the upstream tarball will be created in the parent directory.
$ pwd
/newprogram
$ ls
newprogram-0.12.7/
newprogram-0.12.7.tar.gz
newprogram_0.12.7.orig.tar.gz # <- this guy right here
There are a couple of things to note about the newprogram_0.12.7.orig.tar.gz
filename:
- The package name and version are separated by the underscore (_) character
- The string
.orig
is placed before.tar.gz
Also, newly created debian template files will be placed in the source folder under the debian directory.
$ cd newprogram-0.12.7/debian/
$ ls
changelog compat control copyright docs rules source ...
this example does not show all template files created by dh_make
Next steps
After the debian boilerpate files have been created, the real fun can begin. This includes understanding and modifying the required files under the debian directory, modifying the upstream source, and building the actual package.
We’ve also put out a couple of blog posts that can likely help you along the way:
#packaging_love
Conclusion
Use dh_make
to automate some of the boilerplate around creating a debian package from an upstream source. Hopefully, it’ll get you a few steps ahead when building your next deb package. If you’re not experienced in making software packages, chances are there will be some pain and suffering in your immediate future - but fear not! We have released a series of blog posts to help you along the way. Check out the packagecloud.io blog.