Debian Codegraph @

tools/spgen/documentation/implementation.tex

raw
1 Much of the documentation of the implementation is contained in the interface files of the source code.
2 %TODO: make a graph illustrating the workflow.
3
4 Some notes:
5 \begin{itemize}
6 \item See \texttt{spgen/source/README.md} for a broad overview of the workflow and dependencies, read \texttt{spgen/source/spgen.ml} for the driver of the program.
7 %\item Terminology: patch rule, context rule, */+/- rule, context\_mode ...
8 \item Several of the modules make extensive use of the AST0 visitor\footnote{\texttt{coccinelle/parsing\_cocci/visitor\_ast0.ml}}. It is used because it abstracts away a lot of the boilerplace code needed for accessing the components of the abstract syntax tree.
9 \item An easy way to debug in \texttt{spgen/source/rule\_body.ml}: add
10 \begin{verbatim}
11 >> Snapshot.add "debug message" >>
12 \end{verbatim}
13 in some function sequence. Then "debug message" will appear in the exact same place it was called in the generated script.
14 \item Absolutely not optimised for performance (in particular, memory).
15
16 \begin{itemize}
17 \item Snapshot need not be purely functional; rule map can be hashtable in mutable record field instead of map (needs to be sorted in get\_result however). However, a map might be beneficial later on if we want to keep various copies for e.g. rule splitting.
18 \item Rule map is converted to string list before printing; no need to do so, could just print directly from rule map. However, this makes for a better separation interface-wise.
19 \item Most importantly, the generally small size of Coccinelle scripts means that performance is not actually a problem in practice.
20 \end{itemize}
21
22 \item spgen needs its own flag in the Coccinelle parser: \texttt{Flag\_parsing\_cocci.generating\_mode}. This ensures that dependencies are not optimised away in the parser, as we need that information for printing the rules properly.
23
24 It cannot be substituted for the \texttt{ignore\_patch\_or\_match} option, because that option also affects other parts of the parser.
25 \item Regression tests: run spgen with flag \texttt{-{}-test <path\_to\_test\_dir} to run the tests. They should be run once before changing anything in the code. The tests test diff equality with expected files (ie. a bit too strict) and that generated files are parsable.
26 \end{itemize}