| 1 |
\subsection{Installation and uninstallation} |
| 2 |
\textbf{To install}: You need to have \texttt{Coccinelle} and all its dependencies installed. You also need to have the \texttt{Coccinelle} source code available. By default, the \texttt{spgen} directory lies within the \texttt{Coccinelle} directory in \texttt{coccinelle/tools/spgen}.\footnote{If you change this, you need to modify the \texttt{COCCIDIR} path in \texttt{source/Makefile} to point to the \texttt{Coccinelle} source code directory.} From the \texttt{spgen} directory, do: |
| 3 |
\begin{enumerate} |
| 4 |
\item Run \texttt{make} to compile the program. |
| 5 |
\item Run \texttt{make install}\footnote{If permission is denied, run it in superuser mode e.g. \texttt{sudo make install}, depending on your system.\label{sudo}} to install the program. |
| 6 |
\item (Optional) Try out the program by running \texttt{spgen examples/addvoid.cocci}. |
| 7 |
\end{enumerate} |
| 8 |
\textbf{To uninstall}: From the \texttt{spgen} directory, do: |
| 9 |
\begin{enumerate} |
| 10 |
\item Run \texttt{make uninstall}$^{\ref{sudo}}$. |
| 11 |
\end{enumerate} |
| 12 |
\bigskip |
| 13 |
|
| 14 |
\subsection{Running the program} |
| 15 |
The most common usages are as follows, for a semantic patch file \texttt{foo.cocci} and an spgen config file \texttt{foo.config}: |
| 16 |
\begin{itemize} |
| 17 |
\item \texttt{spgen foo.cocci}: Generate the file with the information found |
| 18 |
d in \texttt{foo.config} if it exists. If not, the program is run in interactive mode. |
| 19 |
\item \texttt{spgen -{}-config foo.config foo.cocci}: Generate the file with |
| 20 |
\texttt{foo.config} as the configuration file. The shorthand \texttt{-c} can be used instead of \texttt{-{}-config}. |
| 21 |
\item \texttt{spgen foo.cocci -{}-interactive}: Run the program in interactive mode. The shorthand \texttt{-i} can be used instead of \texttt{-{}-interactive}. |
| 22 |
\end{itemize} |
| 23 |
Additional options: |
| 24 |
\begin{itemize} |
| 25 |
\item \texttt{-{}-default}: Generates the file, entirely using default values, such as generic error messages, instead of user input. Can, e.g., be used to quickly check the generated context rule(s). |
| 26 |
\item \texttt{-o <filename>}: Saves the generated file to \texttt{<filename>} instead of printing it to standard output. |
| 27 |
\item \texttt{-{}-no-output}: Generates the file, but doesn't output the result. |
| 28 |
\item \texttt{-help, -{}-help}: Displays the list of options. |
| 29 |
\end{itemize} |
| 30 |
\bigskip |
| 31 |
|
| 32 |
\subsection{User input} |
| 33 |
When generating a script, \texttt{spgen} might need some extra information from the user. There are two kinds of information: |
| 34 |
\begin{itemize} |
| 35 |
\item \textbf{Preface}: information to go at the beginning of the script. Contains metainformation about the script such as description, author, etc. See the full list in Section \ref{config}. |
| 36 |
\item \textbf{Rule information}: rule-specific info, such as error messages that are output in \texttt{org} and \texttt{report} mode. |
| 37 |
\end{itemize} |
| 38 |
There are two ways of passing this information, interactive mode and configuration mode. |
| 39 |
\bigskip |
| 40 |
|
| 41 |
\subsubsection{Interactive mode\label{interact}} |
| 42 |
In interactive mode, the program prompts the user for the information through the commandline. The user can then choose to save the information into an \texttt{spgen} config file, which can be further modified and reused in configuration mode. |
| 43 |
\bigskip |
| 44 |
|
| 45 |
\subsubsection{Configuration mode\label{config}} |
| 46 |
In configuration mode, the program looks for an \texttt{spgen} config file to provide the needed information to generate the file. For \texttt{<file>}.cocci, the config file should be called \texttt{<file>}.config. |
| 47 |
|
| 48 |
The user-specified attributes in the \textbf{preface} are, in no specific order ((r) means required): |
| 49 |
\begin{center} |
| 50 |
\renewcommand{\arraystretch}{1.2} |
| 51 |
\begin{tabular}{p{3cm}p{2.1cm}p{3.6cm}p{5.5cm}} |
| 52 |
|
| 53 |
\textbf{Attribute name} & \textbf{Shorthand} & \textbf{Value} & \textbf{Description}\\ |
| 54 |
|
| 55 |
\texttt{description} (r) & \texttt{d} & Single-value text & Describes what the script does.\\ |
| 56 |
|
| 57 |
\texttt{confidence} (r) & \texttt{c} & Low, Moderate, High & Confidence level for the script.\\ |
| 58 |
|
| 59 |
\texttt{authors} & \texttt{a} & Multi-value text & Authors of the script, including affiliation and license.\\ |
| 60 |
|
| 61 |
\texttt{url} & \texttt{u} & Single-value text & URL for the script.\\ |
| 62 |
|
| 63 |
\texttt{limitations} & \texttt{l} & Multi-value text & Limitations for the script.\\ |
| 64 |
|
| 65 |
\texttt{keywords} & \texttt{k} & Single-value text & Keywords for the script.\\ |
| 66 |
|
| 67 |
\texttt{options} & \texttt{o} & Single-value text &\texttt{spatch} options with which to run the script.\\ |
| 68 |
|
| 69 |
\texttt{comments} & \texttt{m} & Single-value text & Additional comments.\\ |
| 70 |
\end{tabular} |
| 71 |
\end{center}\vspace{0.5cm} |
| 72 |
The \textbf{rule information} contains error messages for \texttt{org} and \texttt{report}, and possibly rule names for rules that are unnamed in the original \texttt{Coccinelle script}. |
| 73 |
|
| 74 |
\clearpage |
| 75 |
\noindent The syntax for the \texttt{spgen} config files is rather simple, and the easiest way to learn it is to run \texttt{spgen} in interactive mode and study the resulting config. But for completeness ...: |
| 76 |
|
| 77 |
\begin{itemize} |
| 78 |
\item The syntax for attributes is |
| 79 |
\begin{verbatim} |
| 80 |
<attribute_name> = <value> |
| 81 |
\end{verbatim} |
| 82 |
where \texttt{<attribute\_name>} can be either the attribute name or its shorthand. The end of \texttt{<value>} is marked by a newline. It is therefore not possible to insert newlines in any of the values. |
| 83 |
\item For multi-valued attributes, values are delimited by pipes, \texttt{|}, ie. |
| 84 |
\begin{verbatim} |
| 85 |
<attribute_name> = <value_1>|<value_2>|...|<value_n> |
| 86 |
\end{verbatim} |
| 87 |
\item Error messages for rules follow the syntax |
| 88 |
\begin{verbatim} |
| 89 |
<rule_name> = |
| 90 |
org:<message> |
| 91 |
report:<message> |
| 92 |
\end{verbatim} |
| 93 |
for \texttt{org} and \texttt{report} error messages, respectively. Here, \texttt{<rule\_name>} is either the actual rule name, or, if it is a nameless rule, \texttt{<line\_that\_rule\_starts\_on>:<new\_name>}.\newline |
| 94 |
Meanwhile, \texttt{<message>} follow the syntax of \texttt{python} format strings, e.g. |
| 95 |
\begin{verbatim} |
| 96 |
"This is a message that references two metavariables %s and %s." % (x,y) |
| 97 |
\end{verbatim} |
| 98 |
where \texttt{x} and \texttt{y} are metavariables in the rule. If using metavariables from another rule, write \texttt{<other\_rule\_name>.<metavar\_name>}. If using no metavariables, just write the error message surrounded by quotes. |
| 99 |
\item Comments can be written in \texttt{C}-style, ie. \texttt{//} and \texttt{/**/}. |
| 100 |
|
| 101 |
\end{itemize} |
| 102 |
\bigskip |
| 103 |
|
| 104 |
\subsection{Examples} |
| 105 |
Example files can be found in the \texttt{examples} directory. For each example, there should be four files. The file extensions denote the following: |
| 106 |
\begin{itemize} |
| 107 |
\item \texttt{<name>.c}: \texttt{C} source file that returns matches/patches for the corresponding cocci file. Can be tested with \texttt{spatch --sp-file <name>.cocci <name>.c}. |
| 108 |
\item \texttt{<name>.cocci}: simple, unhardened Coccinelle script. |
| 109 |
\item \texttt{<name>.config}: \texttt{spgen} configuration file for specifying preface and rule information. |
| 110 |
\item \texttt{<name>\_.cocci}: expected output when running \texttt{spgen} on the unhardened Coccinelle script with the config file. Should be a valid, hardened Coccinelle script. Can be tested with e.g. \texttt{spatch --sp-file <name>\_.cocci <name>.c -D report --no-show-diff}. |
| 111 |
\end{itemize} |
| 112 |
|
| 113 |
%PSEUDOGRAMMAR: |
| 114 |
%\begin{center} |
| 115 |
%\renewcommand{\arraystretch}{1.2} |
| 116 |
%\begin{tabular}{p{3cm}p{11cm}} |
| 117 |
%config : & (declaration) NL (config) \newline EOF \\ |
| 118 |
%declaration: & (attribute) = (value) \newline |
| 119 |
% (attribute) = (multivalue) \newline |
| 120 |
% (rulename) = (messages) \\ |
| 121 |
%attribute : & description \newline |
| 122 |
% comments ... \\ |
| 123 |
%value : & string (no newline) \\ |
| 124 |
%multivalue : & value | multivalue \newline |
| 125 |
% value \\ |
| 126 |
%rulename : & string (rulename) \newline |
| 127 |
% int : string (line, new rule) \\ |
| 128 |
%messages : & org : (message) NL report : (message) \newline |
| 129 |
% org : (message) \newline |
| 130 |
% report : (message) \\ |
| 131 |
%message : & "string" \newline "string" \% metavariables |
| 132 |
%\end{tabular} |
| 133 |
%\end{center} |