======================================================================
Quick sparse HOWTO
Randy Dunlap
2007-JULY-28

in kernel tree, 'make help' says:

  make C=1   [targets] Check all c source with $CHECK (sparse by default)
  make C=2   [targets] Force check of all c source with $CHECK

To build & install sparse:

a.  unpack the tarball or grab the 'git' tree
b.  cd path/to/sparse
c.  make
d.  make install     # default location is in user's $HOME/bin

...then do your target build, e.g.,

make allmodconfig     # or defconfig or whatever
make C=1 all >build.out 2>&1     # to capture all messages

======================================================================
sparse command-line options:
(compare to gcc options for more help)


  -Dname[= ]value		define name as value
  -dirafter path
  -E				preprocess only
  -f[no-]flag			set or reset flag (not used)
  -G 0				ignored
  -I[- | path]			specify include path
  -include path			specify include path
  -imacros filename		specify macros filename
  -isystem dir			search dir for header files, after all
				directories specified by -I but before the
				standard system directories
  -k[c]				check for use of C keywords as identifiers
  -kp				check for use of C & C++ keywords as identifiers
  -MF | -MQ | -MT
  -m64				cross-check: set bits_in_long = 64,
				  max_int_alignment = 8,
				  bits_in_pointer = 64,
				  pointer_alignment = 8
  -msize-long
  -nostdinc
  -O[0..9 | s]			set optimize level or for size
  -o foo			ignored
  -U name			undef name
  -v				verbose mode
  -v [entry | dead]		debug switches
  -W[no[-]]<warnings>		enable or disable warnings;
				the Linux Makefile enables "bitwise";
			all {enable/disable all Warnings}
			address-space [on]
			bitwise [off]
			cast-to-as {address-space} [off]
			cast-truncate [on]
			context {checks balanced locking/unlocking} [on]
			decl [on]
			default-bitfield-sign [off]
			do-while [on]
			enum-mismatch [on]
			non-pointer-null [on]
			old-initializer {check for using pre-C99 inits} [on]
			one-bit-signed-bitfield [on]
			paren-string [off]
			ptr-subtraction-blows [off]
			return-void {checks for return <expr> in a
				void function} [off]
			shadow {checks for shadow variables} [off]
			transparent-union [on]
			typesign [off]
			undef {undefined preprocessor} [off]
			uninitialized [on]


When used with a linux/ Makefile, use CF to add extra check flags to sparse.
E.g.:

make C=2 CF=-Wshadow fs/nfs*/

make C=2 CF=-D__CHECK_ENDIAN__ fs/nfs*/
======================================================================
Other sparse references/resources:

  Mailing list:  linux-sparse@vger.kernel.org
 
  in sparse tree:  FAQ, README

  in kernel tree:  Documentation/sparse.txt

  git repository:  git://git.kernel.org/pub/scm/linux/kernel/git/josh/sparse.git

  sparse releases:  http://www.kernel.org/pub/software/devel/sparse/

  sparse snapshots:  http://www.codemonkey.org.uk/projects/git-snapshots/sparse/
 
  sparse presentation (old):  http://developer.osdl.org/dmo/sparse/

###