"Fossies" - the Fresh Open Source Software Archive 
Member "ncc-2.8/doc/NCC" (28 Aug 2007, 11032 Bytes) of package /linux/privat/old/ncc-2.8.tar.gz:
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1 ncc 2.7
2 - see doc/CHANGES for the new stuff
3
4
5 WHATIS
6 ======
7
8
9 Basically, ncc is a tool for hackers designed to provide program analysis
10 data of C source code. That is program flow and usage of variables.
11 Some big programs out there are by default obfuscated, either due to extreme
12 size, programming style, hacks upon hacks and other crazyness. In order to
13 do program analysis correctly, there has to be compilation of expressions,
14 and thus ncc is really a compiler (supporting zero architectures).
15
16 At the same time, ncc is small and easy to understand so you can hack it and
17 add custom features and extensions at any stage of the compilation, to match
18 what you expect and consider useful as output. Most common GNU extensions
19 are supported and there has been an effort be practically useful in the GNU
20 system (which is not easy because the GNU system is very gcc-friendly).
21 The goal is to be able to replace 'ncc' in Makefiles and work with the big
22 open source projects.
23
24 In the latest versions of ncc, some advanced analysis features have been
25 implemented and they are about pointer-to-function variables and the values
26 assigned to them. The sample files doc/fptrs.c and doc/farg.c can be
27 analysed with ncc to demonstrate what can be done there.
28
29 In version 2.0 ncc can emulate the linker behavior to join ncc output files
30 and can also act as a wrapper for some binutils programs that are used
31 for linking.
32
33
34 INSTALL
35 =======
36
37 Either 'make install' as root, or:
38
39 1. 'make' and the file ncc should appear in objdir/
40
41 2. Copy the file doc/nognu to /usr/include.
42
43 This file is used to fix some madness of libc header files and remove some
44 GNU extensions which violate the C grammar and can be removed without
45 problems. If you don't want to copy it to /usr/include, edit config.h and
46 recompile.
47
48 3. With make the file 'nccnav' should also appear in nccnav.
49 Copy this file to /usr/bin and make a symbolic link nccnavi -> nccnav if
50 you want auto-indent
51
52
53
54 Invoking ncc
55 ------------
56
57 USAGE
58 =====
59
60 The simple way to use ncc on a C program hello.c, is with the
61 command : ncc hello.c
62
63 The default output (at stdout) is that for every function defined in hello.c
64 the following things are reported :
65
66 - function calls
67 - pointer to function assigned values
68 - use of global variables
69 - use of members of structures
70
71 The latter has been proved very useful in understanding what
72 a function actually does.
73
74 The options of ncc start with "-nc".
75
76 with "-ncmv" each use of global variable, function or member of structure is
77 reported multiple times as used. This is a way to understand better how the
78 code works, by looking the use of variables between function calls.
79 -nccnav can't display that-
80
81 with "-nchelp" help is displayed on the -nc options.
82
83 with "-ncoo" the output goes to a file sourcefile.c.nccout
84
85 with "-ncld" the output goes to a file sourcefile.o.nccout
86 or to the file specified with the command line option "-c"
87 and the extension nccout. Moreover in this mode ncc does
88 linker emulation. Described below.
89
90 with "-ncspp" the preprocessed file is kept in sourcefile.i
91
92 with "-ncfabs" absolute pathnames are reported.
93
94 with "-ncnoerror" if there are syntax errors in expressions ncc
95 will link the function with a special "NCC:syntax_error()" function
96 instead of terminating the compilation.
97
98
99 STUDYING THE OUTPUT & PROGRAM ANALYSIS
100 ========================================
101
102 ncc is a very useful tool in exploring programs but equally useful is the
103 included program `nccnav'. The output of ncc is such that can be easilly
104 loaded by some other graphical viewer. nccnav can do this and has some nice
105 features like the recursion detector.
106
107 So once you learn HOW to run ncc on programs, make sure to read
108 nccnav/README.
109
110 The output can also be viewed using the graphviz program. See the section
111 GRAPHVIZ below.
112
113
114 GCC-PREPROCESSING
115 =================
116
117 ncc uses gcc for preprocessing because the standard library headers
118 eventually need some other architecture specific header which are somewhere
119 where gcc knows where. Any options starting with -D and -I will be passed
120 to gcc for preprocessing. Generally, because ncc should be able to work
121 from makefiles instead of gcc, all options unless starting with '-nc'
122 produce no error (and may be even passed to gcc in a special mode).
123
124 The files compiled with ncc, will have the __GCC__ macro defined, because many
125 programs are written for gcc and take some gcc extensions for granted.
126 ncc additionally defines __NCC__ macro.
127
128
129
130 (example) HACKING mpg123
131 ========================
132
133 This one is easy (because it's done "the right way", programs are
134 exponential: the number of tasks a program can do is N^2 if N are the lines
135 of code. Thus any program of more than 50000 lines has probably design flaws
136 (unless it's device drivers))
137
138 Anyway, to view the calls of mpg123, the command is:
139
140 for a in *.c; do ncc $a -ncoo; done
141 cat *.nccout > Code.map
142 nccnav
143
144 or alternativelly:
145
146 ncc *.c > Code.map
147
148
149 HACKING BIGGER PROGRAMS
150 =======================
151
152 The obvious way is to use make with ncc, so that the required -D and -I
153 options are invoked, and only the right files are compiled (if there
154 are depenencies). Normally, changing "CC=gcc" to "CC=ncc -ncoo" would be
155 enough. But alas! some times it isn't.
156
157 Sometimes the make procedure expects object files which ncc does not produce
158 and it may fail. This can be prevented with 'make -i' where make ignores
159 errors.
160
161 Some other programs compile and run helpers during make. If all else
162 fails, the last resort that always works, is using the "-ncgcc" option.
163
164 with "-ncgcc", ncc will also run gcc in parallel with all it's options except
165 the -nc ones. So nobody will understand that ncc was even run and the
166 makefiles will be happy. It takes 1000% more time, but computers do get
167 faster every day. In this case, it is generally a good idea to remove any
168 '-O2 -g' options.
169
170 Make sure you read doc/TROUBLES if you're going to use ncc in big GNU
171 projects (and not only).
172
173 hacking.LINUX-KERNEL, hacking.GCC, hacking.GLIBC, and other files in doc/
174 have specific instructions on using ncc on some *really big* programs which
175 may need a couple of tricks to get it done.
176
177
178 LINKER EMULATION
179 ================
180
181 The best job is done by using ncc in the makefile in parallel with the
182 normal compilation. For serious work, use
183
184 CC=ncc -ncgcc -ncld -ncspp -ncfabs
185
186 The option "-ncld" instructs ncc to attempt to link ncc output files
187 as gcc would create object files. For example, the command
188
189 ncc -ncld -ncgcc -c file1.c
190
191 will generate the files "file1.o" and "file1.o.nccout"
192 The command
193
194 ncc -ncld -ncgcc file2.c file1.o -o myprog
195
196 will generate the files "myprog" and "myprog.nccout", where the second
197 file will be the analysis of file2.c plus the file file1.o.nccout.
198
199 Moreover, ncc can be called as "nccar", "nccld", "nccg++" and "nccc++".
200 In this case, the corresponding program will be called normally
201 with all the options passed and then ncc will attempt to locate
202 object files with the extension 'nccout' and link them in a bigger
203 nccout file. So it's even better to say
204
205 AR = nccar
206 LD = nccld
207 CXX = nccg++
208
209 The advantage of this method is that we don't have to collect the
210 nccout files afterwards. Usually all the right files will have been
211 concatenated into one big nccout file at the end of compilation.
212
213 This method works best when gcc is used to link the object files, and
214 also works pretty well with ar and ld. However, there are projects
215 out there that use crazy Makefiles and libtool, that need special
216 hacks to achieve this.
217
218 Output Details
219 --------------
220
221 POINTERS TO FUNCTIONS
222 =====================
223
224 ncc does not only report which pointer to function variables are called, but
225 also which values are assigned to them. Pointers to functions are reported
226 as pseudo-functions which call *all* the values assigned to them.
227
228 So the caller -> callee relation is different. While the code of a normal
229 function calls all its callees, a pointer to function will call any one of
230 its callees.
231
232
233 RELEVANT NOTES
234 ==============
235
236 - Anonymous typedef'd structures are automatically named after the typedef.
237 For example:
238 typedef struct {
239 int x, y;
240 } Point;
241 int main ()
242 {
243 Point P;
244 P.x = 3;
245 }
246 ncc will report that 'main' uses member 'x' of structure 'Point', although
247 the structure is really anonymous. Conflicts *should* be extremely rare.
248
249
250 TROUBLESHOOTING
251 ===============
252
253 Thanks to open source, there are infinitive test cases.
254 ncc has been tested with:
255
256 linux kernel 2.2 (partial according to depend),
257 Imagemagick, gcc, Doom (you gotta see this source!),
258 xanim, mpg123, bladeenc, bzip2, gtk, gnu-fileutils,
259 less, mpeg_play, nasm, ncftp, vim, sox, bind, gdb, flames,
260 xrick (Rick Dangerous!), inform (Text adventure language),
261 linux kernel 2.4.20, zsh, zile, emacs, gnuchess, bash,
262 python, elinks, linux kernel 2.6.9, pygame, jamvm, perl5,
263 linux 2.17, gcc 4.2, x.org 7.1, git, qemu, ffmpeg, libjpeg,
264 openssh
265
266 although these programs are correct and ncc lacks testing on finding errors
267 on programs with syntax errors.
268
269 In the case ncc complains about syntax errors or segfaults, check out
270 the file TROUBLES for the way to hunt down the bug. Sometimes just
271 adding something to nognu macros is enough to continue the compilations.
272
273
274 Viewers
275 -------
276
277 CODEVIZ
278 =======
279
280 CodeViz is a collection of C/C++ analysis tools by Mel Gorman.
281 See http://freshmeat.net/projects/codeviz
282
283 The CodeViz perl scripts recognize the .nccout format of ncc.
284 If you have concatenated all the .nccout files of a projects to say
285 'everything.nccout'
286
287 You can do:
288 genfull -g cncc -f everything.nccout
289 to generate the full.graph file. Then:
290 gengraph -f some_function -d depth
291 to generate a nice postscript graph of the call tree.
292
293
294 GRAPHVIZ
295 ========
296
297 Jose Vasconcellos has sent a python script which converts ncc output
298 to dot data. The dot command is part of the Graphviz package and it's
299 used by codeviz to generate the graph. More about graphviz at:
300
301 http://www.graphviz.org
302
303 The script scripts/gengraph.py can be called like this:
304
305 gengraph.py code.map main | dot -Tsvg -o graph.svg
306
307 to generate a nice SVG graph of the callgraph.
308 The zgrviewer at http://zvtm.sourceforge.net/zgrviewer.html
309 is great for viewing large graphs. Still, it's a good idea
310 to specify depth because some graphs are **really** big:)
311
312
313
314 THEREST
315 =======
316
317 Program written & Copyright (C) Stelios Xanthakis 2002, 2003, 2004, 2005, 2006, 2007
318 Distributed under the terms of the Artistic License.
319 e-mail: sxanth@ceid.upatras.gr
320 ncc latest download: http://students.ceid.upatras.gr/~sxanth/ncc/
321
322 Many contributions and feedback from Scott McKellar <jm407a@sbc.com>
323 who now is the other person who knows `how ncc works'.
324 Additional hacks for kernel 2.6 by Ben Lau <benlau@linux.org.hk>
325 gengraph.py is Copyright (C) 2004 Jose Vasconcellos and GPL.
326
327 Also thanks to:
328 Sylvain Beucler, Anuradha Weeraman, Florian Larysch,
329 Deepak Ravi, Thomas Petazzoni, Adam Shostack,
330 Hakon Lovdal, Awesome Walrus