Example 15.3. The control file
Source: falcot-data
Section: misc
Priority: optional
Maintainer: Raphael Hertzog <hertzog@debian.org>
Build-Depends: debhelper (>= 7.0.50~)
Standards-Version: 3.8.4
Package: falcot-data
Architecture: all
Depends: iceweasel | www-browser, ${misc:Depends}
Description: Internal Falcot Corp Documentation
This package provides several documents describing the internal
structure at Falcot Corp. This includes:
- organization diagram
- contacts for each department.
.
These documents MUST NOT leave the company.
Their use is INTERNAL ONLY.
Example 15.4. The changelog file
falcot-data (1.0) internal; urgency=low
* Initial Release.
* Let's start with few documents:
- internal company structure;
- contacts for each department.
-- Raphael Hertzog <hertzog@debian.org> Mon, 11 Apr 2011 20:46:33 +0200
Example 15.5. The copyright file
This work was packaged for Debian by Raphael Hertzog <hertzog@debian.org>
on Mon, 11 Apr 2011 20:46:33 +0200
Copyright:
Copyright (C) 2004-2011 Falcot Corp
License:
All rights reserved.
BACK TO BASICS Makefile file
A Makefile file is a script used by the make program; it describes rules for how to build a set of files from each other in a tree of dependencies (for instance, a program can be build from a set of source files). The Makefile files describes these rules in the following format:
target: sources
command1
command2
The interpretation of such a rule is as follows: if one of the files of sources is more recent than the target file, then the target needs to be generated, using command1 and command2.
Note that the command lines must start with a tab character; also note that when a command line starts with a dash character (-), failure of the command does not interrupt the whole process.
The rules file usually contains a set of rules used to configure, build and install the software in a dedicated subdirectory (named after the generated binary package). The contents of this subdirectory is then archived within the Debian package as if it were the root of the filesystem. In our case, files will be installed in the debian/falcot-data/usr/share/falcot-data/ subdirectory, so that installing the generated package will deploy the files under /usr/share/falcot-data/. The rules file is used as a Makefile, with a few standard targets (including clean and binary, used respectively to clean the source directory and generate the binary package).
Although this file is the heart of the process, it increasingly contains only the bare minimum for running a standard set of commands provided by the debhelper tool. Such is the case for files generated by dh_make. To install our files, we simply configure the behaviour of the dh_install command by creating the following debian/falcot-data.install file:
data/* usr/share/falcot-data/
At this point, the package can be created. We will however add a lick of paint. Since the administrators want the documents to be easily accessed from the Help menus of graphical desktop environment, we create an entry in the Debian menu system. This is simply done by renaming the debian/menu.ex without its extension and editing it as follows:
Example 15.6. The menu file
?package(falcot-data):needs=X11|wm section=Help\
title="Internal Falcot Corp Documentation" \
command="/usr/bin/x-www-browser /usr/share/falcot-data/index.html"
?package(falcot-data):needs=text section=Help\
title="Internal Falcot Corp Documentation" \
command="/usr/bin/www-browser /usr/share/falcot-data/index.html"
The needs field, when set to X11|wm indicates that this entry only makes sense in a graphical interface. It will therefore only be integrated into the menus of the graphical (X11) applications and window managers (hence the wm). The section field states where in the menu the entry should be displayed. In our case, the entry will be in the Help menu. The title field contains the text that will be displayed in the menu. Finally, the command field describes the command to run when the user selects the menu entry.
The second entry matches the first one, with slight adaptations adapted to the Linux console text mode.
DEBIAN POLICY Menu organization
The Debian menus are organized in a formal structure, documented in the following text:
→ http://www.debian.org/doc/packaging-manuals/menu-policy/
The section in a menu file should be picked from the list mentioned in this document.
Simply creating the debian/menu file is enough to enable the menu in the package, since the dh_installmenu command is automatically invoked by dh during the package build process.
Our source package is now ready. All that's left to do is to generate the binary package, with the same method we used previously for rebuilding packages: we run the dpkg-buildpackage -us -uc command from within the falcot-data-1.0 directory.
15.3. Creating a Package Repository for APT
Falcot Corp gradually started maintaining a number of Debian packages either locally modified from existing packages or created from scratch to distribute internal data and programs.
To make deployment easier, they want to integrate these packages in a package archive that can be directly used by APT. For obvious maintenance reasons, they wish to separate internal packages from locally-rebuilt packages. The goal is for the matching entries in a /etc/apt/sources.list file to be as follows:
deb http://packages.falcot.com/ updates/
deb http://packages.falcot.com/ internal/
The administrators therefore configure a virtual host on their internal HTTP server, with /srv/vhosts/packages/ as the root of the associated web space. The management of the archive themselves is delegated to the mini-dinstall command (in the similarly-named package). This tool keeps an eye on an incoming/ directory (in our case, /srv/vhosts/packages/mini-dinstall/incoming/) and waits for new packages there; when a package is uploaded, it is installed into a Debian archive at /srv/vhosts/packages/. The mini-dinstall command reads the *.changes file created when the Debian package is generated. These files contain a list of all other files associated to the version of the package (*.deb, *.dsc, *.diff.gz/*.debian.tar.gz, *.orig.tar.gz, or their equivalents with other compression tools), and they allow mini-dinstall to know which files to install. *.changes files also contain the name of the target distribution (often unstable) mentioned in the latest debian/changelog entry, and mini-dinstall uses this information to decide where the package should be installed. This is why administrators must always change this field before building a package, and set it to internal or updates, depending on the target location. mini-dinstall then generates the files required by APT, such as Packages.gz.