docs/manual/introduction.tex

   1 \chapter{Introduction}
   2 %src: cocci website, LWN article
   3
   4 Coccinelle is a tool to help automate repetitive
   5 source-to-source style-preserving program transformations
   6 on C source code, like for instance to perform some refactorings.
   7 %coupling: readme.txt
   8 Coccinelle is presented as a command line tool called \spatch that takes
   9 as input the name of a file containing the specification of a program
  10 transformation, called a {\em semantic patch}, and a set of C files,
  11 and then performs the transformation on all those C files.
  12 %synopsis ?
  13
  14 To make it easy to express those transformations,
  15 Coccinelle proposes a WYSISWYG approach where the C programmer
  16 can leverage the things he already knows: the C syntax
  17 and the patch syntax. Indeed, with Coccinelle transformations
  18 are written in specific language called SmPL, for
  19 Semantic Patch Language, which as the name suggests is very
  20 close to the syntax of a patch, but which does not
  21 work at a line level, than traditional patches do.
  22 but a more high level, or semantic level.
  23
  24 Here is an example of a simple program transformation.
  25 To replace every calls to \verb+foo+ of any expression $x$
  26 to a call to \verb+bar+, create a semantic patch file \verb+ex1.cocci+
  27 (semantic patches usually ends with the \verb+.cocci+  filename extension)
  28 containing:
  29 \begin{verbatim}
  30 @@ expression x; @@
  31
  32 - foo(x)
  33 + bar(x)
  34
  35 \end{verbatim}
  36
  37 Then to ``apply'' the specified program transformation to a set of C files,
  38 simply do:
  39 \begin{verbatim}
  40 $ spatch -sp_file ex1.cocci *.c
  41 \end{verbatim}
  42 %command line:
  43
  44 %can do inplace, or with git, cf chapter on developing ...
  45
  46 %Other approaches
  47 %instead of
  48 %expressing the transformation on the internal representation
  49 %of a C frontend, for instance the abstract syntax tree
  50 %used internally by gcc, which would require for the user
  51 %to learn how to use this internal data structure,
  52
  53 %if can find and transform, can also find, so semantic grep.
  54
  55 %vs regexp
  56 %vs ast
  57
  58 %features:
  59 %src: darcs manual