Debian Codegraph @

tools/spgen/documentation/usage.tex

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