1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
\r
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
\r
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
\r
5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
\r
6 <meta name="generator" content="AsciiDoc 8.2.2" />
\r
7 <style type="text/css">
\r
9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
\r
11 border: 1px solid red;
\r
16 margin: 1em 5% 1em 5%;
\r
21 text-decoration: underline;
\r
39 h1, h2, h3, h4, h5, h6 {
\r
41 font-family: sans-serif;
\r
43 margin-bottom: 0.5em;
\r
48 border-bottom: 2px solid silver;
\r
51 border-bottom: 2px solid silver;
\r
61 border: 1px solid silver;
\r
66 margin-bottom: 0.5em;
\r
76 font-family: sans-serif;
\r
83 font-family: sans-serif;
\r
87 font-family: sans-serif;
\r
89 border-top: 2px solid silver;
\r
95 padding-bottom: 0.5em;
\r
99 padding-bottom: 0.5em;
\r
103 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
\r
104 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
\r
105 div.admonitionblock {
\r
108 margin-bottom: 1.5em;
\r
110 div.admonitionblock {
\r
112 margin-bottom: 2.5em;
\r
115 div.content { /* Block element content. */
\r
119 /* Block element titles. */
\r
120 div.title, caption.title {
\r
121 font-family: sans-serif;
\r
125 margin-bottom: 0.5em;
\r
131 td div.title:first-child {
\r
134 div.content div.title:first-child {
\r
137 div.content + div.title {
\r
141 div.sidebarblock > div.content {
\r
142 background: #ffffee;
\r
143 border: 1px solid silver;
\r
150 div.listingblock > div.content {
\r
151 border: 1px solid silver;
\r
152 background: #f4f4f4;
\r
156 div.quoteblock > div.content {
\r
157 padding-left: 2.0em;
\r
163 div.verseblock + div.attribution {
\r
167 div.admonitionblock .icon {
\r
168 vertical-align: top;
\r
171 text-decoration: underline;
\r
173 padding-right: 0.5em;
\r
175 div.admonitionblock td.content {
\r
176 padding-left: 0.5em;
\r
177 border-left: 2px solid silver;
\r
180 div.exampleblock > div.content {
\r
181 border-left: 2px solid silver;
\r
185 div.verseblock div.content {
\r
189 div.imageblock div.content { padding-left: 0; }
\r
190 div.imageblock img { border: 1px solid silver; }
\r
191 span.image img { border-style: none; }
\r
195 margin-bottom: 0.8em;
\r
200 font-style: italic;
\r
202 dd > *:first-child {
\r
207 list-style-position: outside;
\r
210 list-style-type: lower-alpha;
\r
213 div.tableblock > table {
\r
214 border: 3px solid #527bbd;
\r
217 font-family: sans-serif;
\r
226 margin-bottom: 0.8em;
\r
229 padding-bottom: 5px;
\r
232 vertical-align: top;
\r
233 font-style: italic;
\r
234 padding-right: 0.8em;
\r
237 vertical-align: top;
\r
241 div#footer-badges { display: none; }
\r
246 font-family: sans-serif;
\r
250 margin-bottom: 0.1em;
\r
253 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
\r
269 /* Workarounds for IE6's broken and incomplete CSS2. */
\r
271 div.sidebar-content {
\r
272 background: #ffffee;
\r
273 border: 1px solid silver;
\r
276 div.sidebar-title, div.image-title {
\r
277 font-family: sans-serif;
\r
280 margin-bottom: 0.5em;
\r
283 div.listingblock div.content {
\r
284 border: 1px solid silver;
\r
285 background: #f4f4f4;
\r
289 div.quoteblock-content {
\r
290 padding-left: 2.0em;
\r
293 div.exampleblock-content {
\r
294 border-left: 2px solid silver;
\r
295 padding-left: 0.5em;
\r
298 /* IE6 sets dynamically generated links as visited. */
\r
299 div#toc a:visited { color: blue; }
\r
301 <script type="text/javascript">
\r
303 window.onload = function(){generateToc(2)}
\r
304 /* Author: Mihai Bazon, September 2002
\r
305 * http://students.infoiasi.ro/~mishoo
\r
307 * Table Of Content generator
\r
310 * Feel free to use this script under the terms of the GNU General Public
\r
311 * License, as long as you do not remove or alter this notice.
\r
314 /* modified by Troy D. Hanson, September 2006. License: GPL */
\r
315 /* modified by Stuart Rackham, October 2006. License: GPL */
\r
317 function getText(el) {
\r
319 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
320 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
\r
322 else if (i.firstChild != null)
\r
323 text += getText(i);
\r
328 function TocEntry(el, text, toclevel) {
\r
331 this.toclevel = toclevel;
\r
334 function tocEntries(el, toclevels) {
\r
335 var result = new Array;
\r
336 var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
\r
337 // Function that scans the DOM tree for header elements (the DOM2
\r
338 // nodeIterator API would be a better technique but not supported by all
\r
340 var iterate = function (el) {
\r
341 for (var i = el.firstChild; i != null; i = i.nextSibling) {
\r
342 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
\r
343 var mo = re.exec(i.tagName)
\r
345 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
\r
354 // This function does the work. toclevels = 1..4.
\r
355 function generateToc(toclevels) {
\r
356 var toc = document.getElementById("toc");
\r
357 var entries = tocEntries(document.getElementsByTagName("body")[0], toclevels);
\r
358 for (var i = 0; i < entries.length; ++i) {
\r
359 var entry = entries[i];
\r
360 if (entry.element.id == "")
\r
361 entry.element.id = "toc" + i;
\r
362 var a = document.createElement("a");
\r
363 a.href = "#" + entry.element.id;
\r
364 a.appendChild(document.createTextNode(entry.text));
\r
365 var div = document.createElement("div");
\r
366 div.appendChild(a);
\r
367 div.className = "toclevel" + entry.toclevel;
\r
368 toc.appendChild(div);
\r
373 <title>grml policy</title>
\r
377 <h1>grml policy</h1>
\r
379 <div id="toctitle">Table of Contents</div>
\r
380 <noscript><p><b>JavaScript must be enabled in your browser to display the table of contents.</b></p></noscript>
\r
383 <div id="preamble">
\r
384 <div class="sectionbody">
\r
385 <div class="sidebarblock">
\r
386 <div class="sidebar-content">
\r
387 <p>Important! This file is not yet official - work in progress.</p>
\r
391 <h2>1. Preface</h2>
\r
392 <div class="sectionbody">
\r
393 <p>This is a short documentation describing different policies used at and for
\r
394 <a href="http://grml.org/">grml</a>.</p>
\r
396 <h2>2. Packaging Software</h2>
\r
397 <div class="sectionbody">
\r
398 <p>If you are not yet familiar with <strong>creating</strong> Debian packaging useful
\r
399 resources are the <a href="http://www.debian.org/doc/maint-guide/">Debian New
\r
400 Maintainers' Guide</a> and
\r
401 <a href="http://www.debian.org/doc/manuals/developers-reference/index.en.html">The
\r
402 Debian Developer's Reference</a>.</p>
\r
403 <p>Software that should be <strong>added</strong> to the grml repository (and as a
\r
404 consequence being available for inclusion in grml) must be packaged
\r
406 <a href="http://www.debian.org/doc/debian-policy/index.html">Debian policy</a>.
\r
407 The Debian packages should be
\r
408 <a href="http://lintian.debian.org/">lintian</a>-clean and have to provide manpages
\r
409 for the shipped executables. The package should be maintained inside a
\r
410 mercurial repository hosted at <a href="http://hg.grml.org/">hg.grml.org</a>.
\r
411 If the package is a grml specific package (so upstream is different from
\r
412 the grml-team) the Debian package has to start with the suffix <em>grml-</em> (so
\r
413 the grml specific packages can be identified easily).</p>
\r
414 <p>If you want to see software included in grml but won't be able to deal with
\r
415 the Debian package please <a href="http://grml.org/report/">send your feature
\r
416 request to the grml-team</a>.</p>
\r
417 <p>Uploading Debian packages to <a href="http://deb.grml.org/">the grml pool</a> is
\r
418 restricted to the ftp-masters (being Michael Prokop and Alexander Wirt at
\r
419 the time of writing this document).</p>
\r
420 <p>As a long term goal the Debian packages used at grml should be provided to
\r
421 the official Debian distribution using the official
\r
422 <a href="http://www.debian.org/devel/wnpp/">WNPP / ITP (Intend To Package)</a>
\r
425 <h2>3. Adding Software to grml</h2>
\r
426 <div class="sectionbody">
\r
427 <p>If you plan to write software for inclusion and distribution by grml you
\r
428 should be aware of the following requirements:</p>
\r
432 The software has to be licensed under an
\r
433 <a href="http://www.opensource.org/licenses">OSI approved license</a> and should
\r
434 follow the <a href="http://www.debian.org/social_contract#guidelines">The Debian
\r
435 Free Software Guidelines (DFSG)</a>. The grml-team prefers the
\r
436 <a href="http://www.gnu.org/copyleft/gpl.html">GNU General Public License
\r
437 (GPL)</a>. If you want to see your patch/script/software included in a core
\r
438 grml package it has to be licensed under the GPL as well.
\r
443 Your software has to provide documentation. The package must provide at
\r
444 least an up2date manpage. The grml-team prefers documentation written in
\r
445 <a href="http://www.methods.co.nz/asciidoc/">asciidoc</a>, see
\r
446 <a href="http://grml.org/docs/">grml.org/docs/</a> and
\r
447 <a href="http://hg.grml.org/grml-debootstrap/file/tip/grml-debootstrap.8.txt">grml-debootstrap.8.txt</a>
\r
448 for a real-life example.
\r
453 Your software should be as platform independent as possible and should
\r
454 work at least on x86, x86_64 (amd64) and ppc.
\r
459 <h2>4. Contributing patches to grml</h2>
\r
460 <div class="sectionbody">
\r
461 <p>Software written by and maintained by the grml-team is available at
\r
462 <a href="http://hg.grml.org/">hg.grml.org</a>. If you plan to provide a patch to
\r
463 the grml-team you can checkout the according repository and create a patch
\r
464 using the <em>hg diff</em> command. Usage example:</p>
\r
465 <div class="listingblock">
\r
466 <div class="content"><!-- Generator: GNU source-highlight 2.4
\r
468 http://www.lorenzobettini.it
\r
469 http://www.gnu.org/software/src-highlite -->
\r
470 <pre><tt>hg clone http<span style="color: #990000">:</span>//hg<span style="color: #990000">.</span>grml<span style="color: #990000">.</span>org/grml-policy
\r
472 hg diff <span style="color: #990000">></span> update_for_grml-policy-mention_foobar<span style="color: #990000">.</span>diff
\r
473 </tt></pre></div></div>
\r
474 <p>And mail the resulting diff to the grml-team. The maintainer of the
\r
475 according repository is listed in the Contact-column on
\r
476 <a href="http://hg.grml.org/">hg.grml.org</a>. You are free to
\r
477 <a href="http://grml.org/contact/">contact the grml-team directly via mail</a> or
\r
478 the <a href="http://grml.org/mailinglist/">grml-mailinglist</a> as well.</p>
\r
479 <p>More details regarding use of mercurial at grml is available at
\r
480 <a href="http://grml.org/mercurial/">grml.org/mercurial/</a>.</p>
\r
482 <h2>5. Common practices for writing code</h2>
\r
483 <div class="sectionbody">
\r
484 <h3>5.1. Header information</h3>
\r
485 <p>Every script should provide a header which should look like this:</p>
\r
486 <div class="literalblock">
\r
487 <div class="content">
\r
489 # Filename: grml2hd
\r
490 # Purpose: install grml to harddisk
\r
491 # Authors: grml-team (grml.org), (c) Andreas Gredler <jimmy@grml.org>, Michael Prokop <mika@grml.org>
\r
492 # Bug-Reports: see http://grml.org/bugs/
\r
493 # License: This file is licensed under the GPL v2.
\r
494 # Latest change: Thu Sep 13 23:00:56 CEST 2007 [mika]
\r
495 ################################################################################</tt></pre>
\r
497 <h3>5.2. Footer information</h3>
\r
498 <p>Most developers of the grml-team use Vim as their favourite editor.
\r
499 Therefor providing a modeline at the end of the sourcefile is commonly used
\r
500 to indicate the favourite editing mode/style. Usage example:</p>
\r
501 <div class="literalblock">
\r
502 <div class="content">
\r
503 <pre><tt># vim: ai filetype=sh expandtab shiftwidth=3</tt></pre>
\r
505 <h3>5.3. grml shellscript library</h3>
\r
506 <p>The grml system provides several shellscript resources. The package
\r
507 grml-etc-core provides the files /etc/grml/lsb-functions and
\r
508 /etc/grml/script-functions, the package grml-shlib ships /etc/grml/sh-lib.</p>
\r
509 <h4>5.3.1. /etc/grml/lsb-functions</h4>
\r
510 <p>The file /etc/grml/lsb-functions is used within init-scripts and init-style
\r
511 scripts (like shellscripts handling with services) and is supposed to be
\r
512 POSIX-compatible. Usage example:</p>
\r
513 <div class="listingblock">
\r
514 <div class="content"><!-- Generator: GNU source-highlight 2.4
\r
516 http://www.lorenzobettini.it
\r
517 http://www.gnu.org/software/src-highlite -->
\r
518 <pre><tt><span style="color: #990000">%</span> <span style="font-weight: bold"><span style="color: #0000FF">source</span></span> /etc/grml/lsb-functions
\r
519 <span style="color: #990000">%</span> einfo <span style="color: #FF0000">"Starting foobar."</span> <span style="color: #990000">;</span> /bin/true <span style="color: #990000">;</span> eend $<span style="color: #990000">?</span>
\r
520 <span style="color: #990000">*</span> Starting foobar<span style="color: #990000">.</span> <span style="color: #990000">[</span> ok <span style="color: #990000">]</span>
\r
521 <span style="color: #990000">%</span> einfo <span style="color: #FF0000">"Starting foobar."</span> <span style="color: #990000">;</span> /bin/false <span style="color: #990000">;</span> eend $<span style="color: #990000">?</span>
\r
522 <span style="color: #990000">*</span> Starting foobar<span style="color: #990000">.</span> <span style="color: #990000">[</span> <span style="color: #990000">!!</span> <span style="color: #990000">]</span>
\r
523 <span style="color: #990000">%</span>
\r
524 </tt></pre></div></div>
\r
525 <p>If you want to provide output on the plain console (without using an
\r
526 interface like <a href="http://invisible-island.net/dialog/">dialog</a> or
\r
527 <a href="http://www.clifford.at/stfl/">stfl</a>) you should consider the use of
\r
528 /etc/grml/lsb-functions so look and feel of grml-scripts is as consistent
\r
530 <h4>5.3.2. /etc/grml/script-functions</h4>
\r
531 <p>The file /etc/grml/script-functions provides common functions used inside
\r
532 several scripts, like check4root (check for root-permissions), iszsh (check
\r
533 for running zsh). The file is supposed to be used in every POSIX-compatible
\r
534 shell (otherwise it's a bug).</p>
\r
535 <h4>5.3.3. /etc/grml/sh-lib</h4>
\r
536 <p>The file /etc/grml/sh-lib provides a smiliar functionality like
\r
537 /etc/grml/lsb-functions and /etc/grml/script-functions do. As a long term
\r
538 goal the functionality of this file should be merged with the one of
\r
539 lsb-functions and script-functions.</p>
\r
540 <h3>5.4. Good practices for shellscript</h3>
\r
544 <strong>shebang line:</strong> if you use <em>#!/bin/sh</em> as the shebang line of your
\r
545 shellscript you should make sure that the script runs under every
\r
546 POSIX-compatible shell. A good test is the use of /bin/dash for /bin/sh. If
\r
547 you use bash/zsh/ksh93/… specific features please use the according
\r
548 shell in the shebang line of your script.
\r
553 <strong>check for appropriate permissions:</strong> if you need root permissions you
\r
554 should make sure that your script is running as user root (take a look at
\r
555 check4root function provided by /etc/grml/script-functions).
\r
560 <strong>clean up when being interrupted and on exit:</strong> your script should not leave
\r
561 any temporary files (unless intented for debugging purposes of course).
\r
564 <div class="listingblock">
\r
565 <div class="content"><!-- Generator: GNU source-highlight 2.4
\r
567 http://www.lorenzobettini.it
\r
568 http://www.gnu.org/software/src-highlite -->
\r
569 <pre><tt><span style="color: #009900">TMPFILE</span><span style="color: #990000">=</span><span style="color: #009900">$(mktemp</span> <span style="color: #009900">${TMP}</span>/grml2hd<span style="color: #990000">.</span>XXXXXX<span style="color: #990000">)</span>
\r
570 <span style="font-weight: bold"><span style="color: #000000">bailout()</span></span> {
\r
571 rm -f <span style="color: #FF0000">"$TMPFILE"</span>
\r
572 <span style="color: #990000">[</span> -n <span style="color: #FF0000">"$1"</span> <span style="color: #990000">]</span> <span style="color: #990000">&&</span> <span style="color: #009900">EXIT</span><span style="color: #990000">=</span><span style="color: #FF0000">"$1"</span> <span style="color: #990000">||</span> <span style="color: #009900">EXIT</span><span style="color: #990000">=</span><span style="color: #FF0000">"1"</span>
\r
573 <span style="font-weight: bold"><span style="color: #0000FF">exit</span></span> <span style="color: #FF0000">"$EXIT"</span>
\r
575 <span style="font-weight: bold"><span style="color: #0000FF">trap</span></span> bailout <span style="color: #993399">1</span> <span style="color: #993399">2</span> <span style="color: #993399">3</span> <span style="color: #993399">15</span>
\r
576 <span style="color: #009900">$CODE</span>
\r
577 bailout <span style="color: #993399">0</span>
\r
578 </tt></pre></div></div>
\r
582 <strong>use of subshells:</strong> please use <em>$(…)</em> instead of <em>`…`</em>.
\r
584 <p>It allows nesting of commands in a more clearly and easier way.
\r
585 Therefore any shell code might appear within the parentheses, since
\r
586 the only time parentheses occur unquoted is in pairs.<br />
\r
587 With backquotes however any unquoted <em>`</em> within the form <em>`…`</em>
\r
588 would end the quotes immediately.</p>
\r
589 <p>Consider the following as an example on readability:</p>
\r
590 <div class="listingblock">
\r
591 <div class="content"><!-- Generator: GNU source-highlight 2.4
\r
593 http://www.lorenzobettini.it
\r
594 http://www.gnu.org/software/src-highlite -->
\r
595 <pre><tt><span style="color: #990000">%</span> echo <span style="color: #FF0000">"Tomorrow's date: `expr </span><span style="color: #CC33CC">\`</span><span style="color: #FF0000">date +%d</span><span style="color: #CC33CC">\`</span><span style="color: #FF0000"> + 1`.`date +%m`."</span>
\r
596 <span style="color: #990000">%</span> echo <span style="color: #FF0000">"Tomorrow's date: $(expr $(date +%d) + 1).$(date +%m)."</span>
\r
597 </tt></pre></div></div>
\r
598 <p>Furthermore it can get quite tricky to get the right level of quotes
\r
599 when using backquotes.</p>
\r
600 <div class="listingblock">
\r
601 <div class="content"><!-- Generator: GNU source-highlight 2.4
\r
603 http://www.lorenzobettini.it
\r
604 http://www.gnu.org/software/src-highlite -->
\r
605 <pre><tt><span style="color: #990000">%</span> print <span style="color: #FF0000">"`echo </span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">hello</span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">`"</span>
\r
607 <span style="color: #990000">%</span> print <span style="color: #FF0000">"$(echo </span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">hello</span><span style="color: #CC33CC">\"</span><span style="color: #FF0000">)"</span>
\r
608 <span style="color: #FF0000">"hello"</span>
\r
609 </tt></pre></div></div>
\r
610 <p>For further reading have a look at
\r
611 <a href="http://zsh.dotsrc.org/Guide/zshguide05.html#l11">A User's Guide to the
\r
613 and <a href="http://zsh.sourceforge.net/Intro/intro_7.html#SEC7">Introduction to
\r
614 the Z Shell</a></p>
\r
618 <strong>if … then … else …</strong>: you should make sure that the code is as
\r
619 easy understandable as possible. So instead of using:
\r
621 <div class="listingblock">
\r
622 <div class="content"><!-- Generator: GNU source-highlight 2.4
\r
624 http://www.lorenzobettini.it
\r
625 http://www.gnu.org/software/src-highlite -->
\r
626 <pre><tt><span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -n <span style="color: #FF0000">"$FOO"</span> <span style="color: #990000">]</span> <span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>
\r
630 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
\r
632 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
\r
634 you should consider use of<span style="color: #990000">:</span>
\r
636 <span style="font-weight: bold"><span style="color: #0000FF">if</span></span> <span style="color: #990000">[</span> -z <span style="color: #FF0000">"$FOO"</span> <span style="color: #990000">]</span> <span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">then</span></span>
\r
638 <span style="font-weight: bold"><span style="color: #0000FF">else</span></span>
\r
642 <span style="font-weight: bold"><span style="color: #0000FF">fi</span></span>
\r
643 </tt></pre></div></div>
\r
647 <strong>indenting:</strong> make sure you indent your code and use blank lines where
\r
648 according. Commonly accepted textwidth is 80 chars. (TODO: provide some
\r
649 more information…)
\r
654 <strong>use of tabs:</strong> the grml-team prefers to <strong>not</strong> use any tabs inside
\r
655 their code. Please use 4 spaces instead of a tab instead (<em>tabstop=4</em> and
\r
656 <em>set expandtab</em> when using Vim editor). To replace tabs with spaces you can
\r
657 use <em>:set expandtab</em> and <em>:retab</em> using Vim editor.
\r
662 <strong>no trailing whitespaces:</strong> make sure your code does not contain any
\r
663 trailing whitespaces. Remove them inside Vim editor running <em>:%s/\s+$//</em>
\r
664 and make them visible using for example <em>:set
\r
665 listchars=eol:$,precedes:«,extends:»,tab:»·,trail:·</em>.
\r
670 <h2>6. About this document</h2>
\r
671 <div class="sectionbody">
\r
672 <p>© Michael Prokop <mika@grml.org>; HTML version powered by <a href="http://www.methods.co.nz/asciidoc/">asciidoc</a>.</p>
\r
675 <div id="footer-text">
\r
676 Last updated 17-Dec-2007 04:31:59 CEST
\r