Vincent Simonet

November, 2002

This manual is also available in plain text, PostScript and PDF.

1  Overview

It is a common usage to put at the beginning of source code files a short header giving, for instance, some copyright informations. headache is a simple and lightweight tool for managing easily these headers. Among its functionalities, one may mention: headache is distributed under the terms of the GNU Library General Public License. See file LICENSE of the distribution for more information.

2  Compilation and installation

Building headache requires Objective Caml (version 3.06 or up, available at http://caml.inria.fr/) and GNU Make.

  1. Configure the system. From the source directory, do:
    This generates the Makefile in the source directory. The software is installed by default in /usr/local/bin. This path is customizable thanks to the --bindir option.

  2. Build the executable. From the source directory, do:
    This builds an executable named headache.

  3. In order to install it in the directory specified during configuration, as a superuser, do:
      make install

3  Usage

Let us illustrate the use of this tool with a small example. Assume you have a small project mixing C and Caml code consisting in three files foo.c, bar.ml and bar.mli', and you want to equip them with some header. First of all, write a header file, i.e. a plain text file including the information headers must mention. An example of such a file is given in figure 1. In the following, we assume this file is named myheader and is in the same directory as source files.

Then, in order to generate headers, just run the command:
  headache -h myheader foo.c bar.ml bar.mli
Each file is equipped with an header including the text given in the header file myheader, surrounded by some extra characters depending on its format making it a comment (e.g. (* and *) in .ml files). If you update informations in the header file myheader, you simply need to re-run the above command to update headers in source code files: existing ones are automatically removed.

Similarly, running:
  headache -r foo.c bar.ml bar.mli
removes any existing in files foo.c, bar.ml and bar.mli. Files which do not have a header are kept unchanged.

               Automatic generation of files headers

        Vincent Simonet, Projet Cristal, INRIA Rocquencourt

Copyright 2002 
Institut National de Recherche en Informatique et en Automatique.
All rights reserved.  This file is distributed under the terms of
the GNU Library General Public License.

Vincent.Simonet@inria.fr           http://cristal.inria.fr/~simonet/

Figure 1: An example of header file

4  Configuration file

File types and format of header may be specified by a configuration file. By default, the default builtin configuration file given in figure 2 is used. You can also use your own configuration file thanks to the -c option:
  headache -c myconfig -h myheader foo.c bar.ml bar.mli
In order to write your own configuration, you can follow the example given in figure 2. A configuration file consists in a list of entries separated by the character |. Each of them is made of two parts separated by an ->: headache currently supports three models: It is possible to change the default builtin configuration file at compile time. For this, just edit the file config_builtin present in the source distribution before building the software.

# Objective Caml source 
  ".*\\.ml[il]?" -> frame open:"(*" line:"*" close:"*)"
| ".*\\.mly"     -> frame open:"/*" line:"*" close:"*/"
# C source
| ".*\\.[ch]"    -> frame open:"/*" line:"*" close:"*/"
# Misc
| ".*Makefile.*" -> frame open:"#"  line:"#" close:"#"
| ".*README.*"   -> frame open:"*"  line:"*" close:"*"
| ".*LICENSE.*"  -> frame open:"*"  line:"*" close:"*"

Figure 2: The default builtin configuration file

This document was translated from LATEX by HEVEA.