ganeti-doc 2.16.0~rc2-1build1 / usr / share / doc / ganeti / html / devnotes.html

This file is indexed.

/usr/share/doc/ganeti/html/devnotes.html is in ganeti-doc 2.16.0~rc2-1build1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below. 

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>Developer notes &#8212; Ganeti 2.16.0~rc2 documentation</title>
    <link rel="stylesheet" href="_static/style.css" type="text/css" />
    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    './',
        VERSION:     '2.16.0~rc2',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  true,
        SOURCELINK_SUFFIX: '.txt'
      };
    </script>
    <script type="text/javascript" src="_static/jquery.js"></script>
    <script type="text/javascript" src="_static/underscore.js"></script>
    <script type="text/javascript" src="_static/doctools.js"></script>
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Code style guide" href="dev-codestyle.html" />
    <link rel="prev" title="Design for virtual clusters support" href="design-virtual-clusters.html" /> 
  </head>
  <body>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="dev-codestyle.html" title="Code style guide"
             accesskey="N">next</a></li>
        <li class="right" >
          <a href="design-virtual-clusters.html" title="Design for virtual clusters support"
             accesskey="P">previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Ganeti 2.16.0~rc2 documentation</a> &#187;</li> 
      </ul>
    </div>  

    <div class="document">
      <div class="documentwrapper">
        <div class="bodywrapper">
          <div class="body" role="main">
            
  <div class="section" id="developer-notes">
<h1>Developer notes<a class="headerlink" href="#developer-notes" title="Permalink to this headline"></a></h1>
<div class="section" id="build-dependencies">
<h2>Build dependencies<a class="headerlink" href="#build-dependencies" title="Permalink to this headline"></a></h2>
<p>Most dependencies from <a class="reference internal" href="install-quick.html"><span class="doc">Ganeti quick installation guide</span></a>, including <code class="docutils literal"><span class="pre">qemu-img</span></code>
(marked there as optional) plus (for Python):</p>
<ul class="simple">
<li><a class="reference external" href="http://www.gnu.org/software/make/">GNU make</a></li>
<li><a class="reference external" href="http://www.gnu.org/software/tar/">GNU tar</a></li>
<li><a class="reference external" href="http://www.gnu.org/software/gzip/">Gzip</a></li>
<li><a class="reference external" href="http://johnmacfarlane.net/pandoc/">pandoc</a></li>
<li><a class="reference external" href="http://epydoc.sourceforge.net/">python-epydoc</a></li>
<li><a class="reference external" href="http://sphinx.pocoo.org/">python-sphinx</a>
(tested with version 1.1.3)</li>
<li><a class="reference external" href="http://www.voidspace.org.uk/python/mock/">python-mock</a>
(tested with version 1.0.1)</li>
<li><a class="reference external" href="http://www.graphviz.org/">graphviz</a></li>
<li>the <cite>en_US.UTF-8</cite> locale must be enabled on the system</li>
<li><a class="reference external" href="http://www.logilab.org/857">pylint</a> and its associated
dependencies</li>
<li><a class="reference external" href="https://github.com/jcrocholl/pep8/">pep8</a></li>
<li><a class="reference external" href="http://pyyaml.org/">PyYAML</a></li>
</ul>
<p>For older developement (Ganeti &lt; 2.4) <code class="docutils literal"><span class="pre">docbook</span></code> was used instead of
<code class="docutils literal"><span class="pre">pandoc</span></code>.</p>
<p>Note that for pylint, at the current moment the following versions
must be used:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">pylint</span> <span class="gs">--version</span>
pylint 0.26.0,
astng 0.24.1, common 0.58.3
</pre></div>
</div>
<p>The same with pep8, other versions may give you errors:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">pep8</span> <span class="gs">--version</span>
1.3.3
</pre></div>
</div>
<p>Both these versions are the ones shipped with Ubuntu 13.04.</p>
<p>To generate unittest coverage reports (<code class="docutils literal"><span class="pre">make</span> <span class="pre">coverage</span></code>), <a class="reference external" href="http://pypi.python.org/pypi/coverage">coverage</a> needs to be installed.</p>
<p>Installation of all dependencies listed here:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">apt-get</span> <span class="gs">install</span> <span class="gs">python-setuptools</span> <span class="gs">automake</span> <span class="gs">git</span> <span class="gs">fakeroot</span>
$ <span class="gs">apt-get</span> <span class="gs">install</span> <span class="gs">pandoc</span> <span class="gs">python-epydoc</span> <span class="gs">graphviz</span> <span class="gs">python-sphinx</span>
$ <span class="gs">apt-get</span> <span class="gs">install</span> <span class="gs">python-yaml</span>
$ <span class="gs">cd</span> <span class="gs">/</span> <span class="gs">&amp;&amp;</span> <span class="gs">easy_install</span> <span class="gs">\</span>
          <span class="gs">logilab-astng==0.24.1</span> <span class="gs">\</span>
          <span class="gs">logilab-common==0.58.3</span> <span class="gs">\</span>
          <span class="gs">pylint==0.26.0</span> <span class="gs">\</span>
          <span class="gs">pep8==1.3.3</span> <span class="gs">\</span>
          <span class="gs">mock==1.0.1</span> <span class="gs">\</span>
          <span class="gs">coverage</span>
</pre></div>
</div>
<p>For Haskell development, again all things from the quick install
document, plus:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.haskell.org/haddock/">haddock</a>, documentation
generator (equivalent to epydoc for Python)</li>
<li><a class="reference external" href="http://hackage.haskell.org/package/hscolour">HsColour</a>, again
used for documentation (it’s source-code pretty-printing)</li>
<li><a class="reference external" href="http://community.haskell.org/~ndm/hlint/">hlint</a>, a source code
linter (equivalent to pylint for Python), recommended version 1.8 or
above (tested with 1.8.43)</li>
<li>the <a class="reference external" href="http://hackage.haskell.org/package/QuickCheck">QuickCheck</a>
library, version 2.x</li>
<li>the <a class="reference external" href="http://hunit.sourceforge.net/">HUnit</a> library (tested with
1.2.x)</li>
<li>the <a class="reference external" href="http://batterseapower.github.com/test-framework/">test-framework</a> libraries,
tested versions: <code class="docutils literal"><span class="pre">test-framework</span></code>: 0.6, <code class="docutils literal"><span class="pre">test-framework-hunit</span></code>:
0.2.7, <code class="docutils literal"><span class="pre">test-framework-quickcheck2</span></code>: 0.2.12.1</li>
<li><code class="docutils literal"><span class="pre">hpc</span></code>, which comes with the compiler, so you should already have
it</li>
<li><a class="reference external" href="http://joyful.com/shelltestrunner">shelltestrunner</a>, used for
running shell-based unit-tests</li>
<li><a class="reference external" href="https://github.com/batterseapower/temporary/">temporary</a> library,
tested with version 1.1.2.3</li>
</ul>
<p>Under Debian Wheezy or later, these can be installed (on top of the
required ones from the quick install document) via:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">apt-get</span> <span class="gs">install</span> <span class="gs">libghc-quickcheck2-dev</span> <span class="gs">libghc-hunit-dev</span> <span class="gs">\</span>
      <span class="gs">libghc-test-framework-dev</span> <span class="gs">\</span>
      <span class="gs">libghc-test-framework-quickcheck2-dev</span> <span class="gs">\</span>
      <span class="gs">libghc-test-framework-hunit-dev</span> <span class="gs">\</span>
      <span class="gs">libghc-temporary-dev</span> <span class="gs">shelltestrunner</span> <span class="gs">\</span>
      <span class="gs">hscolour</span> <span class="gs">hlint</span>
</pre></div>
</div>
<p>Or alternatively via <code class="docutils literal"><span class="pre">cabal</span></code>:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">cabal</span> <span class="gs">install</span> <span class="gs">QuickCheck</span> <span class="gs">HUnit</span> <span class="gs">\</span>
        <span class="gs">test-framework</span> <span class="gs">test-framework-quickcheck2</span> <span class="gs">test-framework-hunit</span> <span class="gs">\</span>
        <span class="gs">temporary</span> <span class="gs">hscolour</span> <span class="gs">hlint</span> <span class="gs">shelltestrunner</span>
</pre></div>
</div>
</div>
<div class="section" id="configuring-for-development">
<h2>Configuring for development<a class="headerlink" href="#configuring-for-development" title="Permalink to this headline"></a></h2>
<p>Run the following command (only use <code class="docutils literal"><span class="pre">PYTHON=...</span></code> if you need to use a
different python version):</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">./autogen.sh</span> <span class="gs">&amp;&amp;</span> <span class="gs">\</span>
  <span class="gs">./configure</span> <span class="gs">--prefix=/usr/local</span> <span class="gs">--sysconfdir=/etc</span> <span class="gs">--localstatedir=/var</span>
</pre></div>
</div>
<p>Note that doing development on a machine which already has Ganeti
installed is problematic, as <code class="docutils literal"><span class="pre">PYTHONPATH</span></code> behaviour can be confusing
(see Issue 170 for a bit of history/details; in general it works if
the installed and developed versions are very similar, and/or if
PYTHONPATH is customised correctly). As such, in general it’s
recommended to use a “clean” machine for ganeti development.</p>
</div>
<div class="section" id="style-guide">
<h2>Style guide<a class="headerlink" href="#style-guide" title="Permalink to this headline"></a></h2>
<p>Please adhere to the <a class="reference internal" href="dev-codestyle.html"><span class="doc">Code style guide</span></a> while writing code for Ganeti.</p>
</div>
<div class="section" id="haskell-development-notes">
<h2>Haskell development notes<a class="headerlink" href="#haskell-development-notes" title="Permalink to this headline"></a></h2>
<p>There are a few things which can help writing or debugging the Haskell
code.</p>
<p>You can run the Haskell linter <strong class="command">hlint</strong> via:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">hlint</span>
</pre></div>
</div>
<p>This is not enabled by default (as the htools component is
optional). The above command will generate both output on the terminal
and, if any warnings are found, also an HTML report at
<code class="docutils literal"><span class="pre">doc/hs-lint.html</span></code>.</p>
<p>When writing or debugging TemplateHaskell code, it’s useful to see
what the splices are converted to. This can be done via:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">HEXTRA=&quot;-ddump-splices&quot;</span>
</pre></div>
</div>
<p>Or, more interactively:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">ghci</span>
λ&gt; :set -ddump-splices
λ&gt; :l src/Ganeti/Objects.hs
</pre></div>
</div>
<p>And you will get the spliced code as the module is loaded.</p>
<p>To build profiling code you must install the <code class="docutils literal"><span class="pre">ghc-prof</span></code> (or
<code class="docutils literal"><span class="pre">gch6-prof</span></code>) package, and all the relevant libraries with their
<code class="docutils literal"><span class="pre">-prof</span></code> counterparts. If installing libraries through cabal the config
file should include <code class="docutils literal"><span class="pre">library-profiling:</span> <span class="pre">True</span></code> or the <code class="docutils literal"><span class="pre">-p</span></code> flag
should be used. Any library already installed can be updated by passing
<code class="docutils literal"><span class="pre">--reinstall</span></code> as well.</p>
<p>Due to the way TemplateHaskell works, it’s not straightforward to
build profiling code. The recommended way is to run <code class="docutils literal"><span class="pre">make</span> <span class="pre">hs-prof</span></code>,
or alternatively the manual sequence is:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">clean</span>
$ <span class="gs">make</span> <span class="gs">src/htools</span> <span class="gs">HEXTRA=&quot;-osuf</span> <span class="gs">.o&quot;</span>
$ <span class="gs">rm</span> <span class="gs">src/htools</span>
$ <span class="gs">make</span> <span class="gs">src/htools</span> <span class="gs">HEXTRA=&quot;-osuf</span> <span class="gs">.prof_o</span> <span class="gs">-prof</span> <span class="gs">-auto-all&quot;</span>
</pre></div>
</div>
<p>This will build the binary twice, per the TemplateHaskell
documentation, the second one with profiling enabled.</p>
<p>The binary files generated by compilation and the profiling/coverage
files can “break” tab-completion in the sources; they can be ignored,
for example, in bash via <code class="docutils literal"><span class="pre">.bashrc</span></code>:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>FIGNORE=&#39;.o:.hi:.prof_o:.tix&#39;
</pre></div>
</div>
<p>or in emacs via <code class="docutils literal"><span class="pre">completion-ignored-extensions</span></code> (run <code class="docutils literal"><span class="pre">M-x</span>
<span class="pre">customize-var</span> <span class="pre">completion-ignored-extensions</span></code>).</p>
<div class="section" id="running-individual-tests">
<h3>Running individual tests<a class="headerlink" href="#running-individual-tests" title="Permalink to this headline"></a></h3>
<p>When developing code, running the entire test suite can be
slow. Running individual tests is possible. There are different
Makefile targets for running individual Python and Haskell tests.</p>
<p>For Python tests:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">export</span> <span class="gs">PYTHONPATH=$PWD</span>
$ <span class="gs">python</span> <span class="gs">./test/py/ganeti.</span><span class="nv">mytest</span>
</pre></div>
</div>
<p>For Haskell tests:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">hs-test-</span><span class="nv">pattern</span>
</pre></div>
</div>
<p>Where <code class="docutils literal"><span class="pre">pattern</span></code> can be a simple test pattern (e.g. <code class="docutils literal"><span class="pre">comma</span></code>,
matching any test whose name contains <code class="docutils literal"><span class="pre">comma</span></code>), a test pattern
denoting a group (ending with a slash, e.g. <code class="docutils literal"><span class="pre">Utils/</span></code>), or more
complex glob pattern. For more details, search for glob patterns in
the documentation of <a class="reference external" href="http://batterseapower.github.com/test-framework/">test-framework</a>).</p>
<p>For individual Haskell shelltests:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">hs-shell-</span><span class="nv">name</span>
</pre></div>
</div>
<p>which runs the test <code class="docutils literal"><span class="pre">test/hs/shelltests/htools-%name%.test</span></code>. For
example, to run the test <code class="docutils literal"><span class="pre">test/hs/shelltests/htools-balancing.test</span></code>,
use:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">hs-shell-balancing</span>
</pre></div>
</div>
<p>For combined Haskell shelltests:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">hs-shell-{</span><span class="nv">name1</span><span class="gs">,</span><span class="nv">name2</span><span class="gs">,...}</span>
</pre></div>
</div>
<p>for example:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">hs-shell-{balancing,basic}</span>
</pre></div>
</div>
<p>Checking for the correct style of the NEWS file is also possible, by running:</p>
<div class="highlight-shell-example"><div class="highlight"><pre><span></span>$ <span class="gs">make</span> <span class="gs">check-news</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class="section" id="packaging-notes">
<h1>Packaging notes<a class="headerlink" href="#packaging-notes" title="Permalink to this headline"></a></h1>
<p>Ganeti is mostly developed and tested on <a class="reference external" href="http://www.debian.org/">Debian</a>-based distributions, while still keeping
adaptability to other Linux distributions in mind.</p>
<p>The <code class="docutils literal"><span class="pre">doc/examples/</span></code> directory contains a number of potentially useful
scripts and configuration files. Some of them might need adjustment
before use.</p>
<div class="section" id="daemon-util">
<h2><code class="docutils literal"><span class="pre">daemon-util</span></code><a class="headerlink" href="#daemon-util" title="Permalink to this headline"></a></h2>
<p>This script, in the source code as <code class="docutils literal"><span class="pre">daemons/daemon-util.in</span></code>, is used
to start/stop Ganeti and do a few other things related to system
daemons. It is recommended to use <code class="docutils literal"><span class="pre">daemon-util</span></code> also from the system’s
init scripts. That way the code starting and stopping daemons is shared
and future changes have to be made in only one place.</p>
<p><code class="docutils literal"><span class="pre">daemon-util</span></code> reads extra arguments from variables (<code class="docutils literal"><span class="pre">*_ARGS</span></code>) in
<code class="docutils literal"><span class="pre">/etc/default/ganeti</span></code>. When modifying <code class="docutils literal"><span class="pre">daemon-util</span></code>, keep in mind to
not remove support for the <code class="docutils literal"><span class="pre">EXTRA_*_ARGS</span></code> variables for starting
daemons. Some parts of Ganeti use them to pass additional arguments when
starting a daemon.</p>
<p>The <code class="docutils literal"><span class="pre">reload_ssh_keys</span></code> function can be adjusted to use another command
for reloading the OpenSSH daemon’s host keys.</p>
</div>
</div>


          </div>
        </div>
      </div>
      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
        <div class="sphinxsidebarwrapper">
  <h3><a href="index.html">Table Of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">Developer notes</a><ul>
<li><a class="reference internal" href="#build-dependencies">Build dependencies</a></li>
<li><a class="reference internal" href="#configuring-for-development">Configuring for development</a></li>
<li><a class="reference internal" href="#style-guide">Style guide</a></li>
<li><a class="reference internal" href="#haskell-development-notes">Haskell development notes</a><ul>
<li><a class="reference internal" href="#running-individual-tests">Running individual tests</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#packaging-notes">Packaging notes</a><ul>
<li><a class="reference internal" href="#daemon-util"><code class="docutils literal"><span class="pre">daemon-util</span></code></a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="design-virtual-clusters.html"
                        title="previous chapter">Design for virtual clusters support</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="dev-codestyle.html"
                        title="next chapter">Code style guide</a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="_sources/devnotes.rst.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <form class="search" action="search.html" method="get">
      <div><input type="text" name="q" /></div>
      <div><input type="submit" value="Go" /></div>
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
      <div class="clearer"></div>
    </div>
    <div class="related" role="navigation" aria-label="related navigation">
      <h3>Navigation</h3>
      <ul>
        <li class="right" style="margin-right: 10px">
          <a href="dev-codestyle.html" title="Code style guide"
             >next</a></li>
        <li class="right" >
          <a href="design-virtual-clusters.html" title="Design for virtual clusters support"
             >previous</a> |</li>
        <li class="nav-item nav-item-0"><a href="index.html">Ganeti 2.16.0~rc2 documentation</a> &#187;</li> 
      </ul>
    </div>
    <div class="footer" role="contentinfo">
        &#169; Copyright 2018, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 Google Inc..
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
    </div>
  </body>
</html>

APT Browse - Built by Thomas Orozco.