Contents

• Chapter 1  Installation
  • 1.1  Requirements
  • 1.2  Sources
  • 1.3  Distribution package
• Chapter 2  How to use Herodotos
• Chapter 3  HCL grammar
  • 3.1  Global attributes and top-level definitions
  • 3.2  Common attributes
  • 3.3  Project attributes
  • 3.4  Pattern attributes
  • 3.5  Graphs rules
  • 3.6  Expression rules

Foreword

This manual documents the release 0.6.0rc1 of Herodotos.

Copyright

Herodotos copyright is
©2010, University of Copenhagen DIKU.
©2010, Nicolas Palix.
Herodotos is open source and can be freely redistributed under the terms of the GNU General Public License version 2. See the file license.txt in the distribution for licensing information.

The present documentation is copyright 2010, Nicolas Palix and distributed under the terms of the GNU Free Documentation License version 1.3.

Availability

Herodotos can be freely downloaded from http://www.diku.dk/~npalix/herodotos/. This website contains also additional information.

Chapter 1  Installation

1.1  Requirements

To install Herodotos from the source

You need the O’Caml compiler. Herodotos parsers are generated with Menhir. However they have been pre-generated in the source package.

To use Herodotos

You need the following:

• A org-mode capable matching tool. For instance, Coccinelle (spatch) is perfect.
• Herodotos relies on EPS generation using jgraph and ps2eps. They are thus mandatory.
• To convert to PDF files, Herodotos uses epstopdf which is part of texlive. You may also consider installing pdftk to manipulate PDF files.
• To easy diffusion of your results on the web, Herodotos is able to generate a web site with images in PNG and SVG formats. If you want to use this feature, you need to have imagemagick (for PNG) and inkscape (for SVG). Note that the conversion to SVG needs the PDF version of your graphs. You thus need to have epstopdf available. Finally, this feature requires inscape version to be at least 0.47.
• To improve the execution time of Coccinelle, you may consider using the glimpse indexer.

1.2  Sources

Sources are available on several web sites:

• http://www.diku.dk/~npalix/herodotos/
• https://launchpad.net/~npalix/+archive/herodotos
• https://launchpad.net/~npalix/+archive/herodotos-stable

1.3  Distribution package

If you’re under Ubuntu, you may add ppa:npalix/herodotos or ppa:npalix/herodotos-stable as an other software source in Synaptic. In that case, runtime dependencies are automatically handled.

For more information, you can go to the PPA pages on Launchpad mentioned in previous section.

Chapter 2  How to use Herodotos

At this point, you must have Herodotos installed. You now have to setup your environment and write a Herodotos Configuration file.

1. Setup the environment
   • Copy default make files and define your working directory. If you installed Herodotos from source, the default make files are herodotos/scripts. For a package install, copy the files from the Herodotos examples¹.
   • Write a HC file which declares your projects, patterns and graphs.
     If you want to have several .hc files, you should define the CONF environment variable to select a default one. Every following make command will then use that configuration file.
2. Initialize the environment:

   make init

3. Compute raw data:

   make -j2

4. Correlate bug reports and propose an initial set of correlations:

   make correl

   Note: Herodotos will automatically compute the changeset.

5. Manually edit the remaining correlations

   $EDITOR results/*/*.correl.org

   Emacs with the Org mode is recommended. Org mode view-link add-on will transform your emacs in a wizard to handle Coccinelle reports.

   See ./tools/org-view-link.el

6. Use the new complementary correlation information

   make correl (recompute the correlation and use the correlation set manually provided)

7. Check the result:

   make stat

8. Look for false positive
   • cp results/*/*.edit.org results/*/*.new.org
   • Edit the new copy and annotate the reported TODO with either BUG or FP.
9. Generate graphs (or website):

   make [graph|web]

10. Edit and adjust your HC file
    Iterate on steps 9 and 10.

1

/usr/share/doc/herodotos/examples/scripts

Chapter 3  HCL grammar

This document presents the grammar of the Herodotos Configuration Language used by the Herodotos tool. The grammar uses some unspecified nonterminals, such as id, etc. These refer to the sets suggested by the name, i.e., id refers to the set of possible identifiers.

A PDF version of this documentation is available at http://www.diku.dk/~npalix/herodotos/docs/herodotos.pdf.

3.1  Global attributes and top-level definitions

3.2  Common attributes

3.3  Project attributes

3.4  Pattern attributes

3.5  Graphs rules

3.6  Expression rules

The operators * and / have priority over the operators + and -.

This document was translated from L^AT_EX by H^EV^EA.