Important! This file is not yet official - work in progress.

1. Preface

This is a short documentation describing different policies used at and for grml.

2. Packaging Software

If you are not yet familiar with creating Debian packaging, useful resources are the Debian New Maintainers' Guide and The Debian Developer’s Reference.

Software that should be added to the grml repository (and as a consequence being available for inclusion in grml) must be packaged according to the Debian policy. The Debian packages should be lintian-clean and have to provide manpages for the shipped executables. The package should either be maintained inside a git repository hosted at git.grml.org or be part of the official debian repository. If a package is a grml specific package (so upstream is different from the grml-team) the Debian package has to start with the suffix grml- (so the grml specific packages can be identified easily).

If you want to see software included in grml but won’t be able to deal with the Debian package please send your feature request to the grml-team or by sending a mail to bts@bts.grml.org, which will add an issue to bts.grml.org.

Uploading Debian packages to the grml pool is restricted to the ftp-masters (being Michael Prokop and Alexander Wirt at the time of writing this document).

As a long term goal the Debian packages used at grml should be provided to the official Debian distribution using the official WNPP / ITP (Intend To Package) procedure.

3. Adding Software to grml

If you plan to write software for inclusion and distribution by grml you should be aware of the following requirements:

4. Contributing patches to grml

Software written by and maintained by the grml-team is available at git.grml.org. If you plan to provide a patch to the grml-team you can checkout the according repository and create a patch using the git diff or even better the git format-patch command. Usage example:

% git clone git://git.grml.org/grml-policy.git
% cd grml-policy
% git checkout -b mygreatfeature
% [hack hack hack]
% git commit -a
% git format-patch master

And mail the resulting patches to the grml-team with your favourite mail client or using git send-email. The maintainer of the according repository is listed in the owner-column on git.grml.org. You are free to contact the grml-team directly via mail, the grml bug tracking system, or the grml-mailinglist as well.

More details regarding use of git within grml is available at grml.org/git/.

5. Common practices for writing code

5.1. Header information

Every script should provide a header which should look like this:

#!/bin/sh
# Filename:      grml2hd
# Purpose:       install grml to harddisk
# Authors:       grml-team (grml.org), (c) Andreas Gredler <jimmy@grml.org>, Michael Prokop <mika@grml.org>
# Bug-Reports:   see http://grml.org/bugs/
# License:       This file is licensed under the GPL v2.
# Latest change: Thu Sep 13 23:00:56 CEST 2007 [mika]
################################################################################

5.2. Footer information

Most developers of the grml-team use Vim as their favourite editor. Therefor providing a modeline at the end of the sourcefile is commonly used to indicate the favourite editing mode/style. Usage example:

# vim: autoindent filetype=sh expandtab shiftwidth=4

5.3. grml shellscript library

The grml system provides several shellscript resources. The package grml-etc-core provides the files /etc/grml/lsb-functions and /etc/grml/script-functions, the package grml-shlib ships /etc/grml/sh-lib.

5.3.1. /etc/grml/lsb-functions

The file /etc/grml/lsb-functions is used within init-scripts and init-style scripts (like shellscripts handling with services) and is supposed to be POSIX-compatible. Usage example:

% source /etc/grml/lsb-functions
% einfo "Starting foobar." ; /bin/true ; eend $?
 * Starting foobar.                                  [ ok ]
% einfo "Starting foobar." ; /bin/false ; eend $?
 * Starting foobar.                                  [ !! ]
%

If you want to provide output on the plain console (without using an interface like dialog or stfl) you should consider the use of /etc/grml/lsb-functions so look and feel of grml-scripts is as consistent as possible.

5.3.2. /etc/grml/script-functions

The file /etc/grml/script-functions provides common functions used inside several scripts, like check4root (check for root-permissions), iszsh (check for running zsh). The file is supposed to work with every POSIX-compatible shell (otherwise it’s a bug).

5.3.3. /etc/grml/sh-lib

The file /etc/grml/sh-lib provides a smiliar functionality like /etc/grml/lsb-functions and /etc/grml/script-functions do. As a long term goal the functionality of this file should be merged with the one of lsb-functions and script-functions.

5.4. Good practices for shellscript

  • shebang line: if you use #!/bin/sh as the shebang line of your shellscript you should make sure that the script runs under every POSIX-compatible shell. A good test is the use of /bin/dash for /bin/sh. If you use bash/zsh/ksh93/… specific features please use the according shell in the shebang line of your script.

  • check for appropriate permissions: if you need root permissions you should make sure that your script is running as user root (take a look at check4root function provided by /etc/grml/script-functions).

  • clean up when being interrupted and on exit: your script should not leave any temporary files (unless intented for debugging purposes of course). Usage example: 

    TMPFILE=$(mktemp ${TMP}/grml2hd.XXXXXX)
bailout() {
  rm -f "$TMPFILE"
  [ -n "$1" ] && EXIT="$1" || EXIT="1"
  exit "$EXIT"
}
trap bailout 1 2 3 15
$CODE
bailout 0

  • use of subshells: please use $(…) instead of `…\`.

    It allows nesting of commands in a more clearly and easier way. Therefore any shell code might appear within the parentheses, since the only time parentheses occur unquoted is in pairs.
    With backquotes however any unquoted `_ within the form _\`…\` would end the quotes immediately.

    Consider the following as an example on readability:

    % echo "Tomorrow's date: `expr \`date +%d\` + 1`.`date +%m`."
% echo "Tomorrow's date: $(expr $(date +%d) + 1).$(date +%m)."

    Furthermore it can get quite tricky to get the right level of quotes when using backquotes.

    % print "`echo \"hello\"`"
hello
% print "$(echo \"hello\")"
"hello"

    For further reading have a look at A User’s Guide to the Z Shell and Introduction to the Z Shell

  • if … then … else … etc.: Use the coding style used in other shell scripts shipped by grml, like: 

    ## use the following forms:

if [ -n "$FOO" ] ; then
    bar
else
    baz
fi

while [ -n "$FOO" ] ; do
    bar
done

## instead of these:

if [ -n "$FOO" ]
then
    bar
else
    baz
fi

while [ -n "$FOO" ]
do
    bar
done

  • whitespace: make sure you indent your code and use blank lines where according. Commonly accepted textwidth is 80 chars. (TODO: provide some more information…)

  • indenting and use of tabs: the grml-team prefers to not use any tabs inside their code. Please use 4 spaces instead of a tab instead (tabstop=4 and set expandtab when using Vim editor). To replace tabs with spaces you can use :set expandtab and :retab using Vim editor.

  • no trailing whitespaces: make sure your code does not contain any trailing whitespaces. Remove them inside Vim editor running :%s/\s\+$// and make them visible using for example :set listchars=eol:$,precedes:«,extends:»,tab:»·,trail:·.

6. About this document

© Michael Prokop <mika@grml.org>; HTML version powered by asciidoc.