| 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} |