Move alternative init systems to avoid renumbering

[debian/debian-policy.git] / policy.sgml

diff --git a/policy.sgml b/policy.sgml
index fa1c39aca19f0e8e051179f648d35f0ebe1304d1..43926534da730cac53b3f8dcd6ae16b0e9f1f441 100644 (file)
--- a/policy.sgml
+++ b/policy.sgml
@@ -1988,51 +1988,33 @@ zope.
              </p>
            </item>
 
              </p>
            </item>
 

-           <tag><tt>build-arch</tt> (optional),
-                <tt>build-indep</tt> (optional)
+           <tag><tt>build-arch</tt> (required),
+                <tt>build-indep</tt> (required)

            </tag>
            <item>
              <p>
            </tag>
            <item>
              <p>

-               A package may also provide one or both of the targets
-               <tt>build-arch</tt> and <tt>build-indep</tt>.
-               The <tt>build-arch</tt> target, if provided, should
+               The <tt>build-arch</tt> target must

                perform all the configuration and compilation required for
                producing all architecture-dependant binary packages
                (those packages for which the body of the
                <tt>Architecture</tt> field in <tt>debian/control</tt> is
                not <tt>all</tt>).  Similarly, the <tt>build-indep</tt>
                perform all the configuration and compilation required for
                producing all architecture-dependant binary packages
                (those packages for which the body of the
                <tt>Architecture</tt> field in <tt>debian/control</tt> is
                not <tt>all</tt>).  Similarly, the <tt>build-indep</tt>

-               target, if provided, should perform all the configuration
+               target must perform all the configuration

                and compilation required for producing all
                architecture-independent binary packages (those packages
                for which the body of the <tt>Architecture</tt> field
                in <tt>debian/control</tt> is <tt>all</tt>).
                and compilation required for producing all
                architecture-independent binary packages (those packages
                for which the body of the <tt>Architecture</tt> field
                in <tt>debian/control</tt> is <tt>all</tt>).

-             </p>
-
-             <p>
-               If <tt>build-arch</tt> or <tt>build-indep</tt> targets are
-               provided in the rules file, the <tt>build</tt> target
+               The <tt>build</tt> target

                should either depend on those targets or take the same
                actions as invoking those targets would perform.<footnote>
                should either depend on those targets or take the same
                actions as invoking those targets would perform.<footnote>

-                 The intent of this split is so that binary-only builds
-                 need not install the dependencies required for
-                 the <tt>build-indep</tt> target.  However, this is not
-                 yet used in practice since <tt>dpkg-buildpackage
-                 -B</tt>, and therefore the autobuilders,
-                 invoke <tt>build</tt> rather than <tt>build-arch</tt>
-                 due to the difficulties in determining whether the
-                 optional <tt>build-arch</tt> target exists.
+                 This split allows binary-only builds to not install the
+                 dependencies required for the <tt>build-indep</tt>
+                 target and skip any resource-intensive build tasks that
+                 are only required when building architecture-independent
+                 binary packages.

                </footnote>
              </p>
 
                </footnote>
              </p>
 

-             <p>
-               If one or both of the targets <tt>build-arch</tt> and
-               <tt>build-indep</tt> are not provided, then invoking
-               <file>debian/rules</file> with one of the not-provided
-               targets as arguments should produce a exit status code
-               of 2.  Usually this is provided automatically by make
-               if the target is missing.
-             </p>
-

              <p>
                The <tt>build-arch</tt> and <tt>build-indep</tt> targets
                must not do anything that might require root privilege.
              <p>
                The <tt>build-arch</tt> and <tt>build-indep</tt> targets
                must not do anything that might require root privilege.


@@ -5646,7 +5628,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
        <p>
          To determine the <var>soversion</var>, look at
          the <tt>SONAME</tt> of the library, stored in the
        <p>
          To determine the <var>soversion</var>, look at
          the <tt>SONAME</tt> of the library, stored in the

-         ELF <tt>SONAME</tt> attribute.  it is usually of the
+         ELF <tt>SONAME</tt> attribute.  It is usually of the

          form <tt><var>name</var>.so.<var>major-version</var></tt> (for
          example, <tt>libz.so.1</tt>).  The version part is the part
          which comes after <tt>.so.</tt>, so in that example it
          form <tt><var>name</var>.so.<var>major-version</var></tt> (for
          example, <tt>libz.so.1</tt>).  The version part is the part
          which comes after <tt>.so.</tt>, so in that example it


@@ -6016,7 +5998,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
        </p>
 
        <p>
        </p>
 
        <p>

-         <file>shlibs<file> files also only support a limited range of
+         <file>shlibs</file> files also only support a limited range of

          library SONAMEs, making it difficult to use <file>shlibs</file>
          files in some unusual corner cases.<footnote>
            A <file>shlibs</file> file represents an SONAME as a library
          library SONAMEs, making it difficult to use <file>shlibs</file>
          files in some unusual corner cases.<footnote>
            A <file>shlibs</file> file represents an SONAME as a library


@@ -6238,9 +6220,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
          </p>
 
          <p>
          </p>
 
          <p>

-           A common example of when a change to the is required is a
-           function that takes an enum or struct argument that controls
-           what the function does.  For example:
+           A common example of when a change to the dependency version
+           is required is a function that takes an enum or struct
+           argument that controls what the function does.  For example:

            <example>
              enum library_op { OP_FOO, OP_BAR };
              int library_do_operation(enum library_op);
            <example>
              enum library_op { OP_FOO, OP_BAR };
              int library_do_operation(enum library_op);


@@ -6489,8 +6471,9 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
              recent version of the shared library that changed the
              behavior of that symbol, whether by adding it, changing its
              function signature (the parameters, their types, or the
              recent version of the shared library that changed the
              behavior of that symbol, whether by adding it, changing its
              function signature (the parameters, their types, or the

-             return type), or its behavior in a way that is visible to a
-             caller.  <var>id-of-dependency-template</var> is an optional
+             return type), or changing its behavior in a way that is
+             visible to a caller.
+             <var>id-of-dependency-template</var> is an optional

              field that references
              an <var>alternative-dependency-template</var>; see below for
              a full description.
              field that references
              an <var>alternative-dependency-template</var>; see below for
              a full description.


@@ -6798,7 +6781,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
              library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
              the <tt>shlibs</tt> entry for this library could say:
              <example compact="compact">
              library was in version <tt>1:1.2.3.3.dfsg-1</tt>, then
              the <tt>shlibs</tt> entry for this library could say:
              <example compact="compact">

-               libz 1 zlib1g (>= 1:1.2.3.3.dfsg-1)
+               libz 1 zlib1g (>= 1:1.2.3.3.dfsg)

              </example>
              This version restriction must be new enough that any binary
              built against the current version of the library will work
              </example>
              This version restriction must be new enough that any binary
              built against the current version of the library will work


@@ -6810,7 +6793,7 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
              As zlib1g also provides a udeb containing the shared
              library, there would also be a second line:
              <example compact="compact">
              As zlib1g also provides a udeb containing the shared
              library, there would also be a second line:
              <example compact="compact">

-               udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg-1)
+               udeb: libz 1 zlib1g-udeb (>= 1:1.2.3.3.dfsg)

              </example>
            </p>
          </sect2>
              </example>
            </p>
          </sect2>


@@ -6961,6 +6944,12 @@ Built-Using: grub2 (= 1.99-9), loadlin (= 1.6e-1)
                  in <file>/run</file> should be stored on a temporary
                  file system.
                </p>
                  in <file>/run</file> should be stored on a temporary
                  file system.
                </p>

+               <p>
+                 Packages must not assume the <file>/run</file>
+                 directory exists or is usable without a dependency
+                 on <tt>initscripts (>= 2.88dsf-13.3)</tt> until the
+                 stable release of Debian supports <file>/run</file>.
+               </p>

              </item>
               <item>
                 <p>
              </item>
               <item>
                 <p>


@@ -8289,6 +8278,74 @@ exec /usr/lib/foo/foo "$@"
        </p>
       </sect>
 
        </p>
       </sect>
 

+      <sect id="alternateinit">
+        <heading>Alternate init systems</heading>
+        <p>
+          A number of other init systems are available now in Debian that
+          can be used in place of <package>sysvinit</package>.  Alternative
+          init implementations must support running SysV init scripts as
+          described at <ref id="sysvinit"> for compatibility.
+        </p>
+        <p>
+          Packages may integrate with these replacement init systems by
+          providing implementation-specific configuration information about
+          how and when to start a service or in what order to run certain
+          tasks at boot time.  However, any package integrating with other
+          init systems must also be backwards-compatible with
+          <package>sysvinit</package> by providing a SysV-style init script
+          with the same name as and equivalent functionality to any
+          init-specific job, as this is the only start-up configuration
+          method guaranteed to be supported by all init implementations.  An
+          exception to this rule is scripts or jobs provided by the init
+          implementation itself; such jobs may be required for an
+          implementation-specific equivalent of the <file>/etc/rcS.d/</file>
+          scripts and may not have a one-to-one correspondence with the init
+          scripts.
+        </p>
+        <sect1 id="upstart">
+          <heading>Event-based boot with upstart</heading>
+
+         <p>
+            Packages may integrate with the <prgn>upstart</prgn> event-based
+            boot system by installing job files in the
+            <file>/etc/init</file> directory.  SysV init scripts for which
+            an equivalent upstart job is available must query the output of
+            the command <prgn>initctl version</prgn> for the string
+            <tt>upstart</tt> and avoid running in favor of the native
+            upstart job, using a test such as this:
+           <example compact="compact">
+if [ "$1" = start ] && which initctl >/dev/null && initctl version | grep -q upstart
+then
+       exit 1
+fi
+           </example>
+          </p>
+          <p>
+            Because packages shipping upstart jobs may be installed on
+            systems that are not using upstart, maintainer scripts must
+            still use the common <prgn>update-rc.d</prgn> and
+            <prgn>invoke-rc.d</prgn> interfaces for configuring runlevels
+            and for starting and stopping services.  These maintainer
+            scripts must not call the upstart <prgn>start</prgn>,
+            <prgn>restart</prgn>, <prgn>reload</prgn>, or <prgn>stop</prgn>
+            interfaces directly.  Instead, implementations of
+            <prgn>invoke-rc.d</prgn> must detect when upstart is running and
+            when an upstart job with the same name as an init script is
+            present, and perform the requested action using the upstart job
+            instead of the init script.
+          </p>
+          <p>
+            Dependency-based boot managers for SysV init scripts, such as
+            <prgn>startpar</prgn>, may avoid running a given init script
+            entirely when an equivalent upstart job is present, to avoid
+            unnecessary forking of no-op init scripts.  In this case, the
+            boot manager should integrate with upstart to detect when the
+            upstart job in question is started or stopped to know when the
+            dependency has been satisfied.
+          </p>
+         </sect1>
+      </sect>
+

     </chapt>
 
 
     </chapt>