
nccnav is used explore the output of ncc in a convenient manner for
hacking.

INSTALL & EXTERNAL VIEWER
=========================

As of version 1.3 of ncc, nccnav can invoke an external viewer to browse
source code.

To install nccnav, copy the file nccnav to /usr/bin.
Then make a symbolic link nccnavi -> nccnav

If called as "nccnav" the source code will be viewed with "less".
If called as "nccnavi" the source will be automatically indented
 and viewed with "indent -kr -st | less"

INPUT
=====

Supposing you've compiled the linux kernel with ncc.
Collecting all the .nccout files can be done with :

	find . -name \*.nccout | xargs cat > kernel.map

You can use the pathremover which is found in the
 current directory to truncate long paths in `kernel.map'.
 If you want to compile and install pathremover, the above
 command will be something like:

	find . -name \*.nccout | xargs cat | pathremover /mnt/src/hacks/linux-2.4.10/ > kernel.map

Then, that's viewed with:

	nccnav kernel.map

DISPLAY
=======

nccnav is designed to run in a text console. The ideal display
is a black&white framebuffer 132x50 text mode.  Of course, it can
be executed in an xterm window, but this usually sucks.

In the framebuffer case, the colors are different from the normal
text mode. DIM white is missing.

INITIAL SCREENS
===============

Initially, nccnav displays a list of all the source files.
Pressing 'O' shows a list of all the functions and BACKSPACE or 'q' goes
 back to the source files.
Pressing 'E' shows a list of all the functions not called by any other
 function (which are supposed to be interface entry functions).
Pressing 'G' shows a list of all the global variables.

Pressing any letter (except 'q') in the list of functions will
get the cursor to the closest function beginning with that letter.

Movement is possible with the arrow keys and page-up/down.

Pressing <enter> on a file or function or variable goes to MODE 2.

MODE 2
======

This mode is oriented around a resource which can be a:

	file, function, global variable, member of structure, structure

For any of the above, all the related resources are listed.
For example, in the case of a <function> there are:

	1. File(s) with <function> definition (may not exist)
	2. Functions calling <function> (Blue)
	3. Global variables used by <function> (Red)
	4. <function-herself>
	5. Functions called by <function>
		Dim grey: functions that do not call any other functions.
		Brown: functions that do call other functions.
		Red: Recursion detector alert (if enabled)
	6. Structure members used by <function> (Dark grey)

Selecting something from 1, 2, 3, 5, 6 and pressing enter, will recursively
enter MODE 2 for that resource.
Pressing enter on 4 or typing 'q' will return to the previous screen.
Pressing BACKSPACE will get you to the INITIAL SCREENS with a longjmp.
Pressing '<' will get you to the HISTORY MODE.
Pressing 'r' on a red 5 get you to the UNROLL MODE.
Pressing 'm' on a function will get you to the POP-UP MODE
Pressing 'C' will run system("bash")

FUNCTION CODE
=============

Pressing <space> on a function will show the function text as found in
 the file which is known to include the function definition.
 This means that, nccnav must be in the correct root directory
 or paths should be absolute. The ncc option -ncfabs is rather useful.

Pressing 'v' on a function will show the function text with "vi"
 (after extracting it from its file and saving it to a temporary
 file), colorized with C syntax.

Note that external library functions, obviously have no file.

Also note that if a function reports to be defined in more than one
 files, this will probably fail.  This happens because ncc does
 not distinguish different static functions with the same name.
 They are considered the same thing and their resources are
 mixed in nccnav.  Currently, if nccnav detects more than one
 files for a function it will issue a warning.

Pressing <space> or <enter> will get you to the previous screen if
 you are using the internal source viewer. Otherwise, exit the
 external application by it's custom way of doing so.

MORE CODE
=========

Pressing <space> on a file in MODE 2 will display the  entire file.
Pressing 'v' on a file in MODE 2 will *edit the original* file with vi
 (":q\n" to exit)

Pressing <space> or 'v' on a structure will extract and show the
 structure declaration text.

RECURSION DETECTOR
==================

The recursion detector is by default enabled.
It can be disabled by pressing 'R' while in MODE 2. (it's supposed to be
 expensive and may be confusing)

The recursion detector works in MODE 2 and if the current resource is a
 function. In this case it will paint RED all the functions called by the
 current function, which will eventually lead back to it by some way of
 recursion.

Pressing 'r' on one of the red ones will display one of the possible paths
 through which recursion can happen. Currently there is no way to view
 alternative paths.

In this mode, 'q' will get you back while enter will proceed ahead deeper
 into MODE 2 for the selected resource.

POP-UP MODE
===========

This is an alternative way to browse the call flow and is entered by
 pressing 'm' on a function in MODE 2.

Pop-up menus are generated, where the top element is a function and
 below it all the functions called by it. Movement is possible
 with the UP/DOWN arrows.

<enter> or RIGHT will expand a new pop-up for the current function.
'q' or LEFT will close the current pop-up and activate the previous one.
SPACE is available to view the source code.
BACKSPACE will close all the popups and return to MODE 2.

Pressing '2' will enter MODE 2 for the current selected element.
In this case, HISTORY and BACKSPACE are set at this breakpoint.

HISTORY MODE
============

At any time you can press '<' and '>' to browse through all the previous
 screens. <enter> on one of them will jump back to that screen. Any other
 key will exit the HISTORY MODE.

WHAT TO DO IF YOU'RE STUCK
==========================

Nothing. Stay calm and do not panic.
Remember: The user is the only person responsible for any damages.

FINALLY
=======

Except from hacking unknown projects, ncc together with valgrind are
an excellent debugging platform for discovering and fixing bugs in
zero time.

Happy hacking!
