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 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 on a file or function 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 there are: 1. File(s) with definition (may not exist) 2. Functions calling (Blue) 3. Global variables used by (Red) 4. 5. Functions called by 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 (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 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. 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 or 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 on a file in MODE 2 will display the entire file. Pressing 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. 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. 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!