implement BuildProfileSpec support as dpkg has in 1.17.2

[apt.git] / doc / files.sgml

diff --git a/doc/files.sgml b/doc/files.sgml
index 82650a9bc01175a1b0009dcf380254e1d13305bd..56c7f574db6fa1f0f673f5c49b913bf1b85a34f2 100644 (file)
--- a/doc/files.sgml
+++ b/doc/files.sgml
@@ -1,10 +1,10 @@
-<!doctype debiandoc system>

 <!-- -*- mode: sgml; mode: fold -*- -->
 <!-- -*- mode: sgml; mode: fold -*- -->

+<!doctype debiandoc  PUBLIC  "-//DebianDoc//DTD DebianDoc//EN">

 <book>
 <title>APT Files</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>
 <book>
 <title>APT Files</title>
 
 <author>Jason Gunthorpe <email>jgg@debian.org</email></author>

-<version>$Id: files.sgml,v 1.9 2001/04/04 05:00:15 jgg Exp $</version>
+<version>$Id: files.sgml,v 1.12 2003/04/26 23:26:13 doogie Exp $</version>

 
 <abstract>
 This document describes the complete implementation and format of the 
 
 <abstract>
 This document describes the complete implementation and format of the 


@@ -21,8 +21,8 @@ by the Free Software Foundation; either version 2 of the License, or (at your
 option) any later version.
 
 <p>
 option) any later version.
 
 <p>

-For more details, on Debian GNU/Linux systems, see the file
-/usr/doc/copyright/GPL for the full license.
+For more details, on Debian systems, see the file
+/usr/share/common-licenses/GPL for the full license.

 </copyright>
 
 <toc sect>
 </copyright>
 
 <toc sect>


@@ -42,40 +42,68 @@ multiple package files.
 The var directory structure is as follows:
 <example>
   /var/lib/apt/
 The var directory structure is as follows:
 <example>
   /var/lib/apt/

-                 lists/
+               lists/

                       partial/
                       partial/

-                 xstatus
-                 userstatus
-                 cdroms.list
+               periodic/
+               extended_states
+               cdroms.list

   /var/cache/apt/
   /var/cache/apt/

-                  pkgcache.bin
-                 srcpkgcache.bin

                  archives/
                          partial/
                  archives/
                          partial/

+                 pkgcache.bin
+                 srcpkgcache.bin

   /etc/apt/
   /etc/apt/

-           sources.list
-          apt.conf
+           sources.list.d/
+           apt.conf.d/
+           preferences.d/
+           trusted.gpg.d/
+           sources.list
+           apt.conf
+           apt_preferences
+           trusted.gpg

   /usr/lib/apt/
   /usr/lib/apt/

-                methods/
-                      cdrom
-                      ftp
-                      http
-                      file
-                      gzip
-                      copy
+               methods/
+                        bzip2
+                        cdrom
+                        copy
+                        file
+                        ftp
+                        gpgv
+                        gzip
+                        http
+                        https
+                        lzma
+                        rred
+                        rsh
+                        ssh

 </example>
 
 <p>
 As is specified in the FHS 2.1 /var/lib/apt is used for application 
 data that is not expected to be user modified. /var/cache/apt is used
 for regeneratable data and is where the package cache and downloaded .debs
 </example>
 
 <p>
 As is specified in the FHS 2.1 /var/lib/apt is used for application 
 data that is not expected to be user modified. /var/cache/apt is used
 for regeneratable data and is where the package cache and downloaded .debs

-go.
+go. /etc/apt is the place where configuration should happen and
+/usr/lib/apt is the place where the apt and other packages can place
+binaries which can be used by the acquire system of APT.

 </sect>
                                                                   <!-- }}} -->
 
 <chapt>Files
 <!-- Distribution Source List                                         {{{ -->
 <!-- ===================================================================== -->
 </sect>
                                                                   <!-- }}} -->
 
 <chapt>Files
 <!-- Distribution Source List                                         {{{ -->
 <!-- ===================================================================== -->

+<sect>Files and fragment directories in /etc/apt
+
+<p>
+All files in /etc/apt are used to modify specific aspects of APT. To enable
+other packages to ship needed configuration herself all these files have
+a fragment directory packages can place their files in instead of mangling
+with the main files. The main files are therefore considered to be only
+used by the user and not by a package. The documentation omits this directories
+most of the time to be easier readable, so every time the documentation includes
+a reference to a main file it really means the file or the fragment directories.
+
+</sect>
+

 <sect>Distribution Source list (sources.list)
 
 <p>
 <sect>Distribution Source list (sources.list)
 
 <p>


@@ -90,86 +118,10 @@ fastest source listed first. The format of each line is:
 <p>
 The first item, <var>type</var>, indicates the format for the remainder 
 of the line. It is designed to indicate the structure of the distribution
 <p>
 The first item, <var>type</var>, indicates the format for the remainder 
 of the line. It is designed to indicate the structure of the distribution

-the line is talking about. Currently the only defined value is <em>deb</em>
-which indicates a standard debian archive with a dists dir.
-
-<sect1>The deb Type
-   <p>
-   The <em>deb</em> type is to be a typical two level debian distributions,
-   dist/<var>distribution</var>/<var>component</var>. Typically distribution
-   is one of stable, unstable or frozen while component is one of main, 
-   contrib, non-free or non-us. The format for the deb line is as follows:
-
-   <p>
-   deb <var>uri</var> <var>distribution</var> <var>component</var> 
-   [<var>component</var> ...]
-
-   <p>
-   <var>uri</var> for the <em>deb</em> type must specify the base of the 
-   debian distribution. APT will automatically generate the proper longer 
-   URIs to get the information it needs. <var>distribution</var> can specify
-   an exact path, in this case the components must be omitted and
-   <var>distribution</var> must end in a slash.
-   
-   <p>
-   Since only one distribution can be specified per deb line it may be
-   necessary to list a number of deb lines for the same URI. APT will
-   sort the URI list after it has generated a complete set to allow 
-   connection reuse. It is important to order things in the sourcelist
-   from most preferred to least preferred (fastest to slowest).
-</sect1>
-
-<sect1>URI specification
-<p> 
-URIs in the source list support a large number of access schemes.
-
-<taglist>
-<tag>cdrom<item>
-   The cdrom scheme is special in that If Modified Since queries are never
-   performed and that APT knows how to match a cdrom to the name it
-   was given when first inserted. APT also knows all of the possible 
-   mount points the cdrom drives and that the user should be prompted
-   to insert a CD if it cannot be found. The path is relative to an 
-   arbitrary mount point (of APT's choosing) and must not start with a 
-   slash. The first pathname component is the given name and is purely
-   descriptive and of the users choice. However, if a file in the root of 
-   the cdrom is called '.disk/info' its contents will be used instead of 
-   prompting. The name serves as a tag for the cdrom and should be unique.
-   <example>
-   cdrom:Debian 1.3/debian
-   </example>
-
-<tag>http<item>
-   This scheme specifies a HTTP server for the debian archive. HTTP is preferred
-   over FTP because If Modified Since queries against the Package file are
-   possible as well as deep pipelining and resume capabilities.
-   <example>
-   http://www.debian.org/archive
-   </example>
-
-<tag>ftp<item>
-   This scheme specifies a FTP connection to the server. FTP is limited because
-   there is no support for IMS and is hard to proxy over firewalls.
-   <example>
-   ftp://ftp.debian.org/debian
-   </example>
-
-<tag>file<item>
-   The file scheme allows an arbitrary directory in the file system to be 
-   considered as a debian archive. This is useful for NFS mounts and 
-   local mirrors/archives.
-   <example>
-   file:/var/debian
-   </example>
-   
-<tag>smb<item>
-   A possible future expansion may be to have direct support for smb (Samba 
-   servers).
-   <example>
-   smb://ftp.kernel.org/pub/mirrors/debian
-   </example>
-</taglist>
-</sect1>
+the line is talking about. Currently the only defined values are <em>deb</em>
+and <em>deb-src</em> which indicate a standard debian (source) archive with a
+dists directory. More about these types and the URI specification can be found
+in the sources.list manpage.

 
 <sect1>Hashing the URI
 <p>
 
 <sect1>Hashing the URI
 <p>


@@ -201,38 +153,31 @@ here as well.
 
 </sect>
                                                                   <!-- }}} -->
 
 </sect>
                                                                   <!-- }}} -->

-<!-- Extra Status                                                     {{{ -->
+<!-- Extended Status                                                  {{{ -->

 <!-- ===================================================================== -->
 <!-- ===================================================================== -->

-<sect>Extra Status File (xstatus)
+<sect>Extended States File (extended_states)

 
 <p>
 
 <p>

-The extra status file serves the same purpose as the normal dpkg status file
+The extended_states file serves the same purpose as the normal dpkg status file

 (/var/lib/dpkg/status) except that it stores information unique to apt.
 (/var/lib/dpkg/status) except that it stores information unique to apt.

-This includes the autoflag, target distribution and version and any other
-unique features that come up over time. It duplicates nothing from the normal
+This includes currently only the autoflag but is open to store more
+unique data that come up over time. It duplicates nothing from the normal

 dpkg status file.  Please see other APT documentation for a discussion
 dpkg status file.  Please see other APT documentation for a discussion

-of the exact internal behaviour of these fields. The Package field is
-placed directly before the new fields to indicate which package they
-apply to. The new fields are as follows:
+of the exact internal behavior of these fields. The Package and the
+Architecture field are placed directly before the new fields to indicate
+which package they apply to. The new fields are as follows:

 
 <taglist>
 
 <taglist>

-<tag>X-Auto<item>
-   The Auto flag can be Yes or No and controls whether the package is in
-   auto mode. 
-
-<tag>X-TargetDist<item>
-   The TargetDist item indicates which distribution versions are offered for
-   installation from. It should be stable, unstable or frozen.
-   
-<tag>X-TargetVersion<item>
-   The target version item is set if the user selects a specific version, it
-   overrides the TargetDist selection if both are present.
+<tag>Auto-Installed<item>
+   The Auto flag can be 1 (Yes) or 0 (No) and controls whether the package
+   was automatical installed to satisfy a dependency or if the user requested
+   the installation

 </taglist>
 </sect>
                                                                   <!-- }}} -->
 <!-- Binary Package Cache                                             {{{ -->
 <!-- ===================================================================== -->
 </taglist>
 </sect>
                                                                   <!-- }}} -->
 <!-- Binary Package Cache                                             {{{ -->
 <!-- ===================================================================== -->

-<sect>Binary Package Cache (pkgcache.bin)
+<sect>Binary Package Cache (srcpkgcache.bin and pkgcache.bin)

 
 <p>
 Please see cache.sgml for a complete description of what this file is. The 
 
 <p>
 Please see cache.sgml for a complete description of what this file is. The 


@@ -256,7 +201,7 @@ from partial into archives/. Any files found in archives/ can be assumed
 to be verified.
 
 <p>
 to be verified.
 
 <p>

-No directory structure is transfered from the receiving site and all .deb
+No directory structure is transferred from the receiving site and all .deb

 file names conform to debian conventions. No short (msdos) filename should
 be placed in archives. If the need arises .debs should be unpacked, scanned
 and renamed to their correct internal names. This is mostly to prevent
 file names conform to debian conventions. No short (msdos) filename should
 be placed in archives. If the need arises .debs should be unpacked, scanned
 and renamed to their correct internal names. This is mostly to prevent


@@ -278,69 +223,27 @@ The Methods directory is more fully described in the APT Methods interface
 document.
 </sect>
                                                                   <!-- }}} -->
 document.
 </sect>
                                                                   <!-- }}} -->

-<!-- The Mirror List                                                  {{{ -->
+<!-- The Configuration File                                           {{{ -->

 <!-- ===================================================================== -->
 <!-- ===================================================================== -->

-<sect> The Mirror List
+<sect> The Configuration File (/etc/apt/apt.conf)

 
 <p>
 
 <p>

-The mirror list is stored on the primary debian web server (www.debian.org)
-and contains a machine readable list of all known debian mirrors. It's 
-format and style mirror the Package file.
-
-<taglist>
-<tag>Site<item>
-This is the proper host name of the site. It should not be a host within
-debian.org and generally cnames should be avoided here.
-
-<tag>Aliases<item>
-These list any commonly used aliases for the site. This field is used to make
-sure that a site is not added twice.
-
-<tag>Type<item>
-This field can either be <em>Push-Primary</> or <em>leaf</>. 
-<em>Push-Primary</> are authorized top level mirrors of the archive, all 
-other mirrors are leaf. 
-
-<tag>Archive-[access]<item>
-The Archive field gives the path(s) to the debian archive. [access] 
-specifies the access method and may be one of ftp, http, rsync, nfs, or
-smb. For many of the types it is possible to prefix the path with :###
-indicating that an alternate port should be used. Generally paths
-start with a / and end with a /, rsync is an exception in that the
-first directory component is not a path but a label.
-
-<tag>WWW-[access]<item>
-The WWW field gives the path(s) to the debian web site.
-
-<tag>CDImage-[access]<item>
-The WWW field gives the path(s) to the debian CD-ROM images
-
-<tag>Incoming-[access]<item>
-The Incoming field gives the path(s) to a mirror of the debian incoming
-directory.
-
-<tag>nonUS-[access]<item>
-The nonUS field gives the path(s) to a mirror of the non-US distribution.
-
-<tag>Maintainer<item>
-This is the email address of the maintainer of the mirror.
-
-<tag>Location<item>
-Location gives the general geographical region the mirror is in.
-
-<tag>Sponsor<item>
-The Sponsor field indicates who owns the mirror and a URL to a web page
-describing the organization.
-
-<tag>Comment<item>
-General free-form text.
-
-</taglist>
+The configuration file (and the associated fragments directory
+/etc/apt/apt.conf.d/) is described in the apt.conf manpage.
+</sect>
+                                                                  <!-- }}} -->
+<!-- The trusted.gpg File                                             {{{ -->
+<!-- ===================================================================== -->
+<sect> The trusted.gpg File (/etc/apt/trusted.gpg)

 
 <p>
 
 <p>

-Some form of network measurement will have to be used to gauge performance
-of each of the mirrors. This will be discussed later, initial versions
-will use the first found URI.
+The trusted.gpg file (and the files in the associated fragments directory
+/etc/apt/trusted.gpg.d/) is a binary file including the keyring used
+by apt to validate that the information (e.g. the Release file) it
+downloads are really from the distributor it clams to be and is
+unmodified and is therefore the last step in the chain of trust between
+the archive and the end user. This security system is described in the
+apt-secure manpage.

 </sect>
                                                                   <!-- }}} -->
 <!-- The Release File                                                 {{{ -->
 </sect>
                                                                   <!-- }}} -->
 <!-- The Release File                                                 {{{ -->


@@ -348,7 +251,7 @@ will use the first found URI.
 <sect> The Release File
 
 <p>
 <sect> The Release File
 
 <p>

-This file plays and important role in how APT presents the archive to the 
+This file plays an important role in how APT presents the archive to the 

 user. Its main purpose is to present a descriptive name for the source
 of each version of each package. It also is used to detect when new versions
 of debian are released. It augments the package file it is associated with 
 user. Its main purpose is to present a descriptive name for the source
 of each version of each package. It also is used to detect when new versions
 of debian are released. It augments the package file it is associated with