FreeBSD Manual Pages
SPATCH(1) General Commands Manual SPATCH(1) NAME spatch - apply a semantic patch file to a set of C files SYNOPSIS spatch --sp-file _SP_ _files_ [-o _outfile_ ] [--iso-file _iso_ ] [ op- tions ] DESCRIPTION spatch is a program matching and transformation tool for C. The pro- grammer describes the code to match and the transformation to perform as a semantic patch, which looks like a standard patch, but can trans- form multiple files at any number of code sites. Further information about spatch is available at http://coc- cinelle.lip6.fr/. Semantic patch examples can be found at http://coccinellery.org/, and at the scripts/coccinelle directory of the Linux Kernel source code. OPTIONS Here is a summary of the most commonly used options (also see the "Con- figuration Mechanism" section below): --sp-file _file_ the semantic patch file --dir _dir_ process all files in directory recursively --iso-file _file_ (default=${exec_prefix}/lib/coccinelle/standard.iso) --macro-file _file_ (default=${exec_prefix}/lib/coccinelle/standard.h) --debug print some information to help debug the matching process --all-includes causes all available include files to be used --no-includes causes not even local include files to be used -I _dir_ the directory containing the include files --include-headers process header files independently --use-glimpse works with --dir, use information generated by glimpseindex -o _file_ the output file. If none is specified, a patch is generated on the standard output --in-place do the modification on the file directly --out-place store modifications in a .cocci_res file --version show the version of spatch --date show the date on which spatch was compiled --shorthelp see short list of options --longhelp see all the available options in different categories -help, --help show summary of options. EXAMPLES ./spatch --sp-file foo.cocci foo.c Apply the semantic patch foo.cocci to the C file foo.c. The semantic patch is applied modulo a set of isomorphisms contained in standard.iso (standard.iso is by default located in ${exec_prefix}/lib/coc- cinelle/standard.iso). A patch showing the effect of the application, if any, will be generated on the standard output. ./spatch --sp-file foo.cocci foo.c -o /tmp/newfoo.c The same as the above, except that a modified version of foo.c is stored in /tmp/newfoo.c. It is also possible to apply spatch to all of the C files in a direc- tory: ./spatch --cocci-file foo.cocci --dir foodir If the semantic patch is not working as expected, the option --debug shows selection of information about the application of a semantic patch to a file or directory. MORE OPTIONS MAIN OPTIONS --sp-file <file> the semantic patch file -o <file> the output file --in-place do the modification on the file directly --backup-suffix suffix to use when making a backup for inplace --out-place store modifications in a .cocci_res file --reverse invert the semantic patch before applying it -U set number of diff context lines --partial-match report partial matches of the SP on the C file --iso-file <file> (default=/usr/local/lib/coccinelle/standard.iso) --macro-file <file> --macro-file-builtins <file> (default=/usr/local/lib/coccinelle/standard.h) --recursive-includes causes all available include files, both those included in the C file(s) and those included in header files, to be used --all-includes causes all available include files included in the C file(s) to be used --no-includes causes not even local include files to be used --local-includes causes local include files to be used --ignore-unknown-options For integration in a toolchain (must be set before the first un- known option) --include-headers process header files independently -I <dir> containing the header files (optional) --preprocess run the C preprocessor before applying the semantic match -c gcc/cpp compatibility mode --dir <dir> process all files in directory recursively --use-glimpse works with --dir, use info generated by glimpseindex --use-idutils find relevant files using id-utils --patch <dir> path name with respect to which a patch should be created "" for a file in the current directory --kbuild-info <file> improve --dir by grouping related c files --pyoutput Sets output routine: Standard values: <coccilib.output.Gtk|coc- cilib.output.Console> --version guess what --date guess what --shorthelp see short list of options --longhelp see all the available options in different categories ALIASES AND OBSOLETE OPTIONS --sp command line semantic patch --iso short option of --iso-file --cocci-file <file> the semantic patch file MOST USEFUL SHOW OPTIONS --show-diff --no-show-diff --force-diffshow diff even if only spacing changes --show-flow --ctl-inline-let --ctl-show-mcodekind --show-bindings --show-transinfo --show-misc --show-trying show the name of each function being processed --show-dependencies show the dependencies related to each rule VERBOSE SUBSYSTEMS OPTIONS --verbose-ctl-engine --verbose-match --verbose-engine --graphical-trace generate a pdf file representing the matching process --gt-without-label remove graph label (requires option -graphical-trace) --parse-error-msg --verbose-parsing --type-error-msg OTHER SHOW OPTIONS --show-c --show-cocci --show-before-fixed-flow --show-ctl-tex --show-ctl-text --show-SP DEBUG C PARSING/UNPARSING --debug-cpp --debug-lexer --debug-etdt --debug-typedef --filter-msg filter some cpp message when the macro is a "known" cpp con- struct --filter-define-error --filter-msg-define-error filter the error msg --filter-passed-level --debug-unparsing SHORTCUT FOR ENABLING/DISABLING A SET OF DEBUGGING OPTIONS AT ONCE --quiet --very-quiet --debug --pad BENCH OPTIONS --profile gather timing information about the main coccinelle functions --bench <level> for profiling the CTL engine --timeout <sec> timeout in seconds --steps max number of model checking steps per code unit --iso-limit max depth of iso application --no-iso-limit disable limit on max depth of iso application --track-iso gather information about isomorphism usage --disable-iso disable a specific isomorphism --profile-iso gather information about the cost of isomorphism usage CHANGE OF ALGORITHM OPTIONS --keep-comments keep comments around removed code --loop --no-loops drop all back edges derived from looping constructs - unsafe --no-gotos drop all jumps derived from gotos - unsafe --no-saved-typedefs drop all inferred typedefs from one parse of some code to the next --ocaml-regexps use OCaml Str regular expressions for constraints --l1 --ifdef-to-if convert ifdef to if (experimental) --no-ifdef-to-if convert ifdef to if (experimental) --disable-multi-pass --noif0-passing --defined --undefined --noadd-typedef-root --disallow-nested-exps disallow an expression pattern from matching a term and its sub- term --disable-worth-trying-opt --only-return-is-error-exitif this flag is not set, then break and con- tinue are also error exits --allow-inconsistent-paths if this flag is set don't check for inconsistent paths; danger- ous --no-safe-expressions make an expression disjunction not prioritise the topmost dis- junct --int-bits the number of bits in an unsigned int --long-bits the number of bits in an unsigned long --linux-spacing spacing of + code follows the conventions of Linux --smpl-spacing spacing of + code follows the semantic patch -D indicate that a virtual rule should be considered to be matched --c++ make a small attempt to parse C++ files. The supported exten- sions for source files are .cpp, .cxx, .cc, and for header files are .h, .hpp and .hxx. Note that this option disables the pro- cessing of .c files as Coccinelle behaviour is different for C++. MISC OPTIONS --debugger option to set if launch spatch in ocamldebug --disable-once to print more messages --show-trace-profile show trace --save-tmp-files CONCURRENCY --index the processor to use for this run of spatch --max the number of processors available --mod-distrib use mod to distribute files among the processors PAD OPTIONS --use-cache use .ast_raw pre-parsed cached C file --cache-prefix directory of cached ASTs, sets --use-cache --cache-limit maximum number of cached ASTs, sets --use-cache TEST MODE AND TEST OPTIONS (WORKS WITH TESTS/ OR .OK FILES) The test options don't work with the --sp-file and so on. --test <file> launch spatch on tests/file.[c,cocci] --testall launch spatch on all files in tests/ having a .res --test-okfailed generates .{ok,failed,spatch_ok} files using .res files --test-regression-okfailed process the .{ok,failed,spatch_ok} files in current dir --compare-with-expected use also file.res --expected-score-file which score file to compare with in --testall --no-update-score-file do not update the score file when --testall succeeds --relax-include-path ACTION MODE The action options don't work with the --sp-file and so on. It's for the other (internal) uses of the spatch program. --tokens-c <file> --parse-c <file or dir> --parse-h <file or dir> --parse-ch <file or dir> --parse-i <file or dir> --parse <file or dir> --show-flow <file or file:function> --control-flow <file or file:function> --control-flow-to-file <file or file:function> --test-cfg-ifdef <file> --parse-unparse <file> --type-c <file> --compare-c <file1> <file2> --comment-annotater-c <file> --compare-c-hardcoded --test-attributes <file> --test-cpp <file> --extract-macros <file or dir> --extract-macros-select <file or dir> --xxx <file1> <> --parse-cocci <file> --compare-c <file1> <file2> CONFIGURATION MECHANISM Coccinelle uses a simple text format to store customizations into in which the configuration file is processed is as follows, where the later lines always extend and may override earlier ones: o Your current user's home directory is processed first o Your directory from which spatch is called is processed next o The directory provided with the --dir option is processed last, if used Such a configuration file may look like this: [spatch] options = --jobs 4 options = --show-trying FILES ${exec_prefix}/lib/coccinelle/standard.iso This file contains the default set of isomorphisms. ${exec_prefix}/lib/coccinelle/standard.h This file contains the default set of macro hints. .cocciconfig This file contains the custom set of spatch options. ENVIRONMENT COCCINELLE_HOME The path to the Coccinelle share directory. Default is ${exec_prefix}/lib/coccinelle REFERENCES Y. Padioleau, J.L. Lawall, R.R Hansen, G. Muller. "Documenting and Au- tomating Collateral Evolutions in Linux Device Driver", EuroSys 2008 , Glasgow, Scotland, April 2008, pp. 247-260. Julien Brunel, Damien Doligez, RenA(C) Rydhof Hansen, Julia L. Lawall, Gilles Muller. "A foundation for flow-based program matching: using temporal logic and model checking", POPL 2009 , Savannah, GA, USA, Jan- uary 21-23, 2009, pp. 114-126. AUTHOR spatch was written by Julia Lawall <julia.lawall@lip6.fr>, Yoann Padi- oleau <yoann.padioleau@gmail.com>, Rene Rydhof Hansen <rrh@cs.aau.dk>, Henrik Stuart <henrik@hstuart.dk>, Nicolas Palix <nico- las.palix@imag.fr>, Peter Senna Tschudin <peter.senna@gmail.com>, SA(C)bastien Hinderer <Sebastien.Hinderer@inria.fr>, Xavier Clerc <xavier.clerc@inria.fr> and Matthieu Caneill <matthieu.caneill42@gmail.com>. This manual page was written by Yoann Padioleau <yoann.padi- oleau@gmail.com>, Julia Lawall <julia.lawall@lip6.fr>, Nicolas Palix <nicolas.palix@imag.fr> and Peter Senna Tschudin <pe- ter.senna@gmail.com>. REPORTING BUGS Send a mail to <cocci@systeme.lip6.fr> COPYRIGHT Copyright 2012, 2015, INRIA and University of Grenoble-Alpes LIG. Copyright 2010, 2011, University of Copenhagen DIKU and INRIA. Copy- right 2005-2009, Ecole des Mines de Nantes, University of Copenhagen. spatch is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, according to version 2 of the License. SEE ALSO patch(1), diff(1) Feb 26, 2015 SPATCH(1)
NAME | SYNOPSIS | DESCRIPTION | OPTIONS | EXAMPLES | MORE OPTIONS | CONFIGURATION MECHANISM | FILES | ENVIRONMENT | REFERENCES | AUTHOR | REPORTING BUGS | COPYRIGHT | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=spatch&sektion=1&manpath=FreeBSD+13.0-RELEASE+and+Ports>