[back] [Copyright Notice] [Contents] [next]

Debian Developer's Reference - Chapter 5
The Debian Archive


5.1 Overview

The Debian GNU/Linux distribution consists of a lot of Debian packages (.deb's, currently around 2250) and a few additional files (documentation, installation disk images, etc.).

Here is an example directory tree of a complete Debian distribution:

main/
main/binary-all/
main/binary-all/admin/
main/binary-all/base/
main/binary-all/comm/
main/binary-all/devel/
     ...
main/binary-i386/
main/binary-i386/admin/
main/binary-i386/base/
     ...
main/binary-m68k
main/binary-m68k/admin/
main/binary-m68k/base/
     ...
main/source/
main/source/admin/
main/source/base/
     ...
main/disks-i386/
main/disks-m68k/
     ...

contrib/
contrib/binary-all/
contrib/binary-i386/
contrib/binary-m68k/
     ...
contrib/source/

non-free/
non-free/binary-all/
non-free/binary-i386/
non-free/binary-m68k/
         ...
non-free/source/

As you can see, the top-level directory of the distribution contains three directories, namely main, contrib, and non-free. These directories are called sections.

In each section, there is a directory with the source packages (source), a directory for each supported architecture (binary-i386, binary-m68k, etc.), and a directory for architecture independent packages (binary-all).

The main section contains additional directories which holds the disk images and some essential pieces of documentation required for installing the Debian distribution on a specific architecture (disks-i386, disks-m68k, etc.).

The binary and source directories are divided further into subsections.


5.2 Sections

The main section is what makes up the official Debian GNU/Linux distribution. The main section is official because it fully complies with all our guidelines. The other two sections do not, to different degrees; as such, they are not officially part of Debian.

Every package in the main section must fully comply with the Debian Free Software Guidelines (DFSG) and with all other policy requirements as described in the Debian Policy Manual. The DFSG is our definition of ``free software.'' Check out the Debian Policy Manual for details.

The packages which do not apply to the DFSG are placed in the non-free section. These packages are not considered as part of the Debian distribution, though we support their use, and we provide infrastructure (such as our bug-tracking system and mailing lists) for non-free software packages.

Packages in the contrib section have to comply with the DFSG, but may fail other requirements. For instance, they may depend on non-free packages.

The Debian Policy Manual contains a more exact definition of the three sections. The above discussion is just an introduction.

The separation of the three sections at the top-level of the archive is important for all people who want to distribute Debian, either via FTP servers on the Internet or on CD-ROMs: by distributing only the main and contrib sections, one can avoid any legal risks. Some packages in the non-free section do not allow commercial distribution, for example.

On the other hand, a CD-ROM vendor could easily check the individual package licenses of the packages in non-free and include as many on the CD-ROMs as he's allowed. (Since this varies greatly from vendor to vendor, this job can't be done by the Debian developers.)


5.3 Architectures

In the first days, the Linux kernel was only available for the Intel i386 (or greater) platforms, and so was Debian. But when Linux became more and more popular, the kernel was ported to other architectures, too.

The Linux 2.0 kernel supports Intel x86, DEC Alpha, SPARC, Motorola 680x0 machines (like Atari, Amiga and Macintoshes), MIPS, and PowerPC. Newer kernels support more architectures, including ARM, UltraSPARC, and MIPS. Since Linux supports these platforms, Debian decided that it should, too. Therefore, Debian has ports underway. In fact, we also have ports underway to non-Linux kernel. Aside from i386 (our name for Intel x86), there is m68k, alpha, powerpc, sparc, hurd-i386, and arm as of this writing.

Debian GNU/Linux 1.3 is only available as i386. Debian 2.0 shipped for i386 and m68k architectures. Debian 2.1 ships for the i386, m68k, alpha, and sparc architectures.


5.4 Subsections

The sections main, contrib, and non-free are split into subsections to simplify the installation process and the maintainance of the archive. Subsections are not formally defined, excepting perhaps the `base' subsection. Subsections exist simply to simplify the organization and browsing of available packages. Please check the current Debian distribution to see which sections are available.


5.5 Packages

There are two types of Debian packages, namely source and binary packages.

Source packages consist of either two or three files: a .dsc file, and either a .tar.gz file or both an .orig.tar.gz and a .diff.gz file.

If a package is developed specially for Debian and is not distributed outside of Debian, there is just one .tar.gz file which contains the sources of the program. If a package is distributed elsewhere too, the .orig.tar.gz file stores the so-called upstream source code, that is the source code that's distributed from the upstream maintainer (often the author of the software). In this case, the .diff.gz contains the changes made by the Debian maintainer.

The .dsc lists all the files in the source package together with checksums (md5sums) and some additional info about the package (maintainer, version, etc.).


5.6 Distribution directories

The directory system described in the previous chapter, are themselves contained within distribution directories. Every distribution is contained in the dists directory in the top-level of the Debian archive itself (the symlinks from the top-level directory to the distributions themselves are for backwards compatability and are deprecated).

To summarize, the Debian archive has a root directory within an FTP server. For instance, at the mirror site, ftp.us.debian.org, the Debian archive itself is contained in /debian, which is a common location (another is /pub/debian).

Within that archive root, the actual distributions are contained in the dists directory. Here is an overview of the layout:

archive root/dists/distribution/section/architecture/subsection/packages
Extrapolating from this layout, you know that to find the i386 base packages for the distribution slink, you would look in /debian/dists/slink/main/binary-i386/base/.


5.6.1 Stable, unstable, and sometimes frozen

There is always a distribution called stable (residing in dists/stable) and one called unstable (residing in dists/unstable). This reflects the development process of the Debian project.

Active development is done in the unstable distribution (that's why this distribution is sometimes called the development distribution). Every Debian developer can update his or her packages in this distribution at any time. Thus, the contents of this distribution change from day-to-day. Since no special effort is done to test this distribution, it is sometimes ``unstable.''

After a period of development, the unstable distribution is copied in a new distribution directory, called frozen. When that occurs, no changes are allowed to the frozen distribution except bug fixes; that's why it's called ``frozen.'' After another month or a little longer, the frozen distribution is renamed to stable, overriding the old stable distribution, which is removed at that time.

This development cycle is based on the assumption that the unstable distribution becomes stable after passing a period of testing as frozen. Even once a distribution is considered stable, a few bugs inevitably remain--that's why the stable distribution is updated every now and then. However, these updates are tested very carefully and have to be introduced into the archive individually to reduce the risk of introducing new bugs. You can find proposed additions to stable in the proposed-updates directory. Those packages in proposed-updates that pass muster are periodically moved as a batch into the stable distribution and the revision level of the stable distribution is incremented (e.g., `1.3' becomes `1.3r1', `2.0r2' becomes `2.0r3', and so forth).

Note that development under unstable is continued during the ``freeze'' period, since a new unstable distribution is be created when the older unstable is moved to frozen. Another wrinkle is that when the frozen distribution is offically released, the old stable distribution is completely removed from the Debian archives (although you can still find it from servers which serve up older, obsolete distributions).

In summary, there is always a stable and an unstable distribution available, and the frozen distribution shows up for a month or so from time to time.


5.6.2 Experimental

The experimental distribution is a specialty distribution. It is not a full distribution in the same sense that `stable' and `unstable' are. Instead, it is meant to be a temporary staging area for highly experimental software where there's a good chance that the software could break your system. Users who download and install packages from experimental are expected to have been duly warned. In short, all bets are off for the experimental distribution.

Developers should be very selective in the use of the experimental distribution. Even if a package is highly unstable, it could well still go into unstable; just state a few warnings in the description. However, if there is a chance that the software could do grave damage to a system, it might be better to put it into experimental.

For instance, an experimental encrypted file system should probably go into experimental. A new, beta, version of some software which uses completely different configuration might go into experimental at the maintainer's discretion. New software which isn't likely to damage your system can go into unstable.


5.7 Release code names

Every released Debian distribution has a code name: Debian 1.1 is called `buzz'; Debian 1.2, `rex'; Debian 1.3, `bo'; Debian 2.0, `hamm'; Debian 2.1, `slink'; and Debian 2.2, `potato'. There is also a ``pseudo-distribution'', called `sid' which is contains packages for architectures which are not yet officially supported or released by Debian. These architectures are planned to be integrated into the mainstream distribution at some future date.

Since the Debian has an open development model (i.e., everyone can participate and follow the development) even the unstable distribution is distributed via the Internet on the Debian FTP and HTTP server network. Thus, if we had called the directory which contains the development version `unstable', then we would have to rename it to `stable' when the version is released, which would cause all FTP mirrors to re-retrieve the whole distribution (which is already very large!).

On the other hand, if we called the distribution directories Debian-x.y from the beginning, people would think that Debian release x.y is available. (This happened in the past, where a CD-ROM vendor built a Debian 1.0 CD-ROM based on a pre-1.0 development version. That's the reason why the first official Debian release was 1.1, and not 1.0.)

Thus, the names of the distribution directories in the archive are determined by their code names and not their release status (i.e., `slink'). These names stay the same during the development period and after the release; symbolic links, which can be changed, are made to indicate the currently released stable distribution. That's why the real distribution directories use the code names and symbolic links for stable, unstable, and frozen point to the appropriate release directories.


[back] [Copyright Notice] [Contents] [next]
Debian Developer's Reference
ver. 2.6.0, 11 February, 1999
Adam Di Carlo, current maintainer aph@debian.org
Christian Schwarz schwarz@debian.org
Ian Jackson ijackson@gnu.ai.mit.edu