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
  43
  44 Coccinelle primarily targets ANSI C, and supports some GCC extensions.  It
  45 has only partial support for K\&R C.  K\&R function declarations are only
  46 recognized if the parameter declarations are indented.  Furthermore, the
  47 parameter names are subsequently considered to be type names, due to
  48 confusion with function prototypes, in which a name by itself is indeed the
  49 name of a type.
  50
  51
  52 %command line:
  53
  54 %can do inplace, or with git, cf chapter on developing ...
  55
  56 %Other approaches
  57 %instead of
  58 %expressing the transformation on the internal representation
  59 %of a C frontend, for instance the abstract syntax tree
  60 %used internally by gcc, which would require for the user
  61 %to learn how to use this internal data structure,
  62
  63 %if can find and transform, can also find, so semantic grep.
  64
  65 %vs regexp
  66 %vs ast
  67
  68 %features:
  69 %src: darcs manual
  70
  71 %%% Local Variables:
  72 %%% mode: LaTeX
  73 %%% coding: utf-8
  74 %%% TeX-PDF-mode: t
  75 %%% ispell-local-dictionary: "american"
  76 %%% End: