\subsection{Installation and uninstallation} \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: \begin{enumerate} \item Run \texttt{make} to compile the program. \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. \item (Optional) Try out the program by running \texttt{spgen examples/addvoid.cocci}. \end{enumerate} \textbf{To uninstall}: From the \texttt{spgen} directory, do: \begin{enumerate} \item Run \texttt{make uninstall}$^{\ref{sudo}}$. \end{enumerate} \bigskip \subsection{Running the program} The most common usages are as follows, for a semantic patch file \texttt{foo.cocci} and an spgen config file \texttt{foo.config}: \begin{itemize} \item \texttt{spgen foo.cocci}: Generate the file with the information found d in \texttt{foo.config} if it exists. If not, the program is run in interactive mode. \item \texttt{spgen -{}-config foo.config foo.cocci}: Generate the file with \texttt{foo.config} as the configuration file. The shorthand \texttt{-c} can be used instead of \texttt{-{}-config}. \item \texttt{spgen foo.cocci -{}-interactive}: Run the program in interactive mode. The shorthand \texttt{-i} can be used instead of \texttt{-{}-interactive}. \end{itemize} Additional options: \begin{itemize} \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). \item \texttt{-o }: Saves the generated file to \texttt{} instead of printing it to standard output. \item \texttt{-{}-no-output}: Generates the file, but doesn't output the result. \item \texttt{-help, -{}-help}: Displays the list of options. \end{itemize} \bigskip \subsection{User input} When generating a script, \texttt{spgen} might need some extra information from the user. There are two kinds of information: \begin{itemize} \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}. \item \textbf{Rule information}: rule-specific info, such as error messages that are output in \texttt{org} and \texttt{report} mode. \end{itemize} There are two ways of passing this information, interactive mode and configuration mode. \bigskip \subsubsection{Interactive mode\label{interact}} 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. \bigskip \subsubsection{Configuration mode\label{config}} In configuration mode, the program looks for an \texttt{spgen} config file to provide the needed information to generate the file. For \texttt{}.cocci, the config file should be called \texttt{}.config. The user-specified attributes in the \textbf{preface} are, in no specific order ((r) means required): \begin{center} \renewcommand{\arraystretch}{1.2} \begin{tabular}{p{3cm}p{2.1cm}p{3.6cm}p{5.5cm}} \textbf{Attribute name} & \textbf{Shorthand} & \textbf{Value} & \textbf{Description}\\ \texttt{description} (r) & \texttt{d} & Single-value text & Describes what the script does.\\ \texttt{confidence} (r) & \texttt{c} & Low, Moderate, High & Confidence level for the script.\\ \texttt{authors} & \texttt{a} & Multi-value text & Authors of the script, including affiliation and license.\\ \texttt{url} & \texttt{u} & Single-value text & URL for the script.\\ \texttt{limitations} & \texttt{l} & Multi-value text & Limitations for the script.\\ \texttt{keywords} & \texttt{k} & Single-value text & Keywords for the script.\\ \texttt{options} & \texttt{o} & Single-value text &\texttt{spatch} options with which to run the script.\\ \texttt{comments} & \texttt{m} & Single-value text & Additional comments.\\ \end{tabular} \end{center}\vspace{0.5cm} 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}. \clearpage \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 ...: \begin{itemize} \item The syntax for attributes is \begin{verbatim} = \end{verbatim} where \texttt{} can be either the attribute name or its shorthand. The end of \texttt{} is marked by a newline. It is therefore not possible to insert newlines in any of the values. \item For multi-valued attributes, values are delimited by pipes, \texttt{|}, ie. \begin{verbatim} = ||...| \end{verbatim} \item Error messages for rules follow the syntax \begin{verbatim} = org: report: \end{verbatim} for \texttt{org} and \texttt{report} error messages, respectively. Here, \texttt{} is either the actual rule name, or, if it is a nameless rule, \texttt{:}.\newline Meanwhile, \texttt{} follow the syntax of \texttt{python} format strings, e.g. \begin{verbatim} "This is a message that references two metavariables %s and %s." % (x,y) \end{verbatim} where \texttt{x} and \texttt{y} are metavariables in the rule. If using metavariables from another rule, write \texttt{.}. If using no metavariables, just write the error message surrounded by quotes. \item Comments can be written in \texttt{C}-style, ie. \texttt{//} and \texttt{/**/}. \end{itemize} \bigskip \subsection{Examples} Example files can be found in the \texttt{examples} directory. For each example, there should be four files. The file extensions denote the following: \begin{itemize} \item \texttt{.c}: \texttt{C} source file that returns matches/patches for the corresponding cocci file. Can be tested with \texttt{spatch --sp-file .cocci .c}. \item \texttt{.cocci}: simple, unhardened Coccinelle script. \item \texttt{.config}: \texttt{spgen} configuration file for specifying preface and rule information. \item \texttt{\_.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 \_.cocci .c -D report --no-show-diff}. \end{itemize} %PSEUDOGRAMMAR: %\begin{center} %\renewcommand{\arraystretch}{1.2} %\begin{tabular}{p{3cm}p{11cm}} %config : & (declaration) NL (config) \newline EOF \\ %declaration: & (attribute) = (value) \newline % (attribute) = (multivalue) \newline % (rulename) = (messages) \\ %attribute : & description \newline % comments ... \\ %value : & string (no newline) \\ %multivalue : & value | multivalue \newline % value \\ %rulename : & string (rulename) \newline % int : string (line, new rule) \\ %messages : & org : (message) NL report : (message) \newline % org : (message) \newline % report : (message) \\ %message : & "string" \newline "string" \% metavariables %\end{tabular} %\end{center}