Debian Directory

Now that we have Debian tools ready, it's time to define the package. In this guide however, we won't be showing steps by steps as an independent guide but rather complements from the existing document.

Binary or Source Package

Debian system allows you to compile either the binary form or the source form. They are both different in terms of deployment and maintainability. From Debian Buster onward, the official guide requires us to build the source package. Let's stick to the source package.

The primary difference between them are:

• Binary package requires you to create an UPCASE Debian directory: $ mkdir DEBIAN
• Source package requires you to create a lowercase Debian directory: $ mkdir debian

Once you created the Debian directory inside your project, it's time to pack the necessary files in it. In this guide, we'll be strictly building the source package.

$ mkdir debian

Creating debian/control

debian/control file is the most critical file of all. It carries the instruction and the metadata for your package. This file follows a very strict rules and template, like the one specified in the guide. We'll go through each of them accordingly.

Template Format

 1 Source: <software name>

 2 Section: <software type>

 3 Priority: optional

 4 Maintainer: Josip Rodin <joy-mg@debian.org>

 5 Build-Depends: debhelper (>=10)

 6 Standards-Version: 4.0.0

 7 Homepage: <insert the upstream URL, if relevant>

 8

 9 Package: gentoo

10 Architecture: any

11 Depends: ${shlibs:Depends}, ${misc:Depends}

12 Description: <insert up to 60 chars description>

13  <insert long description, indented with spaces>

Line 1: Source

Source is the software name or the package. This name should be like a 1 word or 2 words with/without connected with hyphen(-).

Avoid using long name. If it happens to you, you should greatly consider the level of details in the name and place them in the descriptions instead.

Example: gentoo, bashell, nuko, shellcheck, coreutils

Line 2: Section

Section is the software distribution your software should goes into. It is a controlled value listed in the Debian Policy Manual. Generally, we use these sections but you can browse the policy to search for more:

• main - the free software
• non-free - the not free software
• contrib - the free software that depends on non-free software.
• devel - the programmer tools
• doc - the documentation
• libs - the libraries
• mail - the email and its associated daemons
• net - the network applications and daemons

Line 3: Priority

Denotes the priority to install your package to user. It is a controlled value listed in Debian Policy Manual. In summary, the values are as follow:

• required - for software critical enough that it can break dpkg packaging software, brick the operating system and make the system totally broken.
• important - for bare minimum software that is common across all Linux system, such as coreutils, grub, etc.
• standard - for bare minimum of your software. The core system. You should only have one standard package with many optional packages.
• optional - commonly used for majority of the archive.

If you don't know what to do, use optional.

Line 4: Maintainer

The contact email when something happens to your package. Please ensure you provide a proper send-able email address. This email follows the format:

FULL NAME <email address>

Example:

Josip Rodin <joy-mg@debian.org>

Line 5: Build-Depends

Specify the dependent tools/software for building your software package. Based on the guide, since most implementation is now using dh command, you should append debhelper (>=10) into Build-Depends. A good example would be:

Build-Depends: debhelper (>=9), bash (>=4.3)

Line 6: Standards-Version

The version number for the standards you're planning to use. Do not confused this field as your software version. It is strictly referring to the Standards-Version list. Keep in mind that not all versions are available in every operating system or distribution branches. You should use the appropriate version that is compatible to your build machine.

Line 7: Homepage

The web URL for your software. Keep it short and simple.

Line 8: Empty Line

This empty line is mandatory. It splits the source section and binary section of the control file. Leave it a clean blank line.

Line 9: Package

Name for the binary package. It is usually the same as Line 1 Source name.

Line 10: Architecture

Specify the package is architecture dependent or otherwise as per Debian Policy Manual. You can check the architecture list using the command dpkg-architecture -L. Some common values are:

armhf

armel

mipsn32

mipsn32el

mipsn32r6

mipsn32r6el

mips64

mips64el

mips64r6

mips64r6el

powerpcspe

x32

arm64ilp32

i386

ia64

amd64

armeb

arm

arm64

avr32

Debian also supplies 2 common value for architecture independent software like scripts, images, and docs; and "compile at install" software. These are:

• any - for "compile at install" software
• all - for architecture independent software

Line 11: Depends

Specify the dependencies for the binary package. This is the list where user will get software lists to be installed when installing your software using dpkg. By default, you must include ${shlibs:Depends}, ${misc:Depends}. These 2 flags are for packager to include the dependencies identified via automation .

There are a lot more keywords aside "Depends". You can refer to the guide: https://www.debian.org/doc/manuals/maint-guide/dreq.en.html.

Line 12: Short Description

The short description, should be around 60 characters, written in the following styles:

Style 1: This package <name> <do what in a nutshell>

Style 2: collection of <something> from <where>

Style 3: <what's inside in a nutshell>

Style 4: <do what in a nutshell> with <name>

Some guidelines:

1. Never starts the description with the package name. This is an error.
2. Never go beyond 80 characters, or only a word. Follow the 60 characters guideline. They are known errors for too long and too short.
3. Capitalize accordingly. Lintian will notify you if it detects such phenomenon.
4. Never starts the description with article (a, an, the). This is a known warning. Use "This" or other styles.
5. Never state a package name as the short description. This is an error.
6. Clean up your leading space. This is a warning.
7. Don't end the sentence with a period (.). Lintian will notify you if it detects such phenomenon.

This short description is meant pitching your software package during package shopping. User may use certain keywords in his/her search. Therefore, just like Search Engine Optimization, you should always do a good research with the keywords and let user find your software easily! Here are some examples when a user search for coreutils:

$ sudo apt search coreutils

bsdmainutils/stable,now 9.0.12+nmu1 amd64 [installed]

  collection of more utilities from FreeBSD

coreutils/stable,now 8.26-3 amd64 [installed]

  GNU core utilities

gotail/stable 1.0.0+git20160415.b294095-3+b2 amd64

  Go implementation of tail

libsemanage1/stable,now 2.6-2 amd64 [installed]

  SELinux policy management library

mktemp/stable 8.26-3 all

  coreutils mktemp transitional package

policycoreutils/stable 2.6-3 amd64

  SELinux core policy utilities

policycoreutils-dev/stable 2.6-3 amd64

  SELinux core policy utilities (development utilities)

policycoreutils-gui/stable 2.6-3 all

  SELinux core policy utilities (graphical utilities)

policycoreutils-python-utils/stable 2.6-3 amd64

  SELinux core policy utilities (Python utilities)

policycoreutils-sandbox/stable 2.6-3 amd64

  SELinux core policy utilities (graphical sandboxes)

progress/stable 0.13.1-1 amd64

  Coreutils Progress Viewer (formerly known as 'cv')

python3-sepolgen/stable 2.6-3 all

  Python3 module used in SELinux policy generation

realpath/stable 8.26-3 all

  coreutils realpath transitional package

Line 13 and Beyond: Long Description

This section holds the long description for your software. There isn't any limit to the long description but please keep it concise and straight to the point. A sensible length is usually 2-4 paragraphs at 6 maximum lines each.

User views this long description using apt show <package> command. Here's an example:

$ sudo apt show zoo

Package: zoo

Version: 2.10-28

Priority: optional

Section: utils

Maintainer: Debian QA Group <packages@qa.debian.org>

Installed-Size: 140 kB

Depends: libc6 (>= 2.14)

Homepage: http://www.ibiblio.org/pub/packages/ccic/software/unix/utils/

Tag: implemented-in::c, interface::commandline, role::program,

 scope::utility, use::compressing, use::storing, works-with::archive

Download-Size: 64.3 kB

APT-Sources: http://ftp.us.debian.org/debian stretch/main amd64 Packages

Description: manipulate zoo archives

 Zoo is used to create and maintain collections of files in compressed

 form.  It uses a Lempel-Ziv compression algorithm that gives space

 savings in the range of 20% to 80% depending on the type of file data.

 Zoo can store and selectively extract multiple generations of the same

 file.

 .

 This package exists for its historical value. If you are looking for

 a compression tool for serious use, check tar and gzip.

There are a few things to take note of:

1. You must leave a space( ) for each line.
2. For newline, add a period (.) instead of leaving it empty.
3. Don't add URL in it. That belongs to Homepage.
4. Don't describes anything that is already known in other field.
5. Be very sensitive with Capitalization. The Lintian is great at detecting such error.
6. Don't duplicate your short description into your description. This is a known error.

Here's an example for a debian/control file or see the one in the official guide:

Source: fennec

Section: devel

Priority: optional

Maintainer: ZORALab Enterprise <tech@zoralab.com>

Build-Depends: debhelper (>=9), bash (>=4.3)

Standards-Version: 3.9.8

Homepage: https://gitlab.com/ZORALab/fennec

Package: fennec

Architecture: all

Depends: ${misc:Depends}, ${shlibs:Depends}, bash (>= 4.3)

Description: This package fennec provides a way to handle CI script

 fennec is a software management tool to handle web supported git repository.

 It structures the repository for a semi-automatic continuous integration

 alongside with web platform supports, such as GitLab.

Creating debian/copyright

This defines the software license for using the your software package. It is a UTF-8 encoded only file and strictly machine parse-able document. The entire detailed information is documented in the Debian Policy Manual - Copyright File section. While it takes time to create one, you can follow the main guide. Here's one example:

 1 Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

 2 Upstream-Name: <package name>

 3 Upstream-Contact: Emil Brink <emil@obsession.se>

 4 Source: <url to source>

 5

 6 Files: *

 7 Copyright: 1998-2010 Emil Brink <emil@obsession.se>

 8 License: GPL-2+

 9

10 Files: icons/*

11 Copyright: 1998 Johan Hanson <johan@tiq.com>

12 License: GPL-2+

13

14 Files: firmware/*

15 Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>

16            2008, John Doe <jdoe@example.com>

17            2007, Jane Smith <jsmith@example.org>

18            2007, Joe Average <joe@example.org>

19            2007, J. Random User <jr@users.example.com>

20 License: Proprietary

21

22 License: GPL-2+

23  This program is free software; you can redistribute it and/or modify

24  it under the terms of the GNU General Public License as published by

25  the Free Software Foundation; either version 2 of the License, or

26  (at your option) any later version. 

27  .

28  This program is distributed in the hope that it will be useful,

29  but WITHOUT ANY WARRANTY; without even the implied warranty of

30  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

31  GNU General Public License for more details.

32  .

33  You should have received a copy of the GNU General Public License along

34  with this program; if not, write to the Free Software Foundation, Inc.,

35  51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

36  .

37  On Debian systems, the full text of the GNU General Public

38  License version 2 can be found in the file

39  '/usr/share/common-licenses/GPL-2'.

40

41 License: Proprietary

42  PROPRIETARY AND CONFIDENTIAL

43  Unauthorized copying of any files and any codes within this project, via any

44  medium is strictly prohibited.

45  .

46  Any line of code and file in this repository CANNOT be copied and/or

47  distributed in any means, any forms, any medium and any channels, without the

48  express written permission of the owner mentioned above.

Line 1: Format

Declares the copyright format version for the package. It tells how this copyright document to parse. Currently there is only version 1.0, in which you can read it here:

• 1.0 - https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/

TIP: read the document itself to populate the necessary information in this file.

Line 2: Upstream-Name

The package name. This should be the same as "Source" and "Package" fields in debian/control.

Line 3: Upstream-Contact

The maintainer contact. This should be the same as "Maintainer" field in debian/control.

Line 4: Source

The URL to your source repository / website. This can be the same as "Homepage" field in debian/control.

Line 5: Necessary Line Split

This is an empty line to split the file header, which is Line 1 to Line 4.

Line 6 - Line 9: License Bind

The license binding for a file/set of files. In a bind, you need to specify the filename with its relative path, copyright owner and the corresponding license tag. Keep in mind that the license tag is a recognized short-code, in which you'll define the license later. We'll go through each line one by one here.

Line 6: Files

The list of files you plan to bind to. Use asterisk (*) to indicate all files within a directory. If you use a single asterisk alone like in Line 6, it means the entire package is bind to that license.

Line 7: Copyright Owner

State the copyright owner for the specified files. When applicable, this can be the same as "Maintainer" field in debian/control. If you have multiple owners, you can list them out in the following line with aligned indentation. Here's an example:

Copyright: 1998-2010 Josip Rodin <joy-mg@debian.org>

           2008, John Doe <jdoe@example.com>

           2007, Jane Smith <jsmith@example.org>

           2007, Joe Average <joe@example.org>

           2007, J. Random User <jr@users.example.com>

This field also supports multi-year copyright. See line 15 in the example above.

Line 8: The License Tag

The license tag you wish to bind with. Keep in mind that this is a tag. You'll need to declare the license's body in later section. It is a controlled value specified inside the specification format that you use. Example, for version 1.0, see License Specification section. These license tags are also available at SPDX License List alongside with their respective license body.

If you are using dual or multiple licensing, you can use them with "and" or "or" words for additional bindings. Here's an example:

License: GPL-1+ or Artistic

License: GPL-2+ and BSD-3-clause

Here's how it works, as per version 1.0 format:

A or B ➔ ( A or B).

A and B ➔ A and B.

A or B and C ➔ A or (B and C).

A or B, and C ➔ (A or B) and C.

You are, however, not allowed to mislead known keywords to a foreign license body. Example: your tag is "GPL-2.0-only" but your license body declares the tag has "NRL License".

Exception

If you really need to use private tag, such as "proprietary" or "fair-use", make sure they are not declared in the known list. As long as the license body is declared in later section that matches the keyword, you're good.

Line 9: Necessary Line Split

When a license bind is completed, this line indicates that binding statements are completed. You should leave an empty new line.

Line 10-12: Demonstrate Licenses Binding Across Multiple Files

This is a different tag to demonstrate how to bind the same license across different files. Notice the similarity.

Line 14-20: Demonstrate License Binding Across Multiple Licenses

This is a different tag to demonstrate how to bind a different license, with multiple copyright owners alongside their copyright years. Notice the similarity.

Line 22: License Declaration

Specify the license body for a particular tag. This line specify GPL2+ tag as deployed in Line 6 and Line 12 license binding. You should append the short text / license header in the following line.

Line 23-39: License Body

The written license body. There is a machine formatting for this section:

1. Use 1 space ( ) to indicate it's a long text.
2. If you need an empty line for your text, use a period (.). See line 27, 32, and 36.

Line 40: Necessary Line Split

When a license body is done writing, this line indicates that the declaration is completed. You should leave an empty new line.

Line 41-48: Demonstrate A Multiple Licenses Declaration

This is a different declaration for multiple licenses. Notice the similarity.

Creating debian/rules

This is a Makefile dedicated for building your package. To date (2018), the ecosystem does supply the debhelper to simplify things up. We'll be using this method for building the package.

As per the Debian guide, you're allowed to customize this rules Makefile. However, this guide will focus on copy and paste software as our highest priority is to get things work. If you're looking for customization guide, it will be in a separate topic.

Keeping it simple, we only need this (NOTE: the "TAB" spacing here is TAB, not space):

#!/usr/bin/make -f

# Uncomment this to turn on verbose mode.

#export DH_VERBOSE=1

%:

        dh $@

Creating debian/compat

Declare compatibility for the debhelper. As per guide, you can create this file with the number version in it, like "10". A quick way to create this file is:

$ echo 10 > debian/compat

You should build your compatibility version to 10 to avoid outdated disruption.

Creating debian/manpage.N

Creating manual page for your package. You must follow the guide, especially the numbering extension. The manpage format follows the standard man-page format. The number level however, indicates the particular manual page at certain operating system level:

• 1 - User Commands
• 2 - System Calls
• 3 - Library Calls
• 4 - Special Files
• 5 - File Formats
• 6 - Games
• 7 - Macro Packages
• 8 - System Administration
• 9 - Kernel Routine

Use the correct numbering to indicate the content. You can save the documents anywhere inside the debian directory. A good way would be grouping them inside a debian/doc directory.

Creating debian/package.manpages

Create the list of manpages for your package. This file serves as an index for all your manuals. You just need to list your manpages path relative to debian directory in this file. Here's an example of what's inside the file:

doc/package.1

doc/package.2

doc/package.3

doc/package.4

doc/package.5

doc/package.6

doc/package.7

doc/package.8

doc/package.9

The system is smart enough to identify the manpage's level through the file numbering.

Creating debian/source/format

This is to tell the build system to use the source format. There are a series of versions available. The commonly used are:

• 3.0 (quilt)
• 3.0 (native)
• 3.0 (git)
• 1.0

You just need to create a directory called source and then a file containing the value in it. Quilt is a version control for the package and is compulsory to use it if you're building an upstream package.

Otherwise, stick to the native version 3 by default.

Keep in mind that git version 3 is still experimental and it may not work properly in the upstream version. Use with caution.

Creating debian/install

Tells the package manager to install files at the correct location. In this file, we declare what files to be placed at which location. As per guide, you should declare the path in a pure relative manner. Example:

<relative path from current source to file> <relative to root directory>

Here are some examples:

bin/executable usr/bin/program

src/bar usr/bin/bar

fennec usr/bin                                                                                                                                                                                                     

lib/fennec usr/share/fennec

Now you can't simply copy your files anywhere in the Linux root system. All the corresponding files should comply to the Debian File Hierarchy Standards.

For our power-on objective, let's keep things simple by copying 1 file to a known location of your desire.

Once you're done, you should have your Debian directory ready. A quick look over the package should produce something as follows (an example):

debian

├── changelog

├── compat

├── control

├── copyright

├── fennec.1

├── fennec.manpages

├── install

├── rules

└── source

    └── format

There are more files specified by the policy manual and the guide. However, these are the minimum requirements for the package builder to build a successful deb package.