4 .. _s-standardsversion:
9 Source packages should specify the most recent version number of this
10 policy document with which your package complied when it was last
13 This information may be used to file bug reports automatically if your
14 package becomes too much out of date.
16 The version is specified in the ``Standards-Version`` control field. The
17 format of the ``Standards-Version`` field is described in
18 :ref:`s-f-Standards-Version`.
20 You should regularly, and especially if your package has become out of
21 date, check for the newest Policy Manual available and update your
22 package, if necessary. When your package complies with the new standards
23 you should update the ``Standards-Version`` source package field and
31 Source packages should specify which binary packages they require to be
32 installed or not to be installed in order to build correctly. For
33 example, if building a package requires a certain compiler, then the
34 compiler should be specified as a build-time dependency.
36 It is not necessary to explicitly specify build-time relationships on a
37 minimal set of packages that are always needed to compile, link and put
38 in a Debian package a standard "Hello World!" program written in C or
39 C++. The required packages are called *build-essential*, and an
40 informational list can be found in
41 ``/usr/share/doc/build-essential/list`` (which is contained in the
42 ``build-essential`` package). [#]_
44 When specifying the set of build-time dependencies, one should list only
45 those packages explicitly required by the build. It is not necessary to
46 list packages which are required merely because some other package in
47 the list of build-time dependencies depends on them. [#]_
49 If build-time dependencies are specified, it must be possible to build
50 the package and produce working binaries on a system with only essential
51 and build-essential packages installed and also those required to
52 satisfy the build-time relationships (including any implied
53 relationships). In particular, this means that version clauses should be
54 used rigorously in build-time relationships so that one cannot produce
55 bad or inconsistently configured packages when the relationships are
58 :doc:`Declaring relationships between packages <ch-relationships>`
59 explains the technical details.
63 Changes to the upstream sources
64 -------------------------------
66 If changes to the source code are made that are not specific to the
67 needs of the Debian system, they should be sent to the upstream authors
68 in whatever form they prefer so as to be included in the upstream
69 version of the package.
71 If you need to configure the package differently for Debian or for
72 Linux, and the upstream source doesn't provide a way to do so, you
73 should add such configuration facilities (for example, a new
74 ``autoconf`` test or ``#define``) and send the patch to the upstream
75 authors, with the default set to the way they originally had it. You can
76 then easily override the default in your ``debian/rules`` or wherever is
79 You should make sure that the ``configure`` utility detects the correct
80 architecture specification string (refer to
81 :ref:`s-arch-spec` for details).
83 If your package includes the scripts ``config.sub`` and
84 ``config.guess``, you should arrange for the versions provided by the
85 package autotools-dev be used instead (see autotools-dev documentation
86 for details how to achieve that). This ensures that these files can be
87 updated distribution-wide at build time when introducing new
90 If you need to edit a ``Makefile`` where GNU-style ``configure`` scripts
91 are used, you should edit the ``.in`` files rather than editing the
92 ``Makefile`` directly. This allows the user to reconfigure the package
93 if necessary. You should *not* configure the package and edit the
94 generated ``Makefile``! This makes it impossible for someone else to
95 later reconfigure the package without losing the changes you made.
99 Debian changelog: ``debian/changelog``
100 --------------------------------------
102 Every source package must include the Debian changelog file,
103 ``debian/changelog``. Changes in the Debian version of the package
104 should be briefly explained in this file. [#]_ This includes
105 modifications made in the Debian package compared to the upstream one
106 as well as other changes and updates to the package. [#]_
108 The format of the ``debian/changelog`` allows the package building tools
109 to discover which version of the package is being built and find out
110 other release-specific information.
112 That format is a series of entries like this:
116 package (version) distribution(s); urgency=urgency
117 [optional blank line(s), stripped]
120 [blank line(s), included in output of dpkg-parsechangelog]
121 * even more change details
122 [optional blank line(s), stripped]
123 -- maintainer name <email address>[two spaces] date
125 ``package`` and ``version`` are the source package name and version
128 ``distribution(s)`` lists the distributions where this version should
129 be installed when it is uploaded - it is copied to the
130 ``Distribution`` field in the ``.changes`` file. See
131 :ref:`s-f-Distribution`.
133 ``urgency`` is the value for the ``Urgency`` field in the ``.changes``
134 file for the upload (see :ref:`s-f-Urgency`). It is not possible to
135 specify an urgency containing commas; commas are used to separate
136 ``keyword=value`` settings in the ``dpkg`` changelog format (though
137 there is currently only one useful keyword, ``urgency``).
139 The change details may in fact be any series of lines starting with at
140 least two spaces, but conventionally each change starts with an asterisk
141 and a separating space and continuation lines are indented so as to
142 bring them in line with the start of the text above. Blank lines may be
143 used here to separate groups of changes, if desired.
145 If this upload resolves bugs recorded in the Bug Tracking System (BTS),
146 they may be automatically closed on the inclusion of this package into
147 the Debian archive by including the string: ``closes: Bug#nnnnn`` in
148 the change details. [#]_ This information is conveyed via the
149 ``Closes`` field in the ``.changes`` file (see
152 The maintainer name and email address used in the changelog should be
153 the details of the person who prepared this release of the package. They
154 are *not* necessarily those of the uploader or usual package maintainer.
155 [#]_ The information here will be copied to the ``Changed-By`` field
156 in the ``.changes`` file (see :ref:`s-f-Changed-By`), and
157 then later used to send an acknowledgement when the upload has been
160 The date has the following format [#]_ (compatible and with the same
161 semantics of RFC 2822 and RFC 5322):
165 day-of-week, dd month yyyy hh:mm:ss +zzzz
169 - ``day-of week`` is one of: Mon, Tue, Wed, Thu, Fri, Sat, Sun
171 - ``dd`` is a one- or two-digit day of the month (01-31)
173 - ``month`` is one of: Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct,
176 - ``yyyy`` is the four-digit year (e.g. 2010)
178 - ``hh`` is the two-digit hour (00-23)
180 - ``mm`` is the two-digit minutes (00-59)
182 - ``ss`` is the two-digit seconds (00-60)
184 - ``+zzzz`` or ``-zzzz`` is the time zone offset from Coordinated
185 Universal Time (UTC). "+" indicates that the time is ahead of
186 (i.e., east of) UTC and "-" indicates that the time is behind
187 (i.e., west of) UTC. The first two digits indicate the hour
188 difference from UTC and the last two digits indicate the number of
189 additional minutes difference from UTC. The last two digits must be
192 The first "title" line with the package name must start at the left hand
193 margin. The "trailer" line with the maintainer and date details must be
194 preceded by exactly one space. The maintainer details and the date must
195 be separated by exactly two spaces.
197 The entire changelog must be encoded in UTF-8.
199 For more information on placement of the changelog files within binary
200 packages, please see :ref:`s-changelogs`.
204 Copyright: ``debian/copyright``
205 -------------------------------
207 Every package must be accompanied by a verbatim copy of its copyright
208 information and distribution license in the file
209 ``/usr/share/doc/package/copyright`` (see
210 :ref:`s-copyrightfile` for further details). Also see
211 :ref:`s-pkgcopyright` for further considerations related
212 to copyrights for packages.
216 Error trapping in makefiles
217 ---------------------------
219 When ``make`` invokes a command in a makefile (including your package's
220 upstream makefiles and ``debian/rules``), it does so using ``sh``. This
221 means that ``sh``'s usual bad error handling properties apply: if you
222 include a miniature script as one of the commands in your makefile
223 you'll find that if you don't do anything about it then errors are not
224 detected and ``make`` will blithely continue after problems.
226 Every time you put more than one shell command (this includes using a
227 loop) in a makefile command you must make sure that errors are trapped.
228 For simple compound commands, such as changing directory and then
229 running a program, using ``&&`` rather than semicolon as a command
230 separator is sufficient. For more complex commands including most loops
231 and conditionals you should include a separate ``set -e`` command at the start of every makefile command that's
232 actually one of these miniature shell scripts.
239 Maintainers should preserve the modification times of the upstream
240 source files in a package, as far as is reasonably possible. [#]_
244 Restrictions on objects in source packages
245 ------------------------------------------
247 The source package may not contain any hard links, [#]_ device special
248 files, sockets or setuid or setgid files.. [#]_
252 Main building script: ``debian/rules``
253 --------------------------------------
255 This file must be an executable makefile, and contains the
256 package-specific recipes for compiling the package and building binary
257 package(s) from the source.
259 It must start with the line ``#!/usr/bin/make -f``, so that it can be
260 invoked by saying its name rather than invoking ``make`` explicitly.
261 That is, invoking either of ``make -f debian/rules args...`` or ``./debian/rules args...`` must result in identical behavior.
263 The following targets are required and must be implemented by
264 ``debian/rules``: ``clean``, ``binary``, ``binary-arch``,
265 ``binary-indep``, ``build``, ``build-arch`` and ``build-indep``. These
266 are the targets called by ``dpkg-buildpackage``.
268 Since an interactive ``debian/rules`` script makes it impossible to
269 auto-compile that package and also makes it hard for other people to
270 reproduce the same binary package, all required targets must be
271 non-interactive. It also follows that any target that these targets
272 depend on must also be non-interactive.
274 For packages in the main archive, no required targets may attempt
277 The targets are as follows:
280 The ``build`` target should perform all the configuration and
281 compilation of the package. If a package has an interactive
282 pre-build configuration routine, the Debian source package must
283 either be built after this has taken place (so that the binary
284 package can be built without rerunning the configuration) or the
285 configuration routine modified to become non-interactive. (The
286 latter is preferable if there are architecture-specific features
287 detected by the configuration routine.)
289 For some packages, notably ones where the same source tree is
290 compiled in different ways to produce two binary packages, the
291 ``build`` target does not make much sense. For these packages it is
292 good enough to provide two (or more) targets (``build-a`` and
293 ``build-b`` or whatever) for each of the ways of building the
294 package, and a ``build`` target that does nothing. The ``binary``
295 target will have to build the package in each of the possible ways
296 and make the binary package out of each.
298 The ``build`` target must not do anything that might require root
301 The ``build`` target may need to run the ``clean`` target first -
304 When a package has a configuration and build routine which takes a
305 long time, or when the makefiles are poorly designed, or when
306 ``build`` needs to run ``clean`` first, it is a good idea to
307 ``touch build`` when the build process is complete. This will ensure
308 that if ``debian/rules build`` is run again it will not rebuild the whole
311 ``build-arch`` (required), ``build-indep`` (required)
312 The ``build-arch`` target must perform all the configuration and
313 compilation required for producing all architecture-dependent binary
314 packages (those packages for which the body of the ``Architecture``
315 field in ``debian/control`` is not ``all``). Similarly, the
316 ``build-indep`` target must perform all the configuration and
317 compilation required for producing all architecture-independent
318 binary packages (those packages for which the body of the
319 ``Architecture`` field in ``debian/control`` is ``all``). The
320 ``build`` target should either depend on those targets or take the
321 same actions as invoking those targets would perform. [#]_
323 The ``build-arch`` and ``build-indep`` targets must not do anything
324 that might require root privilege.
326 ``binary`` (required), ``binary-arch`` (required), ``binary-indep`` (required)
327 The ``binary`` target must be all that is necessary for the user to
328 build the binary package(s) produced from this source package. It is
329 split into two parts: ``binary-arch`` builds the binary packages
330 which are specific to a particular architecture, and
331 ``binary-indep`` builds those which are not.
333 ``binary`` may be (and commonly is) a target with no commands which
334 simply depends on ``binary-arch`` and ``binary-indep``.
336 Both ``binary-*`` targets should depend on the ``build`` target, or
337 on the appropriate ``build-arch`` or ``build-indep`` target, so that
338 the package is built if it has not been already. It should then
339 create the relevant binary package(s), using ``dpkg-gencontrol`` to
340 make their control files and ``dpkg-deb`` to build them and place
341 them in the parent of the top level directory.
343 Both the ``binary-arch`` and ``binary-indep`` targets *must* exist.
344 If one of them has nothing to do (which will always be the case if
345 the source generates only a single binary package, whether
346 architecture-dependent or not), it must still exist and must always
349 The ``binary`` targets must be invoked as root. [#]_
351 ``clean`` (required) This must undo any effects that the ``build`` and ``binary`` targets
352 may have had, except that it should leave alone any output files
353 created in the parent directory by a run of a ``binary`` target.
355 If a ``build`` file is touched at the end of the ``build`` target,
356 as suggested above, it should be removed as the first action that
357 ``clean`` performs, so that running ``build`` again after an
358 interrupted ``clean`` doesn't think that everything is already done.
360 The ``clean`` target may need to be invoked as root if ``binary``
361 has been invoked since the last ``clean``, or if ``build`` has been
362 invoked as root (since ``build`` may create directories, for
365 The ``clean`` target cannot be used to remove files in the source
366 tree that are not compatible with the DFSG. This is because the
367 files would remain in the upstream tarball, and thus in the source
368 package, so the source package would continue to violate DFSG.
369 Instead, the upstream source should be repacked to remove those
372 ``get-orig-source`` (optional)
373 This target fetches the most recent version of the original source
374 package from a canonical archive site (via FTP or WWW, for example),
375 does any necessary rearrangement to turn it into the original source
376 tar file format described below, and leaves it in the current
379 This target may be invoked in any directory, and should take care to
380 clean up any temporary files it may have left.
382 This target is optional, but providing it if possible is a good
386 This target performs whatever additional actions are required to
387 make the source ready for editing (unpacking additional upstream
388 archives, applying patches, etc.). It is recommended to be
389 implemented for any package where ``dpkg-source -x`` does not result
390 in source ready for additional modification. See
391 :ref:`s-readmesource`.
393 The ``build``, ``binary`` and ``clean`` targets must be invoked with the
394 current directory being the package's top-level directory.
396 Additional targets may exist in ``debian/rules``, either as published or
397 undocumented interfaces or for the package's internal use.
399 The architectures we build on and build for are determined by ``make``
400 variables using the utility ``dpkg-architecture``. You can determine the
401 Debian architecture and the GNU style architecture specification string
402 for the build architecture as well as for the host architecture. The
403 build architecture is the architecture on which ``debian/rules`` is run
404 and the package build is performed. The host architecture is the
405 architecture on which the resulting package will be installed and run.
406 The target architecture is the architecture of the packages that the
407 compiler currently being built will generate. These are normally the
408 same, but may be different in the case of cross-compilation (building
409 packages for one architecture on machines of a different architecture),
410 building a cross-compiler (a compiler package that will generate objects
411 for one architecture, built on a machine of a different architecture) or
412 a Canadian cross-compiler (a compiler that will generate objects for one
413 architecture, built on a machine of a different architecture, that will
414 run on yet a different architecture).
416 Here is a list of supported ``make`` variables:
418 - ``DEB_*_ARCH`` (the Debian architecture)
420 - ``DEB_*_ARCH_CPU`` (the Debian CPU name)
422 - ``DEB_*_ARCH_BITS`` (the Debian CPU pointer size in bits)
424 - ``DEB_*_ARCH_ENDIAN`` (the Debian CPU endianness)
426 - ``DEB_*_ARCH_OS`` (the Debian System name)
428 - ``DEB_*_GNU_TYPE`` (the GNU style architecture specification string)
430 - ``DEB_*_GNU_CPU`` (the CPU part of ``DEB_*_GNU_TYPE``)
432 - ``DEB_*_GNU_SYSTEM`` (the System part of ``DEB_*_GNU_TYPE``)
434 where ``*`` is either ``BUILD`` for specification of the build
435 architecture, ``HOST`` for specification of the host architecture or
436 ``TARGET`` for specification of the target architecture.
438 Backward compatibility can be provided in the rules file by setting the
439 needed variables to suitable default values; please refer to the
440 documentation of ``dpkg-architecture`` for details.
442 It is important to understand that the ``DEB_*_ARCH`` string only
443 determines which Debian architecture we are building on or for. It
444 should not be used to get the CPU or system information; the
445 ``DEB_*_ARCH_CPU`` and ``DEB_*_ARCH_OS`` variables should be used for
446 that. GNU style variables should generally only be used with upstream
449 .. _s-debianrules-options:
451 ``debian/rules`` and ``DEB_BUILD_OPTIONS``
452 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
454 Supporting the standardized environment variable ``DEB_BUILD_OPTIONS``
455 is recommended. This variable can contain several flags to change how a
456 package is compiled and built. Each flag must be in the form flag or
457 flag=options. If multiple flags are given, they must be separated by
458 whitespace. [#]_ flag must start with a lowercase letter (``a-z``) and
459 consist only of lowercase letters, numbers (``0-9``), and the characters
460 ``-`` and ``_`` (hyphen and underscore). options must not contain
461 whitespace. The same tag should not be given multiple times with
462 conflicting values. Package maintainers may assume that
463 ``DEB_BUILD_OPTIONS`` will not contain conflicting tags.
465 The meaning of the following tags has been standardized:
468 This tag says to not run any build-time test suite provided by the
472 This tag says to skip any build steps that only generate package
473 documentation. Files required by other sections of Debian Policy,
474 such as copyright and changelog files, must still be generated and
475 put in the package, but other generated documentation such as
476 help2man-generated pages, Doxygen-generated API documentation, or
477 info pages generated from Texinfo sources should be skipped if
478 possible. This option does not change the set of binary packages
479 generated by the source package, but documentation-only binary
480 packages may be nearly empty when built with this option.
483 The presence of this tag means that the package should be compiled
484 with a minimum of optimization. For C programs, it is best to add
485 ``-O0`` to ``CFLAGS`` (although this is usually the default). Some
486 programs might fail to build or run at this level of optimization;
487 it may be necessary to use ``-O1``, for example.
490 This tag means that the debugging symbols should not be stripped
491 from the binary during installation, so that debugging information
492 may be included in the package.
495 This tag means that the package should be built using up to ``n``
496 parallel processes if the package build system supports this. [#]_
497 If the package build system does not support parallel builds, this
498 string must be ignored. If the package build system only supports a
499 lower level of concurrency than n, the package should be built using
500 as many parallel processes as the package build system supports. It
501 is up to the package maintainer to decide whether the package build
502 times are long enough and the package build system is robust enough
503 to make supporting parallel builds worthwhile.
505 Unknown flags must be ignored by ``debian/rules``.
507 The following makefile snippet is an example of how one may implement
508 the build options; you will probably have to massage this example in
509 order to make it work for your package.
515 INSTALL_FILE = $(INSTALL) -p -o root -g root -m 644
516 INSTALL_PROGRAM = $(INSTALL) -p -o root -g root -m 755
517 INSTALL_SCRIPT = $(INSTALL) -p -o root -g root -m 755
518 INSTALL_DIR = $(INSTALL) -p -d -o root -g root -m 755
520 ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
525 ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
526 INSTALL_PROGRAM += -s
528 ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
529 NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
530 MAKEFLAGS += -j$(NUMJOBS)
535 ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
536 # Code to run the package test suite.
541 Variable substitutions: ``debian/substvars``
542 --------------------------------------------
544 When ``dpkg-gencontrol`` generates :ref:`binary package control files
545 <s-binarycontrolfiles>` (``DEBIAN/control``), it performs variable
546 substitutions on its output just before writing it. Variable
547 substitutions have the form ``${variable}``. The optional file
548 ``debian/substvars`` contains variable substitutions to be used;
549 variables can also be set directly from ``debian/rules`` using the
550 ``-V`` option to the source packaging commands, and certain predefined
551 variables are also available.
553 The ``debian/substvars`` file is usually generated and modified
554 dynamically by ``debian/rules`` targets, in which case it must be
555 removed by the ``clean`` target.
557 See deb-substvars(5) for full details about source variable substitutions,
558 including the format of ``debian/substvars``.
562 Optional upstream source location: ``debian/watch``
563 ---------------------------------------------------
565 This is an optional, recommended configuration file for the ``uscan``
566 utility which defines how to automatically scan ftp or http sites for
567 newly available updates of the package. This is also used by some Debian
568 QA tools to help with quality control and maintenance of the
569 distribution as a whole.
571 If the upstream maintainer of the software provides OpenPGP signatures
572 for new releases, including the information required for ``uscan`` to
573 verify signatures for new upstream releases is also recommended. To do
574 this, use the ``pgpsigurlmangle`` option in ``debian/watch`` to specify
575 the location of the upstream signature, and include the key or keys used
576 to sign upstream releases in the Debian source package as
577 ``debian/upstream/signing-key.asc``.
579 For more information about ``uscan`` and these options, including how to
580 generate the file containing upstream signing keys, see uscan(1).
584 Generated files list: ``debian/files``
585 --------------------------------------
587 This file is not a permanent part of the source tree; it is used while
588 building packages to record which files are being generated.
589 ``dpkg-genchanges`` uses it when it generates a ``.changes`` file.
591 It should not exist in a shipped source package, and so it (and any
592 backup files or temporary files such as ``files.new``) [#]_ should be
593 removed by the ``clean`` target. It may also be wise to ensure a fresh
594 start by emptying or removing it at the start of the ``binary`` target.
596 When ``dpkg-gencontrol`` is run for a binary package, it adds an entry
597 to ``debian/files`` for the ``.deb`` file that will be created when
598 ``dpkg-deb --build`` is run for that binary package. So for most
599 packages all that needs to be done with this file is to delete it in the
602 If a package upload includes files besides the source package and any
603 binary packages whose control files were made with ``dpkg-gencontrol``
604 then they should be placed in the parent of the package's top-level
605 directory and ``dpkg-distaddfile`` should be called to add the file to
606 the list in ``debian/files``.
610 Convenience copies of code
611 --------------------------
613 Some software packages include in their distribution convenience copies
614 of code from other software packages, generally so that users compiling
615 from source don't have to download multiple packages. Debian packages
616 should not make use of these convenience copies unless the included
617 package is explicitly intended to be used in this way. [#]_ If the
618 included code is already in the Debian archive in the form of a library,
619 the Debian packaging should ensure that binary packages reference the
620 libraries already in Debian and the convenience copy is not used. If the
621 included code is not already in Debian, it should be packaged separately
622 as a prerequisite if possible. [#]_
626 Source package handling: ``debian/README.source``
627 -------------------------------------------------
629 If running ``dpkg-source -x`` on a source package doesn't produce the
630 source of the package, ready for editing, and allow one to make changes
631 and run ``dpkg-buildpackage`` to produce a modified package without
632 taking any additional steps, creating a ``debian/README.source``
633 documentation file is recommended. This file should explain how to do
634 all of the following:
636 1. Generate the fully patched source, in a form ready for editing, that
637 would be built to create Debian packages. Doing this with a ``patch``
638 target in ``debian/rules`` is recommended; see
639 `Main building script: debian/rules <#s-debianrules>`__.
641 2. Modify the source and save those modifications so that they will be
642 applied when building the package.
644 3. Remove source modifications that are currently being applied when
645 building the package.
647 4. Optionally, document what steps are necessary to upgrade the Debian
648 source package to a new upstream version, if applicable.
650 This explanation should include specific commands and mention any
651 additional required Debian packages. It should not assume familiarity
652 with any specific Debian packaging system or patch management tools.
654 This explanation may refer to a documentation file installed by one of
655 the package's build dependencies provided that the referenced
656 documentation clearly explains these tasks and is not a general
659 ``debian/README.source`` may also include any other information that
660 would be helpful to someone modifying the source package. Even if the
661 package doesn't fit the above description, maintainers are encouraged to
662 document in a ``debian/README.source`` file any source package with a
663 particularly complex or unintuitive source layout or build system (for
664 example, a package that builds the same source multiple times to
665 generate different binary packages).
670 Packages should build reproducibly, which for the purposes of this
671 document [#]_ means that given
673 - a version of a source package unpacked at a given path;
674 - a set of versions of installed build dependencies;
675 - a set of environment variable values;
676 - a build architecture; and
677 - a host architecture,
679 repeatedly building the source package for the build architecture on
680 any machine of the host architecture with those versions of the build
681 dependencies installed and exactly those environment variable values
682 set will produce bit-for-bit identical binary packages.
684 It is recommended that packages produce bit-for-bit identical binaries
685 even if most environment variables and build paths are varied. It is
686 intended for this stricter standard to replace the above when it is
687 easier for packages to meet it.
690 See the file ``upgrading-checklist`` for information about policy
691 which has changed between different versions of this document.
696 - This allows maintaining the list separately from the policy
697 documents (the list does not need the kind of control that the
698 policy documents do).
700 - Having a separate package allows one to install the
701 build-essential packages on a machine, as well as allowing other
702 packages such as tasks to require installation of the
703 build-essential packages using the depends relation.
705 - The separate package allows bug reports against the list to be
706 categorized separately from the policy management process in the
710 The reason for this is that dependencies change, and you should list
711 all those packages, and *only* those packages that *you* need
712 directly. What others need is their business. For example, if you
713 only link against ``libimlib``, you will need to build-depend on
714 libimlib2-dev but not against any ``libjpeg*`` packages, even though
715 ``libimlib2-dev`` currently depends on them: installation of
716 libimlib2-dev will automatically ensure that all of its run-time
717 dependencies are satisfied.
720 Mistakes in changelogs are usually best rectified by making a new
721 changelog entry rather than "rewriting history" by editing old
725 Although there is nothing stopping an author who is also the Debian
726 maintainer from using this changelog for all their changes, it will
727 have to be renamed if the Debian and upstream maintainers become
728 different people. In such a case, however, it might be better to
729 maintain the package as a non-native package.
732 To be precise, the string should match the following Perl regular
737 /closes:\s*(?:bug)?\#?\s?\d+(?:,\s*(?:bug)?\#?\s?\d+)*/i
739 Then all of the bug numbers listed will be closed by the archive
740 maintenance software (``dak``) using the version of the changelog
744 In the case of a sponsored upload, the uploader signs the files, but
745 the changelog maintainer name and address are those of the person who
746 prepared this release. If the preparer of the release is not one of
747 the usual maintainers of the package (as listed in the
748 :ref:```Maintainer`` <#s-f-Maintainer` or
749 ```Uploaders`` <s-f-Uploaders>` control fields of the package),
750 the first line of the changelog is conventionally used to explain why
751 a non-maintainer is uploading the package. The Debian Developer's
752 Reference (see :ref:`s-related`) documents the
755 .. [#] This is the same as the format generated by ``date
759 The rationale is that there is some information conveyed by knowing
760 the age of the file, for example, you could recognize that some
761 documentation is very old by looking at the modification time, so it
762 would be nice if the modification time of the upstream source would
766 This is not currently detected when building source packages, but
767 only when extracting them.
769 Hard links may be permitted at some point in the future, but would
770 require a fair amount of work.
773 Setgid directories are allowed.
776 Another common way to do this is for ``build`` to depend on
777 ``build-stamp`` and to do nothing else, and for the ``build-stamp``
778 target to do the building and to ``touch build-stamp`` on completion.
779 This is especially useful if the build routine creates a file or
780 directory called ``build``; in such a case, ``build`` will need to be
781 listed as a phony target (i.e., as a dependency of the ``.PHONY``
782 target). See the documentation of ``make`` for more information on
786 This split allows binary-only builds to not install the dependencies
787 required for the ``build-indep`` target and skip any
788 resource-intensive build tasks that are only required when building
789 architecture-independent binary packages.
792 The ``fakeroot`` package often allows one to build a package
793 correctly even without being root.
796 Some packages support any delimiter, but whitespace is the easiest to
797 parse inside a makefile and avoids ambiguity with flag values that
801 Packages built with ``make`` can often implement this by passing the
802 ``-j``\ n option to ``make``.
805 ``files.new`` is used as a temporary file by ``dpkg-gencontrol`` and
806 ``dpkg-distaddfile`` - they write a new version of ``files`` here
807 before renaming it, to avoid leaving a corrupted copy if an error
811 For example, parts of the GNU build system work like this.
814 Having multiple copies of the same code in Debian is inefficient,
815 often creates either static linking or shared library conflicts, and,
816 most importantly, increases the difficulty of handling security
817 vulnerabilities in the duplicated code.
820 This is Debian's precisification of the `reproducible-builds.org
821 definition <https://reproducible-builds.org/docs/definition/>`_.