policy/ap-pkg-binarypkg.rst

   1 Binary packages (from old Packaging Manual)
   2 ===========================================
   3
   4 See deb(5) and :ref:`s-pkg-controlarea`.
   5
   6 .. _s-pkg-bincreating:
   7
   8 Creating package files - ``dpkg-deb``
   9 -------------------------------------
  10
  11 All manipulation of binary package files is done by ``dpkg-deb``; it's
  12 the only program that has knowledge of the format. (``dpkg-deb`` may be
  13 invoked by calling ``dpkg``, as ``dpkg`` will spot that the options
  14 requested are appropriate to ``dpkg-deb`` and invoke that instead with
  15 the same arguments.)
  16
  17 In order to create a binary package, you must make a directory tree
  18 which contains all the files and directories you want to have in the
  19 file system data part of the package. In Debian-format source packages,
  20 this directory is usually either ``debian/tmp`` or ``debian/pkg``,
  21 relative to the top of the package's source tree.
  22
  23 They should have the locations (relative to the root of the directory
  24 tree you're constructing) ownerships and permissions which you want them
  25 to have on the system when they are installed.
  26
  27 With current versions of ``dpkg`` the uid/username and gid/groupname
  28 mappings for the users and groups being used should be the same on the
  29 system where the package is built and the one where it is installed.
  30
  31 You need to add one special directory to the root of the miniature file
  32 system tree you're creating: ``DEBIAN``. It should contain the control
  33 information files, notably the binary package control file (see
  34 :ref:`s-pkg-controlfile`).
  35
  36 The ``DEBIAN`` directory will not appear in the file system archive of
  37 the package, and so won't be installed by ``dpkg`` when the package is
  38 unpacked.
  39
  40 When you've prepared the package, you should invoke:
  41
  42 ::
  43
  44     dpkg --build directory
  45
  46 This will build the package in ``directory.deb``. (``dpkg`` knows that
  47 ``--build`` is a ``dpkg-deb`` option, so it invokes ``dpkg-deb`` with
  48 the same arguments to build the package.)
  49
  50 See the dpkg-deb(8) man page for details of how to examine the contents of
  51 this newly-created file. You may find the output of following commands
  52 enlightening:
  53
  54 ::
  55
  56     dpkg-deb --info filename.deb
  57     dpkg-deb --contents filename.deb
  58     dpkg --contents filename.deb
  59
  60 To view the copyright file for a package you could use this command:
  61
  62 ::
  63
  64     dpkg --fsys-tarfile filename.deb | tar xOf - --wildcards \*/copyright | pager
  65
  66 .. _s-pkg-controlarea:
  67
  68 Package control information files
  69 ---------------------------------
  70
  71 The control information portion of a binary package is a collection of
  72 files with names known to ``dpkg``. It will treat the contents of these
  73 files specially - some of them contain information used by ``dpkg`` when
  74 installing or removing the package; others are scripts which the package
  75 maintainer wants ``dpkg`` to run.
  76
  77 It is possible to put other files in the package control information
  78 file area, but this is not generally a good idea (though they will
  79 largely be ignored).
  80
  81 Here is a brief list of the control information files supported by
  82 ``dpkg`` and a summary of what they're used for.
  83
  84 ``control``
  85     This is the key description file used by ``dpkg``. It specifies the
  86     package's name and version, gives its description for the user,
  87     states its relationships with other packages, and so forth. See
  88     :ref:`s-sourcecontrolfiles` and
  89     :ref:`s-binarycontrolfiles`.
  90
  91     It is usually generated automatically from information in the
  92     source package by the ``dpkg-gencontrol`` program, and with
  93     assistance from ``dpkg-shlibdeps``. See :doc:`ap-pkg-sourcepkg`.
  94
  95 ``postinst``, ``preinst``, ``postrm``, ``prerm``
  96     These are executable files (usually scripts) which ``dpkg`` runs
  97     during installation, upgrade and removal of packages. They allow the
  98     package to deal with matters which are particular to that package or
  99     require more complicated processing than that provided by ``dpkg``.
 100     Details of when and how they are called are in
 101     :doc:`Package maintainer scripts and installation procedure <ch-maintainerscripts>`.
 102
 103     It is very important to make these scripts idempotent. See
 104     :ref:`s-idempotency`.
 105
 106     The maintainer scripts are not guaranteed to run with a controlling
 107     terminal and may not be able to interact with the user. See
 108     :ref:`s-controllingterminal`.
 109
 110 ``conffiles`` This file contains a list of configuration files which
 111     are to be handled automatically by ``dpkg`` (see
 112     :doc:`ap-pkg-conffiles`). Note that not necessarily every
 113     configuration file should be listed here.
 114
 115 ``shlibs``
 116     This file contains a list of the shared libraries supplied by the
 117     package, with dependency details for each. This is used by
 118     ``dpkg-shlibdeps`` when it determines what dependencies are required
 119     in a package control file. The ``shlibs`` file format is described
 120     on :ref:`s-shlibs`.
 121
 122 .. _s-pkg-controlfile:
 123
 124 The main control information file: ``control``
 125 ----------------------------------------------
 126
 127 The most important control information file used by ``dpkg`` when it
 128 installs a package is ``control``. It contains all the package's "vital
 129 statistics".
 130
 131 The binary package control files of packages built from Debian sources
 132 are made by a special tool, ``dpkg-gencontrol``, which reads
 133 ``debian/control`` and ``debian/changelog`` to find the information it
 134 needs. See :doc:`ap-pkg-sourcepkg` for more details.
 135
 136 The fields in binary package control files are listed in
 137 :ref:`s-binarycontrolfiles`.
 138
 139 A description of the syntax of control files and the purpose of the
 140 fields is available in
 141 :doc:`Control files and their fields <ch-controlfields>`.
 142
 143 .. _s-sB.4:
 144
 145 Time Stamps
 146 -----------
 147
 148 See :ref:`s-timestamps`.
 149