Next Previous Contents

2. Directory Structure

2.1 The Sources.list entry

The easiest way to understand the repository directory structure is to consider two typical lines in the /etc/apt/sources.list file:

deb http://chaos/debian    unstable    main local unofficial
    ------ base -------  distribution  ---- components -----

deb-src http://chaos/debian    unstable    main local unofficial
        ------ base -------  distribution  ---- components -----

deb  stable/non-US  main contrib
    ---------------- base ----------------  distribution   -components-

The base can be http:, ftp: or file: URI.

The distribution is usually stable, frozen or unstable for official Debian releases, but it can be anything. The distribution may specify multiple directory levels.

The component is usually main, contrib or non-free in official Debian releases. Other common components are local (for internal use only) and unofficial (for distribution). Again, this string can be anything.

2.2 Package directory structure

In the terminology of the prior section, each release directory will have the same layout:

----       ------------ ---------           /admin/binary-packages

If you still have questions about this layout, you should examine the official Debian repository at, or view the contents of any official Debian CD.

Directories which are empty (unsupported architectures, empty sections) can be omitted.

The appropiate subdirectory for all source and binary packages can be determined by examining the debian/control file. It is not uncommon for a single source package to produce binary packages

Binary packages

Binary packages are individiual files which end with .deb. They always follow a rigid naming convention: package-name_version_arch.deb.

If you are creating new packages, you should read the Debian Packaging manual. If you're only working with existing packages, the rest of this section should be enough to get you started.

The package name should only contain lower-case letters, numbers, and a few punctuation characters. It can never include an underscore.

The version indicates the version of the upstream source and the version of the Debian packaging, separated by a hyphen.

The architecture indicates the type of processor (and operating system, for Hurd packages). If the package does not contain compiled executables, e.g., only documentation or Perl modules, it will have an architecture of all.

The binary package itself is an ar(1) archive file. If you unpack it, you will find three standard items:

  • debian-binary - this file indicates the version number for the binary package, currently "2.0\n"
  • control.tar.gz - a compressed tarball which contains the "control" information for the package. This may include the "control" file (which specifies package dependencies), the "md5sums" file (which contains a list of all standard files), the "conffiles" file (which contains a list of all user-configurable files), pre- and post-installation instructions, etc.
  • data.tar.gz - a compress tarball which contains the contents of the package, relative to the root directory.
  • Once the repository is properly set up, you can install a binary package with apt-get install package-name.

    Source packages

    Source packages are two or three files. They always follow a rigid naming convention:

  • package-name_version.dsc
  • package-name_version.diff.gz
  • package-name_version.[orig.]tar.gz
  • The first two items use a version combining both upstream and Debian packaging information. The final item only uses the upstream version information.

    When the source package is unpacked, all Debian packaging instructions are located in the debian directory. The current best practice is for the source package to contain upstream tarballs and patch files; the actual source tree is only created when the package is built. This makes it easy for sites to localize packages but still track new upstream releases.

    Most packages have the source tree already unpacked. This is slightly easier to work with, but can make it nearly impossible to track upstream changes.

    Once the repository is properly set up, you can install and unpack a source package with apt-get source package-name.


    Each binary or source directory should also contain a Release file. It is a text file containing several fields: Archive (usually the distribution), Version, Component (usually the component), Origin, Label, and for binary package directories Architecture.

    2.3 Indices

    Once the package directory structure is set up and populated, we need to create the Packages.gz and Sources.gz files. This is done with the aid of one or more "override" files in the base/indices directory. There should be one file for each distribution and component, typically named override.distribution.component.

    The structure of the override file is simple: each line contains a space-delimited record about each binary package in the release and component. The columes are the name of the package, the priority (required, important, standard, optional or extra), and the section (admin, base, devel, etc.) The last item is also the subdirectory where the binary package is located.

    2.4 Pool

    During development, it is common to need to maintain multiple upstream versions of packages. These source packages are normally maintained in the "pool" directory: base/pool/component/first-letter/package-name. The first-letter is normally the first letter of the source package name, but library source packages are an exception. These packages are stored under libX, where X is the first letter after the lib prefix.

    2.5 Incoming

    If you are modifying or creating more than a few packages, you will probably want to use the Debian tools. You should create an "incoming" directory, base/incoming/, and "queue" directory, base/queue/, for these tools.

    2.6 Marginally useful script

    This basic script will generate the Packages.gz and Sources.gz files for a repository. You should call it with two arguments, the distribution and component.

    For clarity, this script does not include error handling.

    #  Generate "Packages.gz" files
    for i in i386 all
       (cd ${BASE} && \
       /usr/bin/dpkg-scanpackages dists/${DISTRIBUTION}/${COMPONENT}/binary-$i \
           ${OVERRIDE} |\
           gzip -9 > dists/${DISTRIBUTION}/${COMPONENT}/binary-$i/Packages.gz \
    (cd ${BASE}/dists/${DISTRIBUTION}/${COMPONENT} && \
       ln -sf binary-i386/Packages.gz . )
    #  Generate "Sources.gz" file
    (cd ${BASE} && \
    /usr/bin/dpkg-scansources dists/${DISTRIBUTION}/${COMPONENT}/$i \
        ${OVERRIDE} |\
        gzip -9 > dists/${DISTRIBUTION}/${COMPONENT}/$i/Sources.gz \
    (cd ${BASE}/dists/${DISTRIBUTION}/${COMPONENT} && \
       ln -sf source/Sources.gz . )

    Next Previous Contents