Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
292 lines (238 sloc) 10.5 KB
grml policy
Important! This file is not yet official - work in progress.
This is a short documentation describing different policies used at and for
Packaging Software
If you are not yet familiar with **creating** Debian packaging, useful
resources are the link:[Debian New
Maintainers' Guide] and
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
link:[Debian policy].
The Debian packages should be
link:[lintian]-clean and have to provide manpages
for the shipped executables. The package should either be maintained inside
a git repository hosted at link:[] 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 link:[send your feature
request to the grml-team] or by sending a mail to[], which will add an issue to
Uploading Debian packages to link:[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
link:[WNPP / ITP (Intend To Package)]
Adding Software to grml
If you plan to write software for inclusion and distribution by grml you
should be aware of the following requirements:
* The software has to be licensed under an
link:[OSI approved license] and should
follow the link:[The Debian
Free Software Guidelines (DFSG)]. The grml-team prefers the
link:[GNU General Public License
(GPL)]. If you want to see your patch/script/software included in a core
grml package it has to be licensed under the GPL as well.
* Your software has to provide documentation. The package must provide at
least an up2date manpage. The grml-team prefers documentation written in
link:[asciidoc], see
link:[] and
for a real-life example.
* Your software should be as platform independent as possible and should
work at least on x86, x86_64 (amd64) and ppc.
Contributing patches to grml
Software written by and maintained by the grml-team is available at
link:[]. 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
% git clone 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
link:[]. You are free to
link:[contact the grml-team directly via mail],
link:[the grml bug tracking system], or the
link:[grml-mailinglist] as well.
More details regarding use of git within grml is available at
Common practices for writing code
Header information
Every script should provide a header which should look like this:
# Filename: grml2hd
# Purpose: install grml to harddisk
# Authors: grml-team (, (c) Andreas Gredler <>, Michael Prokop <>
# Bug-Reports: see
# License: This file is licensed under the GPL v2.
# Latest change: Thu Sep 13 23:00:56 CEST 2007 [mika]
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
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.
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 link:[dialog] or
link:[stfl]) you should consider the use of
/etc/grml/lsb-functions so look and feel of grml-scripts is as consistent
as possible.
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).
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.
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
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\"`"
% print "$(echo \"hello\")"
For further reading have a look at
link:[A User's Guide to the
Z Shell]
and link:[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
while [ -n "$FOO" ] ; do
## instead of these:
if [ -n "$FOO" ]
while [ -n "$FOO" ]
* **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
About this document
(C) Michael Prokop <>; HTML version powered by link:[asciidoc].
// vim: ft=asciidoc autoindent textwidth=75 formatoptions=tcqn
Something went wrong with that request. Please try again.