botch-doc 0.16-2ubuntu2 / usr / share / doc / botch / wiki / FirstSteps.html

<h1>First steps</h1>

<p>Because there was no dose3 upstream release since January 2013, botch needs some features of dose3 which are only available via git. Dose3 itself can only release a new version once a new upstream version of libcudf is released. So dose3 depends on the git version of libcudf as well.</p>

<p>To check out the dose submodule you need git. To check out the libcudf submodule you need ca-certificates.</p>

<pre><code>$ apt-get install git ca-certificates
$ git clone https://gitlab.mister-muffin.de/debian-bootstrap/botch.git
$ cd botch
$ git submodule update --init
$ (cd dose; git submodule update --init;)
</code></pre>

<p>You now can install all dependencies to build libcudf, dose3 and botch:</p>

<pre><code>$ apt-get install build-essential ocaml-nox camlp4 libzip-ocaml-dev libbz2-ocaml-dev ocaml-findlib libextlib-ocaml-dev libre-ocaml-dev libocamlgraph-ocaml-dev
$ make doselib
$ apt-get install libatdgen-ocaml-dev libxmlm-ocaml-dev
$ make
$ apt-get install zutils dctrl-tools wget python python-apt python-networkx
$ ./native.sh
</code></pre>

<p>Botch is a set of tools which are concatenated in a meaningful manner by <code>./native.sh</code>. The result of above invocation will be:</p>

<ul>
<li>the files <code>buildgraph.xml</code> and <code>srcgraph.xml</code> which are the buildgraph and sourcegraph in graphml format for the current dependency situation</li>
<li>several graphs in graphml format <code>cyclic_src*_*.xml</code> representing the strongly connected components before any dependencies were dropped</li>
<li>a file <code>stats.json</code> containing the results of running several heuristics on the cyclic graph that help to make the graph acyclic</li>
<li>a file <code>stats.html</code> which contains the information of <code>stats.json</code> in human readable format</li>
<li>a file <code>remove.list</code> which contains a close to minimal selection (a feedback arc set) of build dependencies which have to be dropped in addition to the known droppable ones (given by files in the <code>./droppable</code> directory) to make the graph acyclic</li>
<li>a file <code>feedback_vertex_set.list</code> which contains a close to minimal selection (a feedback vertex set) of source packages which were selected to be profile built according to the information in <code>./droppable</code> and <code>remove.list</code> to make the graph acyclic</li>
<li>the files <code>order1.lst</code> and <code>order2.lst</code> which contain the resulting build order to bootstrap the whole distribution</li>
</ul>

<p>The <code>./native.sh</code> script makes the assumption that a minimal build system including <code>Essential:yes</code> packages, <code>build-essential</code> and <code>debhelper</code> exists. Look at the <code>--help</code> output for more options. Investigate the script to see how it combines the multiple tools together.</p>

<p>You can also use graphviz to look at the graphs:</p>

<pre><code>$ apt-get install graphviz python-pygraphviz
$ ./tools/graphml2dot &lt; cyclic_src:foo_0.xml &gt; cyclic_src:foo_0.dot
$ dot -Tpng cyclic_src:foo_0.dot &gt; cyclic_src:foo_0.png
</code></pre>

<p>The number in the graph filename indicates the amount of vertices. Do not use <code>dot</code> to look at large graphs as computation can take hours. Furthermore, even after computation finished, the result will not be very useful due to the sheer amount of vertices and edges. If you nevertheless want to look at it, use <code>sfdp</code> instead.</p>

<p>Instead of looking at a huge graph you might want to look at the neighborhood of a specific node in the graph:</p>

<pre><code>$ ./tools/extract_neighborhood.py --depth=2 src:foo &lt; cyclic_src:foo_0.xml &gt; foo.xml
$ ./tools/graphml2dot &lt; foo.xml &gt; foo.dot
</code></pre>

<p>If that is still too much, try a transitive reduction of the graph (not unique if the graph has cycles):</p>

<pre><code>$ tred &lt; foo.dot &gt; foo_tred.dot
</code></pre>

<p>But instead of investigating the graph manually you should really look at and follow the calculated heuristics:</p>

<pre><code>$ iceweasel stats.html
</code></pre>