dpkg/doc/internals.sgml

<!doctype debiandoc system [
<!entity % manuals-version-def system "manuals-version">
%manuals-version-def;
]>
<debiandoc><book>

<titlepag>
<title>dpkg Internals Manual</title>
<author>
  <name>Klee Dienes</name>
  <email>klee@mit.edu</email>
</author>
<version>Version &manuals-version; (dpkg &dpkg-version;)</version>
<abstract>
This manual describes the internal structure of the <prgn>dpkg</prgn> package
management system.
</abstract>

<copyright>
<copyrightsummary>
Copyright &copy;1997 Klee Dienes &lt;klee@mit.edu&gt;
</copyrightsummary>
<p>
This manual is free software; you may redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation; either version 2, or (at your option) any
later version.
<p>
This is distributed in the hope that it will be useful, but
<em>without any warranty</em>; without even the implied warranty of
merchantability or fitness for a particular purpose.  See the GNU
General Public License for more details.
<p>
You should have received a copy of the GNU General Public License with
your Debian system, in <file>/usr/share/common-licenses/GPL</file>, or
with the <prgn>dpkg</prgn> source package as the file <file>COPYING</file>.  If
not, write to the Free Software Foundation, Inc., 675 Mass Ave,
Cambridge, MA 02139, USA.
</copyright>
</titlepag>

<toc detail="sect">

<chapt id=build>
<heading>Build Notes</heading>
  <sect id=automake>
  <heading>Automake</heading>
<p>
This section by Tom Lees &lt;tom@lpsg.demon.co.uk&gt; on Tue, 4 Mar 1997
21:34:57 +0000, with subsequent modifications by Klee Dienes &lt;klee@debian.org&gt;

<p>
This chapter contains general notes about the conversion to
<prgn>automake</prgn>.  If you plan on doing anything with <prgn>dpkg</prgn>, you
should probably read all of this file first.  You have been warned.

<p>
Automake has several significant advantages, including:

<list>
<item>it supports emacs lisp properly
<item>It supports libtool properly
<item>it includes the aclocal utility
</list>

<p>
The <prgn>aclocal</prgn> utility is a very useful program which will automatically
build an <file>aclocal.m4</file> file from the <file>configure.in</file> file to include the
appropriate macros.

<p>
This doesn't affect anything other than rebuilding the <file>Makefile.in</file> files
from the sources.

<p>
Probably the main difference which is noticable is that instead of
using proprietary directory names, it now supports <em>configure
--sharedstatedir</em>, and <em>configure --localstatedir</em>. To set these
to the Debian defaults, you should use <em>./configure
--localstatedir=/etc --sharedstatedir=/var/lib</em>.

<p>
I have also customized the canonicalizing macros found in
<em>autoconf</em> to include the old way of finding the <prgn>dpkg</prgn>
``architecture'', i.e. to be a bit more smart. Instead of it trying to
determine the architecture only, I changed it to use the `host',
`build', and `target' system types. The target CPU type is checked
against the archtable to find the architecture on which dpkg will run.

<p>
It uses <em>gcc --print-libgcc-file-name</em> to find out the build
architecture if possible (used later to determine ELF or <em>a.out</em>
format), and also uses <em>dpkg --print-architecture</em> if possible to
modify the <em>cpu</em> field before it passes on the target alias to
config.sub. If you want to specify the architecture, you should now
use "--target=", rather than <em>--with-arch</em>, which was essentially
a hack anyway.  The old <em/--with-arch/ is still there, but it is
somewhat less functional. I have also moved the
<em/DPKG_CACHED_/ macros into dpkg.m4 to make configure.in a bit
more readable.

<p>
I also converted to libtool (which can be found in the Debian
distribution now). Essentially, this means that all the dpkg tools can
be compiled against a shared <em>libdpkg</em> without much hassle (in
fact, it is the default). You do not need to install libtool to use
this feature (it works like autoconf), and generally, it should not be
needed much at all.

<p>
The new <em>dist</em> targets will build a distribution including all
files built by the <prgn>debiandoc2html</prgn>, <prgn>debiandoc2ps</prgn>, etc.,
which are included in the distribution so that people may build <prgn>dpkg</prgn>
without these (especially useful to porters).

<p>
A target <em/make debian/ has been added, which will build the
Debian files from a working directory (does a <em/make dist/
first). Now all we need is a modified dpkg-source so that the
<file/dpkg-1.4.0.8.tar.gz/ GNU-distribution file can be used as part
of the Debian distribution.  I'm working on this, but it doesn't work
too well at the moment (find it in examples).

<p>
I removed the <em/make portable/ target - it doesn't do anything useful.

<p>
I have added <em/make uninstall/ targets to aid non-Debian users who simply
want to try out certain Debian packages, and the "dist" targets are also
useful to build a "distribution" of the dpkg tool. Note that since automake
automatically includes dependencies into the Makefiles in a distribution,
if you want to modify the C files, it would be advisable to get and install
automake, and then re-run it in the base dpkg distribution directory, so that
automatic dependency generation will be switched back on, and any
dependencies which change will be taken account of. The "make maintainer-clean"
targets will remove all files which any of the following utilities create:

<list>
<item>automake
<item>autoconf
<item>aclocal
<item>autoheader
<item>gettextize
<item>libtoolize
</list>

<p>
If you want to modify any of the sources, I recommend that you do the following
first (after having installed the appropriate utilities, of course):-

<list>
<item>
make maintainer-clean
<item>
aclocal
<item>
autoheader
<item>
autoconf
<item>
gettextize
<item>
libtoolize (do not let automake run this, as it will cause it not to
include the libtool files in the dist targets) 
<item>
for i in COPYING INSTALL; do ln -s /usr/share/automake/$i .; done
<item>
automake
</list>

<p>
I have also incorporated the patches originally made by Galen
Hazelwood to internationalize dpkg using GNU gettext - see the file
"NOTES.intl" for more information about this.

<p>
Other minor changes are:

<list>
<item>
The version number is now determined from debian/changelog, not from
the directory name.
<item>
Creation of version.h now handled from configure script, not Makefile.
<item>
include/dpkg.h is now generated from include/dpkg.h.in by a sed
script, inserting the appropriate directory definitions - so now it
supports changing the dpkg directories (can install in /usr/local)
<item>
Updated the COPYING (1 very minor change) and INSTALL files to those
distributed with automake-1.1l
<item>
Since the shared libdpkg is now installed, I also made
include/Makefile install dpkg.h and dpkg-db.h into /usr/include by
default
</list>

Questions:

<list>
<item>
Should I use <em/localstatedir/ and <em/sharedstatedir/ instead of
<em/sysconfdir/ and <em/datadir/?
</list>

</sect>

<sect id=i18n>
<heading>Internationalization</heading>

<p>
This section by Galen Hazelwood. 

<p>
Dpkg is, to say the least, generous in its error reporting.  The vast
majority of the output strings are error messages of one kind or another.
And if you feel that you've stumbled into the Department of Redundancy
Department, you would be absolutely correct.  Many of the error messages
in dpkg.pot are duplicates, used at different points in the program.

<p>
To avoid swamping the translators completely, I made some executive decisions
on what kinds of strings to translate.  All the strings sent to debug() are
left alone, on the grounds that these are for dpkg developers, and not for
the general public.  Most interal error messages were very cryptic, and
would probably confuse the translators when seen just sitting there in
the dpkg.pot file, and are also left alone.  (I did mark some of the more
verbose ones for translation.)

<p>
If others disagree with me about the necessity of translating these strings,
it's easy enough to just go through and mark them later.

<p>
I added the startup gettext code to the main routine in dselect, which was
necessary as many of the strings in lib are translated.  Dselect is otherwise
unchanged.

<p>
Changes:

<list>
<item>
The files in intl and po were taken from gettext 0.10.26, by way of
the gettextize program.  I altered the makefiles to remove the VERSION
symbol, which is only used in targets which dpkg does not support.
<item>
aclocal.m4 was stolen from the textutils package, configure.in was
altered to use these new tests, symbols were added to acconfig.h, and
the two new directories were added to Makefile.in.
<item>
The dpkg, dpkg-deb, md5sum, split, and dselect Makefiles now look for
headers in ../intl, and try to link with whatever i18n libraries
configure finds.  They also now define LOCALEDIR in CFLAGS.
<item>
include/dpkg.h has the necessary NLS boilerplate, and the only file
which dosen't include this (md5sum/md5sum.c) had it added directly.
<item>
The most intrusive change is due to a disagreement between xgettext
and the dpkg coding style.  Although xgettext understands string
constant concatenation, it can't handle the case where preprocessor
symbols are used as well.  The dpkg code uses this a lot, especially
in cases like this:
<example>
ohshite("error reading from " BACKEND " pipe");
</example>
where BACKEND is defined as "dpkg-deb".  Because xgettext can't handle
this, I have changed this usage in all cases to something like:
<example>
ohshite(_("error reading from dpkg-deb pipe");
</example>
This isn't very kind to Ian, I know.  But what can I do?
</list>

</sect>

</chapt>

<chapt id=code>
<heading>Code Internals</heading>

<sect id=defs>
<heading>Structure Definitons</heading>

<sect1 id=versionrevision>
<heading>versionrevision</heading>
<p>
<example>
struct versionrevision {
  unsigned long epoch;
  char *version;
  char *revision;
};  
</example>

<p>
The <tt/versionrevision/ structure is used to store a Debian version specification
</sect1>

</sect>

<sect id=functions>
<heading>Functions</heading>

<sect1 id=parsing>
<heading>Parsing translation tables</heading>
<p>
Each of these tables is used to associate a set of strings with a
corresponding set of integers.

Current tables are:

<p>
<example>
const struct namevalue booleaninfos[];
</example>

<p>
Maps boolean strings (<em/"yes"/,<em/"no"/) to their binary values.

<sect2>
<heading>priorityinfos[]</heading>

<p>
<example>
const struct namevalue priorityinfos[];
</example>

<p>
Maps priority strings to and from values of
type <em/enum pkgpriority/.  
Current priority values are:

<list>
<item><em/required/ - required
<item><em/important/ - important
<item><em/standard/ - standard
<item><em/recommended/ - recommended
<item><em/optional/ - optional
<item><em/extra/ - extra
<item><em/contrib/ - contrib
<item><em/other/ - other
<item><em/unknown/ - unknown
<item><em/base/ -
This is obsolete, but is accepted as an alias for <em/required/.
</item>
</list>
</sect2>

<sect2>
<heading>statusinfos[]</heading>

<p>
<example>
const struct namevalue statusinfos[];
</example>

Maps package status strings to values of type <em/enum ???/.

Package status strings are:

"not-installed" "unpacked" "half-configured" "installed"
"half-installed" "config-files" "postinst-failed" "removal-failed"
</sect2>

<sect2>
<heading>eflaginfos[]</heading>

<p>
<example>
const struct namevalue eflaginfos[];
</example>
</sect2>

<sect2>
<heading>wantinfos[]</heading>

<p>
<example>
const struct namevalue wantinfos[];
</example>
</sect2>

<sect2>
<heading>nicknames[]</heading>

<p>
<example>
const struct nickname nicknames[];
</example>

Maps obsolete control fields to their current versions.

</sect2>

</sect1>

<sect1 id=parsef>
<heading>Parsing functions</heading>

<sect2>
<heading>parseerr()</heading>

<p>
<example>
void parseerr
(FILE *file, const char *filename, int lno,
 FILE *warnto, int *warncount, const struct pkginfo *pigp,
 int warnonly, const char *fmt, ...);
</example>

Report an error parsing a control data stream.  Checks <var/file/ for
error status on <var/file/, printing an error message to stderr and
exiting with error status if an error is present on the stream.
Formats the variable arguments according to the <em/printf/-style
string in <var/fmt/, preceding the result with <var/filename/,
<var/lno/, and <var/pigp/ (if not NULL).  If <var/warnonly/ is 0,
writes the result to stderr and exits with error status.  Otherwise,
increments <var/warncount/ and returns normally.
</sect2>

<sect2>
<heading>illegal_packagename()</heading>

<p>
<em>
const char *illegal_packagename
(const char *p, const char **ep) 
</em>

Checks the package name at <var/p/ for proper syntax.  Returns NULL in
case of success, setting <var/*ep/ to point after the last character
in the package name, including any trailing whitespace (as defined by
isspace()).  In case of error, returns the error message as a pointer
to a static buffer.
</sect2>

<sect2>
<heading>informativeversion()</heading>

<p>
<em>
int informativeversion(const struct versionrevision *version)
</em>

<p>
Returns true if and only if the <em/versionrevision/ is non-empty;
otherwise returns false.
</sect2>

<sect2>
<heading>varbufversion()</heading>

<p>
<example>
void varbufversion
(struct varbuf *vb,
 const struct versionrevision *version,
 enum versiondisplayepochwhen vdew);
</example>

Writes a human-readable representation of <var/version/ to <var/vb/.
Possible values of <var/vdew/:

<list>
<item><tt/vdew_never/ - never include epoch
<item><tt/vdew_nonambig/ - include epoch string if non-zero
<item><tt/vdew_always/ - always include epoch string
</list>
</sect2>

<sect2>
<heading>versiondescribe()</heading>

<p>
<example>
const char *versiondescribe
(const struct versionrevision *version,
 enum versiondisplayepochwhen vdew);
</example>

<p>
Return a human-readable representation of <var/version/ as a pointer
to a static buffer.  If the version structure is empty, return
<em/"&lt;none&gt;"/.  Static buffers are allocated from a set of 10
in round-robin fashion (they will be re-used after 10 successive calls
to <em/versiondescribe/).
</sect2>

<sect2>
<heading>parseversion()</heading>

<p>
<example>
const char *parseversion
(struct versionrevision *rversion, const char *string);
</example>

<p>
Parse the contents of <var/string/ into <var/rversion/.  If
successful, returns NULL, otherwise returns a pointer to a static
error string.
</sect2>

<sect2>
<heading>parsemustfield()</heading>

<p>
<example>
void parsemustfield
(FILE *file, const char *filename, int lno,
 FILE *warnto, int *warncount,
 const struct pkginfo *pigp, int warnonly,
 char **value, const char *what);
</example>
</sect2>

<sect2>
<heading>skip_slash_dotslash()</heading>

<p>
<example>
const char *skip_slash_dotslash (const char *p);
</example>
</sect2>

<sect2>
<heading>convert_string()</heading>

<p>
<example>
static int convert_string
(const char *filename, int lno, const char *what, int otherwise,
 FILE *warnto, int *warncount, const struct pkginfo *pigp,
 const char *startp, const struct namevalue *nvip,
 const char **endpp) 
</example>
</sect2>

</sect1>

</sect>
</chapt>
</book></debiandoc>