Next: , Previous: Installation, Up: Top


3 Invoking Nana

The functions defined by Nana are implemented either as pure C code or as a set of commands which are generated for the debugger. To use the C based support for assertion checking you would use something like:

     #include <nana.h> /* this file includes the other nana .h files */
     
     int floor_sqrt(int i) { /* returns floor(sqrt(i) */
       int answer;
       I(i >= 0); /* assert(i >= 0) if i -ve then exit */
       ...; /* code to calculate sqrt(i) */
       L("floor_sqrt(%d) == %d\n",
             i, answer);  /* logs a printf style message */
     }

To compile and link the previous code you may need to use the ‘-Ipath’ or ‘-lnana’ flags with the compiler. For example:

     % gcc toy.c -lnana

If the nana headers have been installed in a strange location you may need to do something like:

     % gcc -I<strange location>/include toy.c -L<strange location>/lib -lnana

The next example uses the debugger versions of ‘L’ and ‘I’. If the code is run under the debugger these checks will occur, otherwise they take up a negligible amount of space and time.

     #include <nana.h> /* this includes the other nana .h files */
     
     int floor_sqrt(int i){
       int answer;
       DI(i >= 0); /* assert(i >= 0) if i -ve then exit */
       ...; /* code to calculate sqrt(i) */
       DL("floor_sqrt(%d) == %d\n", i, answer);  /* logs a printf style message */
     }

To generate the debugger commands from the C source we just run the ‘nana’ filter over the program and then execute the commands under gdb using the ‘source’ command. You also need to compile the program with the ‘-g’ option so the debugger works. So something like:

     % gcc -g sqrt.c
     % nana sqrt.c >sqrt.gdb
     % gdb a.out
     (gdb) source sqrt.gdb
     breakpoint insert: ...
     (gdb) run
     ...
     (gdb) quit

Note that any C preprocessor flags which you use must be passed off to the ‘nana’ command. The best way to do this of course is in a Makefile. Something like the following works for GNU Make:

     %.nana: %.c
             nana $(CFLAGS) $< >$@

The ‘nana’ filter can also be run over multiple source files in a single run if thats more convenient.

For convenience a number of other simple scripts are provided, in particular to:

nana-run
Run a program under the debugger without prompting, etc. For example:
          % nana-run a.out -x main.gdb
          output from program

nana-clg
Compiles the program, generates the debugger commands and the runs the program using ‘nana-run’. For example:
          % nana-clg -O3 main.c
          output from program

You can change the compiler invoked by ‘nana-clg’ by redefining the ‘NANACC’ environment variable. For example:

          % NANACC=g++ nana-clg -O3 main.cc

The installation also ‘nana-c++lg’ which compiles your code using a GNU C++ compiler.

nana-trace
Generates a line by line trace of the execution of a program using GDB. For example:
          % nana-trace a.out
          54           printf("main()\n");
          55           x = distance(5,-5);
          distance (i=5, j=-5) at test.c:47
          47           i = -i;
          48           j = -j;
          ...

The arguments to ‘nana-trace’ are passed directly to GDB. If you wish display variables or call procedures on each line then could use something like:

          % nana-trace -x mycommands.gdb a.out

Where the ‘mycommands.gdb’ contains the GDB commands such as ‘display x’ which causes ‘x’ to be printed every time the debugger gets control of the program.