path: root/greek/devel/buildd/wanna-build-states.wml

#use wml::debian::template title="Wanna-build states: an explanation" BARETITLE="true"
#use wml::debian::translation-check translation="b8114b588961778dbd04974c1464a2f388a90c28" maintainer="galaxico"

    <p>This page tries to explain what every wanna-build state means
      and what will happen to a package when it's in that state. Its
      target audience are Debian package maintainers that try to
      understand why their package has, or has not, been built for a
      specific architecture. Also, an explanation of the different log
      results is given.</p>

    <p>Finally, a flowchart version of the wanna-build states is
      <a href="#graphlink">available</a>, but do note that it doesn't talk
      about everything mentioned in this document.</p>

<h2>The wanna-build states</h2>
<p>For every Debian-supported architecture, there's a wanna-build
database installed on buildd.debian.org, with all packages and their current
compilation state. There are 8 states: <em>needs-build</em>,
<em>building</em>, <em>uploaded</em>, <em>dep-wait</em>,
<em>BD-Uninstallable</em>, <em>failed</em>, <em>not-for-us</em>, and
<em>installed</em>.</p>

<p>Their meaning is as follows:</p>
    <dl>
      <dt><a name="needs-build">needs-build</a></dt>
      <dd>A package marked <em>needs-build</em> has seen an upload of
	a new version by its maintainer, but for a different
	architecture than the one this wanna-build database is for; as
	such, it needs a rebuild. If the state is
	<em>needs-build</em>, it has not been picked up by an
	autobuilder yet, but it will be (once one is available at a
	time the specific package is near the top of the list). People
	commonly say <q>a package is queued for rebuild</q> when they are
	talking about a package in the <em>needs-build</em> state.<br />
	It may be interesting to note that the <em>needs-build</em>
	queue is not a FIFO queue; rather, the ordering used is based
	on the following criteria:
	<ol>
	  <li>Packages' previous compilation states; packages that
	    have been built previously are given priority over new
	    packages.
	  </li>
	  <li>priorities (packages with <em>required</em> priority are
	    built before packages with <em>extra</em> priority)
	  </li>
	  <li>The section a package is in. This ordering is based on what
	    packages are deemed more important; e.g., section <em>games</em> is
	    built after section <em>base</em>, and section <em>libs</em> is
	    built before <em>devel</em>.
	  </li>
	  <li>an asciibetical ordering on the package name.</li>
	</ol>
	Additionally, under certain conditions, it may happen that a buildd
	will not take packages at the head of the queue; for instance,
	when a buildd can't find the source of a given package, it will
	put it back in the queue (where it will then again be put at its
	previous position, i.e. the head of the queue), but it will
	ignore the package for a few hours. Another example where this
	might happen is when an architecture has multiple autobuilders;
	in that case, the architecture's porters may choose to build
	larger packages on their faster autobuilders, and leave the
	smaller ones for the slower machines in the pool. A buildd can
	theoretically also explicitly request a different section ordering,
	but that is not usually done.<br />
	There could be other situations where the queue order seems to
	be ignored; but note that they are all exceptions.
      </dd>
      <dt><a name="building">building</a></dt>
      <dd>A package is marked <em>building</em> from the moment an
	autobuilder picks it from the top of the wanna-build queue
	until the moment the autobuilder admin replies to the log. As
	packages are not picked one by one, this means a package can
	be (and usually is) marked <em>building</em> before the build has
	actually started; however, as buildd builds packages in its
	local queue on a FIFO basis, it should not take too long
	anymore. Also, note that the state of a package is
	<strong>not</strong> modified once the build is complete; only
	when the autobuilder admin comes around to replying to the
	logs.</dd>
      <dt><a name="uploaded">uploaded</a></dt>
      <dd>When a build attempt was successful, a build log is sent to
	the autobuilder admin and to buildd.debian.org. The
	autobuilder maintainer will then sign the .changes file which
	is embedded in the build log, and send it to the
	autobuilder. In reaction, the autobuilder will upload the
	package and set its state to <em>uploaded</em>. As such, a
	package in this state can be found in the incoming queue
	(somewhere).<br />
	An autobuilder will not touch a package anymore once it's
	state is <em>uploaded</em>, at least not until the next upload
	or until a porter manually modifies the state of a package.
      </dd>
      <dt><a name="dep-wait">dep-wait</a></dt>
      <dd>When a package fails due to missing build-time dependencies,
	the autobuilder maintainer will send a mail to the
	autobuilder, instructing it to remove the package sources and
	to mark the package as <em>dep-wait</em> on the missing
	build-dependencies. A package in such a state will
	automatically, without human intervention, be marked
	needs-build once said dependencies are available.<br />
	Originally, a package had to see a build attempt before the
	maintainer would manually place it in the <em>dep-wait</em>
	state. However, in august 2005 some code was added to
	wanna-build which will make a package move from the <em><a
	href='#installed'>installed</a></em> state directly to the
	<em>dep-wait</em> state, if that is appropriate.<br />
	There are two specific cases in which it may happen that a
	package is marked dep-wait forever; these are when a typing
	error happened by specifying the <em>dep-wait</em> dependencies
	(so that the package is marked dep-wait on a package that does
	not and will not ever exist) and when a build-time dependency is
	declared on a package which is marked <em>not-for-us</em>, or
	which is in the <em>packages-arch-specific</em> list.<br />
	As an example to the latter, consider three packages: a package
	<tt>foo</tt>, which exists for <tt>i386</tt> only; a package
	<tt>bar</tt>, which exists for <tt>m68k</tt> only (and which roughly
	performs the same function); and a package <tt>baz</tt>, which can be
	built with one of <tt>foo</tt> or <tt>bar</tt>. Should the maintainer
	of the <tt>baz</tt> package forget to add <tt>bar</tt> to the
	Build-Depends, and should he or she add it when it is noticed that
	<tt>baz</tt> is <em>dep-wait</em>ing on a non-existing <tt>foo</tt> for
	<tt>m68k</tt>, then the <em>dep-wait</em> state for <tt>m68k</tt> will
	have to be manually lifted by the <tt>m68k</tt> porters.
      </dd>
      <dt><a name="bd-uninstallable">BD-Uninstallable</a></dt>
      <dd>During debconf9, <a
	href='https://lists.debian.org/debian-wb-team/2009/07/msg00089.html'>Joachim
	Breitner had the idea</a> of using edos-debcheck to verify
	build-dependency installability of packages that would otherwise
	go into state Needs-Build. At that point, wanna-build already
	had the ability to check the immediate availability of
	build-dependencies; but if a package couldn't be installed
	because it build-depends on a which depends on b which depends
	on c (&gt;=1.2.3) and c is still at version 1.2.2, this would
	not be detected, and the build would fail early because of
	unavailable build-dependencies. Figuring those out was a manual
	process for the buildd admin, and, usually, a lengthy one at
	that. With the BD-Uninstallable patch, this is no longer a
	problem. When your package is in BD-Uninstallable, it means one
	of the build-dependencies is not installable (either
	immediately, or because part of its dependency tree is not
	available). Unfortunately, the BD-Uninstallable patch does not
	provide information about which package, exactly, is missing;
	please use edos-debcheck to find out. This problem will,
	however, solve itself once the missing dependencies are indeed
	available, and at that point your package will automatically
	move to Needs-Build again.
      </dd>
      <dt><a name="wanna-build-state-failed">failed</a></dt>
      <dd>If a build attempt failed, and the autobuilder maintainer
	decides it is really a failure that should not be retried, a
	package is marked as <em>failed</em>. A package will not leave
	this state until a porter decides it should do so, or until a
	new version is available. However, when a new version of a
	package is available which was marked as <em>failed</em> in
	the previous version, the autobuilder will ask its admin
	whether or not the package should be retried; this is so that
	packages which will obviously fail again will not waste buildd
	time. Although failing a package before trying a build is
	hardly ever the right thing to do, the option is available to
	the autobuilder admin.<br />
	Note that a package will <strong>never</strong> be marked
	<em>failed</em> without human intervention.
      </dd>
      <dt><a name="not-for-us">not-for-us</a></dt>
      <dd>Certain specific packages are architecture-specific; for
	instance, <tt>lilo</tt>, an i386 boot loader, should not be
	rebuilt on alpha, m68k, or s390. However, <em>wanna-build</em>
	does not look at the control file of a package when creating its
	database; only at the packages' name and section, the previous
	build state, and its priority. As such, by the first upload of
	an architecture-specific package which should not be built on
	other architectures, a build attempt is tried none the less (but
	fails even before the build-time dependencies are downloaded
	and/or installed)<br />
	Since autobuilders should not waste time trying to build
	packages that aren't required for their architecture, there's
	need for a way to list packages for which even an attempt to
	build isn't required. The first solution to this problem was
	<em>not-for-us</em>; however, as that is difficult to
	maintain, <em>not-for-us</em> is deprecated nowadays;
	autobuilder maintainers should use
	<em>packages-arch-specific</em> instead, which is a list of
	packages specific to one or more architectures instead of a
	wanna-build state.<br />
	A package in <em>not-for-us</em> or
	<em>packages-arch-specific</em> will <strong>not</strong>
	leave this state automatically; if your package specifically
	excluded a given architecture in its control file previously,
	but now includes more architectures, it must be
	<strong>manually</strong> requeued.<br />
	If you ever find yourself in the position that you have to ask
	for this to happen, you can do so by asking the relevant buildd
	maintainer. They can be reached at $arch@buildd.debian.org.
      </dd>
      <dt><a name="installed">installed</a></dt>
      <dd>As the name suggests, a package marked <em>installed</em> is
	compiled for the architecture the wanna-build database is
	for. Before Woody was released, a package's state changed from
	<em>uploaded</em> to <em>installed</em> after the daily katie
	runs. With the implementation of <a
	  href="https://lists.debian.org/debian-devel-announce/2002/debian-devel-announce-200206/msg00002.html">Accepted-autobuild</a>,
	however, this is no longer true; nowadays, a package goes
	from state <em>uploaded</em> to <em>installed</em> when it is
	accepted into the archive. This means that a package is
	usually marked <em>installed</em> after 15 minutes, on
	average.
      </dd>
    </dl>
    <p>In addition to these eight states, <em>wanna-build</em> also
    knows two -removed states, which are really corner cases. These
    two states are <em>dep-wait-removed</em> and
    <em>failed-removed</em>. They relate to their respective <q>plain</q>
    state as follows: when a package in state <em>failed</em> or
    <em>dep-wait</em> doesn't appear in a new Packages file which is
    fed to <em>wanna-build</em> &ndash; when it appears it has been
    removed &ndash; the information about that package isn't thrown
    away, as it could be that the package not appearing in the
    Packages file is just a temporary glitch, or that the package is
    temporarily removed for some reason (but that it will
    reappear in the archive, given time). Instead, in such a case, a
    package is moved to a <em>-removed</em> state, so that the
    information on why it failed or what it's waiting for can be
    retained. Should the package reappear in a following Packages file
    which is fed to wanna-build, it will then be moved from
    <em>failed-removed</em> back to <em>failed</em>, or from
    <em>dep-wait-removed</em> back to <em>dep-wait</em> before further
    processing.</p>
    <p>
      It is not possible to access the wanna-build database directly;
      this database is installed on ftp-master.debian.org, which is a
      restricted host, and only autobuilders have an SSH key which
      allows them to access the wanna-build database of their
      architecture.  This has been the case even before ftp-master was
      restricted; As wanna-build does a database-level lock when
      accessing, even reading, the data, you had to be in the right
      group (wb-&lt;arch&gt;) to be able to directly access a
      wanna-build database.
    </p>
    <p>That said, you can see what state a package is in by
      going to <a href="https://buildd.debian.org/stats/">the buildd
	stats page</a>, except if it is in state <em>installed</em>
	(well, not unless you don't mind digging through the
	multi-megabytes "&lt;arch&gt;-all.txt" files...).
    </p>
    <h2>The build log results</h2>
    <p>
      When a package is built by sbuild (the buildd component which
      does the actual building), a log with the build result is sent,
      by mail, to the autobuilder admin and to logs@buildd.debian.org
      (so that it can end up at https://buildd.debian.org). The build
      log result can be one of <em>successful</em>, <em>attempted</em> (previously
      known as <em>failed</em>),
      <em>given-back</em>, or <em>skipped</em>. Note that, at <a
      href="https://buildd.debian.org/">the buildd log overview
      page</a>, the prefix <em>maybe-</em> is added, because among
      other things, the fact that a build can be marked
      <em>failed</em> there for things that aren't <em>really</em> a
      failure has caused confusion in the past (or, the other way around,
      sometimes a package which apparently built successful is really broken
      and needs to be rebuilt).</p>
    <p>The meaning of
      the log results is as follows:</p>
    <dl>
      <dt><a name="successful">successful</a></dt>
      <dd>The build was successful. When the autobuilder maintainer
	receives this log, he will extract the embedded
	<code>.changes</code> file, sign it, and send it back to the
	autobuilder, which will cause the package to be uploaded.</dd>
      <dt><a name="failed">attempted</a> (previously: failed)</dt>
      <dd>The build exited with a non-zero exit state, indicating it probably
	failed. As there can be a number of reasons why a build fails,
	enumerating all them would be tedious, so no attempt is done here. If a
	package of yours is marked <em>(maybe-)failed</em>, you will want to
	read the above, and check its current wanna-build state.
      </dd>
      <dt><a name="given-back">given-back</a></dt>
      <dd>The build failed due to a temporary problem with the
	autobuilder; examples include network problems, the
	unavailability of the packages' source with the current
	sources.list, low disk space, and others.<br />
	A package which is <em>given-back</em> is marked as
	<em><a href="#needs-build">needs-build</a></em> again; as
	such, it will be automatically picked up by a different
	autobuilder once one is ready.
      </dd>
      <dt><a name="skipped">skipped</a></dt>
      <dd>In the time between the package was picked by the/an
	autobuilder and marked <em><a
	    href="#building">building</a></em> and the build attempt, a new
	    version for this package was uploaded, or a porter manually
	    modified the wanna-build state for another reason. When that is
	    done, a mail is sent to the autobuilder, which will mark the
	    package as not to be built; sbuild sees this, and will skip the
	    build (although a build log with this result is sent, describing
	    the fact that this happened).
      </dd>
    </dl>

<h2><a name="graphlink">The graphical version</a></h2>
<p>To illustrate the above, we have also provided a <a
href="wanna-build.png">flowchart-version</a> of this procedure. Again, note
that it does not contain everything mentioned in this document.
</p>