1This is Info file nana.info, produced by Makeinfo version 1.68 from the 2input file nana.texi. 3 4START-INFO-DIR-ENTRY 5* Nana: (nana). The GNU Nana library (assertions, logging, forall,etc) 6END-INFO-DIR-ENTRY 7 8 This file documents the features and implementation of the GNU Nana 9library. 10 11 Copyright (C) 1996, 1997, 1998, 1999 P.J.Maker, Quoll Systems Pty 12Ltd. 13 14 Permission is granted to make and distribute verbatim copies of this 15manual provided the copyright notice and this permission notice are 16preserved on all copies. 17 18 19File: nana.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 20 21 This manual documents how to install and use the Nana library which 22provides improved support for assertion checking and logging in C and 23C++. 24 25* Menu: 26 27* Introduction:: Overview 28* Installation:: Installing nana 29* Invoking:: Compiling, linking and generating gdb commands 30* Interface:: Interface to nana library functions 31* Shortform:: Nana shortform generation 32* Performance:: 33* Tracing:: 34* Usage:: Some examples 35* FAQ:: Frequently Asked Questions 36* Future:: Future work/projects 37* Index:: 38 39 -- The Detailed Node Listing -- 40 41Introduction 42 43* Related work:: 44* Assert:: 45* Scope:: 46 47Installing the Nana library 48 49* Required Software:: 50* Optional Software :: 51* Configure:: 52* Variables:: 53* Supported Platforms:: 54* Supported Debuggers:: 55* Known Problems:: 56* Bug Reports:: 57* New Versions:: 58 59Interface 60 61* nana.h:: 62* WITHOUT_NANA:: 63* I.h:: 64* DI.h:: 65* L.h:: 66* L_buffer.h:: 67* L_times.h:: 68* DL.h:: 69* GDB.h:: 70* Q.h:: 71* Qstl.h:: 72* now.h:: 73* cycles.h:: 74* eiffel.h:: 75* assert.h:: 76* calls.h:: 77 78cycles.h: access to CPU cycle counting registers. 79 80* RDTSC:: 81 82eiffel.h: eiffel type assertions 83 84* EIFFEL_CHECK:: 85* DOEND:: 86* REQUIRE...:: 87 88Tracing tools 89 90* Statement:: 91* Library:: 92 93Using Nana 94 95* Simplest:: 96* Syslog:: 97* GNU:: 98* Embedded Systems:: 99* Realtime:: 100* A database:: 101* Visualisation:: 102 103 104File: nana.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top 105 106Introduction 107************ 108 109 Nana is a library that provides support for assertion checking and 110logging in a space and time efficient manner. The aim is to put common 111good practice(1) into a library that can be reused rather than writing 112this stuff every time you begin a new project. 113 114 In addition assertion checking and logging code can be implemented 115using a debugger rather than as inline code with a large saving in code 116space. 117 118 Nana aims to solve the following problems: 119 120 1. Avoid the two executables problem (one with asserts in and another 121 without any). 122 123 The code space and time costs of having assertion checking and 124 detailed logging code in a program can be high. Normally people 125 construct two versions of the program, one with checking code for 126 testing and one without checking code for production use. 127 128 With nana one version of the executable can be built for both 129 testing and release since debugger based checking has negligible 130 space and time impact. 131 132 2. Configurable: the nana library is designed to be reconfigured by 133 the user according to their needs. For example we can: 134 * Modify the behavior on assertion failure, e.g. to attempt a 135 system restart rather than just shutting down. 136 137 * Selectively enable and disable assertion checking and logging 138 both at compile and run time. 139 140 * Send the logging information off to various locations, e.g. 141 - Users terminal 142 143 - A file for later checking. 144 145 - Another process, e.g. a plotting program or a program 146 that verifies that the system is behaving itself. 147 148 - A circular buffer in memory. 149 150 This is an old embedded systems trick and is very useful 151 for production systems. The time cost of logging into 152 memory is not large and when your production system in 153 the field has problems you can then see what was 154 happening in the minutes before its unfortunate demise 155 rather than asking some user what was happening before 156 it died. 157 158 3. Time and space efficient. 159 160 For example the GNU `assert.h' implementation uses 53 bytes for 161 `assert(i>=0)' on a i386. The nana version using the i386 `stp' 162 instruction on assert fail uses 10 bytes. If you're willing to 163 accept the time penalty this can be reduced to 0 or 1 byte by 164 using debugger based assertions. 165 166 4. Support for formal methods. 167 168 * Before and after state (e.g. x,x' in the Z notation). 169 170 Specifications are often written in terms of the state of 171 variables before and after an operation. For example the 172 `isempty' operation on a stack should leave the stack 173 unchanged. To verify this in nana we could use: 174 175 bool isempty(){ /* true iff stack is empty */ 176 DS($s = s); /* copy s into $s in the debugger */ 177 ...; /* code to do the operation */ 178 DI($s == s); /* verify that s hasn't been changed */ 179 } 180 181 These `$..' variables are called convenience variables and 182 are implemented by gdb. They have a global scope and are 183 dynamically typed and initialised automatically to 0. 184 185 In addition a C only version of before and after state is 186 provided. For example: 187 188 bool isempty() { /* true iff stack is empty */ 189 ID(int olds); /* declare variable to hold old value */ 190 IS(olds = s); /* copy s into $s in the debugger */ 191 ...; /* code to do the operation */ 192 I(olds == s); /* verify that s hasn't been changed */ 193 } 194 195 * Support for Predicate Calculus. 196 197 Nana provides some support for universal (forall) and 198 existential (exists one or more) quantification. For example 199 to specify that the string v contains only lower case letters 200 we could use: 201 202 I(A(char *p = v, *p != '\0', p++, islower(*p))); 203 204 These macros can be nested and used as normal boolean values 205 in control constructs as well as assertions. Unfortunately 206 they depend on the GNU CC statement value extensions and so 207 are not portable. The following macros are defined in `Q.h': 208 209 `A' 210 For all values the expression must be true. 211 212 `E' 213 There exists one or more values for which the expression 214 is true. 215 216 `E1' 217 There exists a single value for which the expression is 218 true. 219 220 `C' 221 Returns the number of times the expression is true. 222 223 `S' 224 Returns the sum of the expressions. 225 226 `P' 227 Returns the product of the expressions. 228 229 * A C/C++ based shortform generator similar to Eiffel which can 230 produce a HTML summary of your code. 231 232 The shortform of a program consists of the function headers 233 together with their preconditions(2) and postconditions(3) 234 235 * Performance measurement. 236 237 A small package which measures the time and space overhead of 238 code fragments is provided. This is used to analyse the 239 space/time requirements of the nana library and could be used 240 for other types of measurement. 241 242 * Verifying timing. 243 244 As well as using nana to verify timings with assertions using 245 a hardware supported timer you can also a simulator (e.g. the 246 PSIM power pc simulator by Cagney) with gdb. These simulators 247 can model time and provide a register called `$cycles' which 248 represents the current cycle count of the program. This can be 249 used to check that timing constraints are being meet. 250 251 void process_events() { 252 for(;;){ 253 DS($start = $cycles); 254 switch(get_event()){ 255 case TOO_HOT: 256 ...; 257 DI($cycles - $start <= 120); 258 break; 259 case TOO_COLD: 260 ...; 261 DI($cycles - $start <= 240); 262 break; 263 } 264 } 265 } 266 267 The intended audience for Nana includes: 268 269 * Software Engineers. 270 271 * Formal methods community. 272 273 * Real time programmers. 274 275 * System testers. 276 277 * People teaching programming. 278 279* Menu: 280 281* Related work:: 282* Assert:: 283* Scope:: 284 285 ---------- Footnotes ---------- 286 287 (1) Which is unfortunately quite uncommon in the authors experience. 288 289 (2) Precondition: a boolean expression which must be true if the 290operation is to succeed. For example the `sort(int *v, int n)' might 291have have precondition that `v != NULL && n >= 0'. 292 293 (3) Postcondition: a boolean expression that must be true if the 294operation is correct (and the precondition was true on entry). 295 296 297File: nana.info, Node: Related work, Next: Assert, Prev: Introduction, Up: Introduction 298 299Related work 300============ 301 302 The Nana project was inspired by some other projects, in particular: 303 304 * Anna - Anna stands for "Annotated Ada" where the programmer inserts 305 various assertions into the code which can be automatically 306 validated. To quote from the WWW Virtual Library entry on Anna: 307 308 Anna is a language for formally specifying the intended 309 behaviour of Ada programs. It extends Ada with various 310 different kinds of specification constructs from ones as 311 simple as assertions, to as complex as algebraic 312 specifications. A tool set has been implemented at Stanford 313 for Anna, including: 314 315 1. standard DIANA extension packages, parsers, 316 pretty-printers; 317 318 2. a semantic checker; 319 320 3. a specification analyser; 321 322 4. an annotation transformer; and 323 324 5. a special debugger that allows program debugging based 325 on formal specifications 326 327 All tools have been developed in Ada and are therefore 328 extremely portable. Anna has thus been ported to many 329 platforms. For more information send e-mail to 330 "anna-request@anna.stanford.edu". Before down loading the 331 huge Anna release, you may wish to copy and read some Anna 332 LaTeX reports. 333 334 335 Anna is available from: `ftp://anna.stanford.edu/pub/anna' 336 337 * Eiffel - the Eiffel programming language provides support in the 338 language flexible assertion checking. To quote from the Eiffel 339 page in WWW Virtual library: 340 341 Eiffel is a pure object-oriented language featuring multiple 342 inheritance, polymorphism, static typing and dynamic binding, 343 genericity (constrained and unconstrained), a disciplined 344 exception mechanism, systematic use of assertions to promote 345 programming by contract, and deferred classes for high-level 346 design and analysis. 347 348 * APP - Annotation PreProcessor. The APP was written by David S. 349 Rosenblum and provides assertion checking functions for C and C++. 350 It is implemented using a preprocessor wrapper around the C 351 preprocessor and supports quantifiers and before/after state. 352 353 See "A Practical Approach to Programming with Assertions" in Vol 354 21, No. 1, January 1995 of IEEE Transactions on Software 355 Engineering for an interesting paper describing APP. Unfortunately 356 the APP tool doesn't seem to be freely available (I'm willing to 357 be corrected on this). Note that any similarity between my 358 examples and David's are due to morphic resonance. 359 360 * ADL - the Assertion Definition Language. 361 362 To quote from `http://www.sunlabs.com/research/adl/': 363 364 ADL (Assertion Definition Language) is a specification 365 language for programming interfaces. It can be used to 366 describe the programmer's interface to any C-callable 367 function, library or system call. 368 369 The Practical Specification Language. 370 371 ADL is the world's most practical specification language 372 because: 373 374 * Even partial specifications are useful 375 376 * Test programs can be automatically generated from ADL 377 specifications 378 379 * Specifications are external to the implementation of the 380 interface, so that they are vendor-independent. 381 382 An Automated Test Generator. 383 384 An ADL specification is not just a paper document. It can be 385 compiled by ADLT (the ADL translator). ADLT generates: 386 387 * Header files, that can be used in an implementation 388 389 * Test programs, that ensure that any implementation meets 390 the specification 391 392 * Natural-language documentation, derived directly from 393 the specification 394 395 ADLT can be used: 396 397 As a test generator, to create tests for existing software or 398 for existing standards As a development tool, to ensure that 399 documentation, software, and tests are aligned, and to enable 400 concurrent work on all three aspects of software production. 401 402 Nana is essentially a poor mans implementation of some of these ideas 403which works for C and C++. Ideally in the best of all possible worlds 404you might want to look at Eiffel or in the military world Ada and Anna. 405If you use TCL/TK you might also be interested in Jon Cook's `AsserTCL' 406package. 407 408 409File: nana.info, Node: Assert, Next: Scope, Prev: Related work, Up: Introduction 410 411Assert.h considered harmful 412=========================== 413 414 Most C programmers become familiar with assertions from the the 415`assert.h' header. As such its a very good thing and has a nice simple 416implementation. However it is also inefficient and leads some people to 417the conclusion that assertion checking is an expensive luxury. 418 419 The implementation of `assert.h' as distributed with `gcc' looks 420like the following (after a bit of editing): 421 422 # ifndef NDEBUG 423 # define _assert(ex) {if (!(ex)) \ 424 {(void)fprintf(stderr, \ 425 "Assertion failed: file \"%s\", line %d\n", \ 426 __FILE__, __LINE__);exit(1);}} 427 # define assert(ex) _assert(ex) 428 # else 429 # define _assert(ex) 430 # define assert(ex) 431 # endif 432 433 There are are two main problems with this: 434 435 1. Code space overhead: each call to `assert' generates 2 function 436 calls with 4 and 1 arguments plus strings for error messages. If 437 `assert.h' had library code support we could make the 438 implementation much more space efficient, e.g. by calling a single 439 function on error detection. 440 441 2. The default behaviour simply prints a message and dies, ideally 442 you like to be able to use a debugger to determine why the 443 assertion failed. Even if you run this under the debugger you 444 can't observe the failures of variables are an assert failure 445 because the process exits rather than aborting back to the 446 debugger. 447 448 Of course everyone merely rewrites their own `assert' macro so these 449are not significant objections. The only problem is if the author uses 450the libraries without modification. 451 452 453File: nana.info, Node: Scope, Prev: Assert, Up: Introduction 454 455Scope of this document 456====================== 457 458 This document aims to both describe the library and provide a 459tutorial in its use. Further work is required, particularly on the 460tutorial sections. If anyone has any suggestions please send them to 461me. 462 463 464File: nana.info, Node: Installation, Next: Invoking, Prev: Introduction, Up: Top 465 466Installing the Nana library 467*************************** 468 469 Nana uses the normal GNU install method in the same way as `gcc' and 470`gdb'. To install nana in the default location 471`/usr/local/{bin,lib,include}' you would use: 472 473 % gzcat nana-1.10.tar.gz | tar xvf - 474 % cd nana-1.10 475 % ./configure 476 % make 477 % make install 478 % make check 479 % make check-mail 480 % make subscribe 481 482 If you wish to produce space and time efficient code then replace 483the `./configure' with: 484 485 % I_DEFAULT=fast ./configure 486 487 If you are using a Pentium compatiable CPU which supports the 488`RDTSC' instruction you may wish to enable cycle level timing in 489`cycles.h' by using: 490 491 % ./configure --enable-rdtsc 492 493 The CHECK-MAIL and SUBSCRIBE targets both send e-mail. If you need 494to change the mailer used try something like: 495 496 % make MAILER=elm subscribe 497 498 *Note:* we need to install nana before running the `make check' 499target. The `check-mail' target sends the test report via e-mail to the 500`gnuware@cs.ntu.edu.au'. 501 502 Of course things are never that simple. If you want to install Nana 503in a different location or change the behaviour on error detection see 504*Note Configure::. 505 506 Each of the sub-directories nana can be compiled and installed 507separately, e.g. if you don't need the documentation you can just 508compile and install from the `src' sub-directory after doing the 509configure statement. 510 511 Note that some of the subdirectories contain code that you may wish 512to install, improve or inspect. In particular: 513 514 * `emacs' - a protype emacs mode for browsing log files. 515 516 * `examples' - some small examples. 517 518 * `gdb' - some tools for use with gdb, in particular a statement 519 level trace utility and some gdb patches. 520 521 * `perf' - a tool for measuring space/time of code fragments. 522 523 * `shortform' - a shortform generator which produces a HTML summary 524 of your codes interface. 525 526 * `tcl' - a prototype TCL driver. We actually have a few more TCL 527 tools in the works so if you're interested contact the author. 528 529* Menu: 530 531* Required Software:: 532* Optional Software :: 533* Configure:: 534* Variables:: 535* Supported Platforms:: 536* Supported Debuggers:: 537* Known Problems:: 538* Bug Reports:: 539* New Versions:: 540 541 542File: nana.info, Node: Required Software, Next: Optional Software, Prev: Installation, Up: Installation 543 544Required Software 545================= 546 547 The following software is possibly required to run nana. 548 549`gcc-2.7.2' 550 Nana makes use of two GNU extensions in its library so you really 551 should be using `gcc'. Some of the code can be used with any C 552 compiler, though it may not be worth the bother. The dependencies 553 on gcc are in `Q.h' which uses the statement value extension and 554 in `L.h' which uses the variable number of arguments extension to 555 `cpp'. 556 557`gdb-4.16+' 558 A recent version of `gdb' is worthwhile, some early 4.?? versions 559 had problems setting a large number of breakpoints. Note that 560 `gdb-4.17' is available and has a few improvement which are useful 561 for some parts of this package including the tools in `gdb'. 562 563`gmake' 564 The `configure' script and `Makefiles' are generated using the 565 `automake' and `autoconf' programs. They should be reasonably 566 portable but if you have problems try using GNU make. For example 567 on some old DEC boxes we have had strange behaviour using the 568 system make. 569 570 For a listing of porting results including software versions see: 571 572 `http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/' 573 574 575File: nana.info, Node: Optional Software, Next: Configure, Prev: Required Software, Up: Installation 576 577Optional Software 578================= 579 580 In addition to the required software you might also be interested in: 581 582 * `http://www.cs.tu-bs.de/softech/ddd/' - a smart frontend for gdb 583 which can display dynamic data structures such as linked lists, 584 etc. 585 586 * `ftp://ftp.ci.com.au/pub/psim/' - a cycle level simulator for the 587 PowerPC. A fine piece of work. 588 589 590File: nana.info, Node: Configure, Next: Variables, Prev: Optional Software, Up: Installation 591 592Configure 593========= 594 595 Nana uses a standard GNU `autoconf' generated `configure' script. 596The `configure' script checks the setup on your machine and then 597generates the appropriate Makefiles. Some of the things checked by 598configure include: 599 600 1. Which compiler, compiler flags and libraries to use, e.g. you 601 might need to include a `-lposix' flag to the linker to build 602 programs on your machine. 603 604 2. Which header (.h) files are available on this machine, e.g. is 605 `unistd.h' available on this machine. 606 607 3. Where to install programs, header file, man pages, etc. 608 609 In addition `configure' uses the host architecture and operating 610system to generate the `nana-config.h' file. This file contains some 611macro definitions which define how nana works on particular operating 612systems and hardware architectures. 613 614 For example on `i386' machines we would use the `asm("hlt")' 615instruction whenever an assertion fails, on a `sparc' we would use 616`asm("unimp")'. Otherwise we would default to a plain C call to 617`abort()' If `configure' does not recognise your machine it uses plain 618C code. 619 620 You may wish to change these defaults on installation, one method is 621to edit a local copy of the `nana-config.h' file. Alternately you can 622define the code yourself in the call to `configure'. For example to 623redefine the action we take when an error is detected by the `I' macro 624we can use: 625 626 I_DEFAULT_HANDLER="restart_system()" ./configure 627 628 As well as simple calls to routines various other bits of information 629are passed off to the `I_DEFAULT_HANDLER' such as the expression that 630failure and a failure code. For example: 631 632 % I_DEFAULT_HANDLER="restart(line,file,param)" ./configure 633 634 The default for `I_DEFAULT_HANDLER' calls a function which prints a 635message and then dumps core. Different behaviour on failure can be 636organised by setting the `I_DEFAULT' to `fast', i.e. plain core dump or 637`verbose' which prints an error messsage and then does the core dump. 638 639 % I_DEFAULT=fast ./configure 640 641 For nana the following examples may be useful: 642 643 1. `./configure' 644 645 Accept the default values for everything. In particular the files 646 will be installed in: 647 648 `/usr/local/{bin,include,lib,man,info}' 649 650 2. `./configure --prefix=~project/tools' 651 652 Install the files into: 653 654 `~project/tools/{bin,include,lib,man,info}' 655 656 3. `./configure --bindir=~project/bin --libdir=~/project/lib \ 657 --includedir=~/project/headers --infodir=/usr/local/info \ 658 --mandir=~/project/doc' 659 660 The install directory for program (`bin'), etc can all be set with 661 command line arguments to `configure'. 662 663 4. `CC=xacc LIBS=-lposix ./configure sun3' 664 665 If the defaults chosen by `configure' are not correct you can 666 override them by setting variables such as `CC' before calling 667 `configure'. The `sun3' argument is used to identify the machine 668 we are running on and may be necessary on some machines. 669 670 5. `./configure --help' 671 672 And of course when in doubt ask for help. 673 674 For even more details see the file `INSTALL.con' which contains the 675generic instructions for use with `autoconf' generated `configure' 676scripts. 677 678 679File: nana.info, Node: Variables, Next: Supported Platforms, Prev: Configure, Up: Installation 680 681Variables for ./configure 682========================= 683 684 The configure program uses the following shell variables to change 685various defaults. Another method is simply to edit the `nana-config.h' 686file. Most of these values should be auto detected, so you can ignore 687this section until your need to save a few bytes of store by using 688`asm("hlt")' instead of a call to `abort()'. 689 690`DI_MAKE_VALID_BREAKPOINT' 691 This text is inserted when the `DI.h' library needs to set a 692 breakpoint in the generated code. It should ideally update all 693 variables which being kept in registers etc so that gdb gets the 694 correct values for each variable. 695 696 Possible values include: 697 698 1. `asm("nop")' - a single `nop' instruction to set the 699 breakpoint at. 700 701 This is the default. 702 703 2. `_vi = 0' - where `_vi' is a global volatile int. 704 705 3. `_vi = (exprn)' - where EXPRN is the expression we are 706 checking for this assertion. 707 708 4. `/* nothing */' - nothing at all, this means the breakpoint 709 will be set at the start of the next statement which works 710 most of the time. However for some examples this will do the 711 wrong thing. 712 713`DL_MAKE_VALID_BREAKPOINT' 714 Used for the same purpose as `DI_MAKE_VALID_BREAKPOINT' for 715 `DL.h'. It also defaults to `asm("nop")'. 716 717`I_DEFAULT_HANDLER' 718 The code called when `I.h' detects an error. 719 `asm("hlt")' 720 Some machines use a `hlt' instruction. 721 722 `asm("unimp")' 723 And other machines use a `unimp' instruction. 724 725 `abort()' 726 Or we could use a call to `abort' which is at least standard 727 C. On some machines this is significantly larger than a 728 single `hlt' instruction. 729 730 `restart()' 731 Or a call to a function which attempts to restart the system. 732 733`ALWAYS_INCLUDE_MALLOC' 734 This is a dodgey for some versions of Linux which don't seem to 735 include `malloc' when you include `stdio.h' and use `print'. This 736 causes problems for `gdb' since it uses `malloc' in the executable 737 to implement parts of its functionality. 738 739 This kludge should be removed! 740 741`GDB' 742 This is the pathname of the version of GDB you wish to use. For 743 example on my FreeBSD box we have gdb-4.16 installed in `/usr/bin' 744 and gdb-4.17 in `/usr/local/bin/' to optimise confusion. If you 745 wish nana to use 4.17 try something like: 746 747 GDB=/usr/local/bin/gdb ./configure 748 749 750File: nana.info, Node: Supported Platforms, Next: Supported Debuggers, Prev: Variables, Up: Installation 751 752Supported Platforms 753=================== 754 755 Nana has been tested on the following platforms: 756 757 1. i386-unknown-linux, gcc-2.7.0, gdb-4.16 758 759 2. sparc-sun-sunos4.1.4, gcc-2.7.2.f.1, gdb-4.16 760 761 3. sparc-sun-solaris2.3, gcc-2.7.2, gdb-4.16 762 763 4. alpha-dec-osf3.2, gcc-2.7.2, gdb-4.16 764 765 5. mips-sgi-irix5.3, gcc-2.7.0, gdb-4.16 766 767 6. powerpc-ibm-aix3.2.5, gcc-2.6.3, gdb-4.16 768 769 The `alpha-dec-osf3.2', `mips-sgi-irix5.3' and 770`powerpc-ibm-aix3.2.5' implementations have problems when you compile 771with `-O2' or `-O3' optimisation. This causes some errors in the the 772debugger based assertion and logging code since variables can be 773removed or changed by optimisation. At `-O' everything passes. 774Regardless of optimisation the C based checking code passes all tests 775on these platforms. 776 777 If you use nana on a new platform please send the report file to me 778via the `make check-mail' command. A machine generated list of this 779information is available at: 780 781 `http://www.cs.ntu.edu.au/homepages/gnuware/nana' 782 783 (Warning this page is out of date and may be fixed shortly) 784 785 786File: nana.info, Node: Supported Debuggers, Next: Known Problems, Prev: Supported Platforms, Up: Installation 787 788Supported Debuggers 789=================== 790 791 Currently Nana works with the GNU GDB debugger which is available on 792a wide range of platforms including embedded systems and even provides 793support for remote debugging. Porting to any reasonable debugger with 794conditional breakpoints and commands is not very difficult. 795 796 As an example of an unreasonable debugger, Nana has been ported to 797work with the Microsoft CodeView debugger. The port is small (60 lines 798of code) but suffers from a problem with variable scoping in CodeView. 799If a breakpoint is set at a point in the code the expressions are not 800evaluated from that particular scope. For example setting a breakpoint 801in the function `f' cannot access a variable local to `f' directly. 802CodeView has a unique (expletive deleted) scope operator which you must 803use to set the scope `{...}'. This makes the interface somewhat less 804than beautiful. 805 806 Another good thing about CodeView is to try a debug command which 807prints a message which contains a single open `{'. This of course 808causes it to hang and was the main problem during the porting to 809CodeView which took a whole day.(1) 810 811 If anyone is interested I may release the CodeView implementation, 812please contact me if you are interested. Of course a better bet is 813probably to move to the `gdbserver' system. I think `gdb' has been 814released as a native even for some Microsoft operating systems. 815 816 Other debuggers like DBX don't seem to be worth the trouble since gdb 817works on those machines. A redesign of the nana internals may also be 818useful if we decide portability between debuggers is actually useful. 819 820 ---------- Footnotes ---------- 821 822 (1) And about 60 reset cycles where the machine went off into 823hyperspace. 824 825 826File: nana.info, Node: Known Problems, Next: Bug Reports, Prev: Supported Debuggers, Up: Installation 827 828Known Problems 829============== 830 831 Nana has the following known features (or perhaps problems): 832 833 1. Nana macros which use the debugger such as `DI' or `DL' should be 834 on lines by themselves. If you mix code and nana macros on the 835 same line you will get errors, e.g: 836 837 main(){ 838 int x; 839 x = 5; x--; DI(x == 4); 840 } 841 842 This doesn't work since breakpoints are set at line boundaries 843 rather than statement ones. Of course anyone who writes code like 844 this deserves whatever happens to them. 845 846 2. Optimisation can remove variables so that debugger based 847 assertions (`DI.h') do not work correctly. As usual the 848 interaction between the debugger and the compiler is rather 849 complicated. This may not be a problem if the appropriate 850 compile-time flags are selected, e.g. `-O0 and -O1' work on most 851 platforms. 852 853 3. The `Q.h' macros depend on the statement value extension to GNU CC 854 so if you wish to use them you must use GCC. This can be fixed for 855 C++ in a possibly useful manner, I can't see any solution for C. 856 857 4. The logging macros depend on the Var Args extension provided by the 858 GNU C Preprocessor.(1) We could (probably will) implement a fix 859 for this based on the tricks in the C FAQ. Unfortunately these 860 tricks are not pretty. For now interested users could simply 861 replace their CPP with the GNU CPP if they wished to stay with 862 non-standard compilers. 863 864 5. The `Q.h' macros do not work in the debugger since `gdb' does 865 support the statement expression extension. 866 867 6. Multiline expressions do not work as expected in the debugger since 868 you need to use a blackslash as an escape at the end of the line. 869 For example: 870 871 DI(x + 872 10 > 30); 873 A few backslashes may solve this particular problem. 874 875 7. Problems with the `configure' script. 876 877 The `configure' script automatically detects the target operating 878 system and architecture and then generates `nana-config.h'. If the 879 options selected in `nana-config.h' are incorrect they can be 880 edited by hand and installed in the usual include directory. The 881 easiest method is simply to delete all macros in `nana-config.h' 882 since the system defaults to more portable (and less efficient) 883 implementations. If you wish to do this from the configure script 884 you can try giving a unsupported machine type, e.g. 885 886 % ./configure pdp11-dec-ultrix 887 888 8. Some users have reported problems with the `configure' script 889 detecting `vsnprintf'. If `configure' doesn't find it and it does 890 exist then simply define it in `nana-config.h' as per the previous 891 question. 892 893 If `vsnprintf' really doesn't exist then get a new C library, 894 possibly the GNU libc. 895 896 9. The use of `vsprintf' opens a security hole since no bounds 897 checking is done by it. Nana attempts to use `vsnprintf' which is 898 safe when it exists but it will resort to `vsprintf' if it can't 899 find `vsnprintf'. All careful people should make sure that they 900 have a library with `vsnprintf'. 901 902 10. `Qstl.h' doesn't work since the STL library has not been 903 installed along with C++. This can of course be fixed by installing 904 STL. See: 905 906 `http://www.stl.org' 907 908 11. `STL' header file errors due to nana. 909 910 The C++ `STL' header files for version 3.0 at least must be 911 included before the `Q.h' file. 912 913 The problem is caused by the STL files using `S' as a template 914 argument. Of course `Q.h' uses `S' for summing a series. As usual 915 namespace pollution strikes again. 916 917 (Thanks to Han Holl for this particular problem). 918 919 12. If you try to use the debugger based macros such as `DI.h' or 920 `DL.h' on code that has not been compiled with `-g' then misery 921 follows. 922 923 (Thanks to Eugen Dedu for this one) 924 925 ---------- Footnotes ---------- 926 927 (1) This allows a variable number of arguments to C preprocessor 928macros. 929 930 931File: nana.info, Node: Bug Reports, Next: New Versions, Prev: Known Problems, Up: Installation 932 933Bug Reports 934=========== 935 936 If you think you have found a bug in the Nana library, please 937investigate it and report it. 938 939 * Please make sure that the bug is really in the Nana library. 940 941 * You have to send us a test case that makes it possible for us to 942 reproduce the bug. 943 944 * You also have to explain what is wrong; if you get a crash, or if 945 the results printed are not good and in that case, in what way. 946 Make sure that the bug report includes all information you would 947 need to fix this kind of bug for someone else. 948 949 If your bug report is good, we will do our best to help you to get a 950corrected version of the library; if the bug report is poor, we won't do 951anything about it (apart from asking you to send better bug reports). 952 953 Send your bug report to: 954 955 `nana-bug@cs.ntu.edu.au' 956 957 Copies of bug reports will be kept at: 958 959 `http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/' 960 961 962File: nana.info, Node: New Versions, Prev: Bug Reports, Up: Installation 963 964New Versions 965============ 966 967 New versions of nana will be made available at: 968 969 `ftp://ftp.cs.ntu.edu.au/pub/nana/' 970 971 If you wish to be informed about new releases of nana then subscribe 972to the nana mailing list. Send a message containing `subscribe' <your 973e-mail address> to: 974 975 `mailto:nana-request@it.ntu.edu.au'. 976 977 A hypermail archive of this list is kept at: 978 979 `http://www.cs.ntu.edu.au/hypermail/nana-archive' 980 981 If you wish to send a message to the list send it to 982`mailto:nana@it.ntu.edu.au'. 983 984 985File: nana.info, Node: Invoking, Next: Interface, Prev: Installation, Up: Top 986 987Invoking Nana 988************* 989 990 The functions defined by Nana are implemented either as pure C code 991or as a set of commands which are generated for the debugger. To use 992the C based support for assertion checking you would use something like: 993 994 #include <nana.h> /* this file includes the other nana .h files */ 995 996 int floor_sqrt(int i) { /* returns floor(sqrt(i) */ 997 int answer; 998 I(i >= 0); /* assert(i >= 0) if i -ve then exit */ 999 ...; /* code to calculate sqrt(i) */ 1000 L("floor_sqrt(%d) == %d\n", 1001 i, answer); /* logs a printf style message */ 1002 } 1003 1004 To compile and link the previous code you may need to use the 1005`-Ipath' or `-lnana' flags with the compiler. For example: 1006 1007 % gcc toy.c -lnana 1008 1009 If the nana headers have been installed in a strange location you may 1010need to do something like: 1011 1012 % gcc -I<strange location>/include toy.c -L<strange location>/lib -lnana 1013 1014 The next example uses the debugger versions of `L' and `I'. If the 1015code is run under the debugger these checks will occur, otherwise they 1016take up a negligible amount of space and time. 1017 1018 #include <nana.h> /* this includes the other nana .h files */ 1019 1020 int floor_sqrt(int i){ 1021 int answer; 1022 DI(i >= 0); /* assert(i >= 0) if i -ve then exit */ 1023 ...; /* code to calculate sqrt(i) */ 1024 DL("floor_sqrt(%d) == %d\n", i, answer); /* logs a printf style message */ 1025 } 1026 1027 To generate the debugger commands from the C source we just run the 1028`nana' filter over the program and then execute the commands under gdb 1029using the `source' command. You also need to compile the program with 1030the `-g' option so the debugger works. So something like: 1031 1032 % gcc -g sqrt.c 1033 % nana sqrt.c >sqrt.gdb 1034 % gdb a.out 1035 (gdb) source sqrt.gdb 1036 breakpoint insert: ... 1037 (gdb) run 1038 ... 1039 (gdb) quit 1040 1041 Note that any C preprocessor flags which you use must be passed off 1042to the `nana' command. The best way to do this of course is in a 1043Makefile. Something like the following works for GNU Make: 1044 1045 %.nana: %.c 1046 nana $(CFLAGS) $< >$@ 1047 1048 The `nana' filter can also be run over multiple source files in a 1049single run if thats more convenient. 1050 1051 For convenience a number of other simple scripts are provided, in 1052particular to: 1053 1054`nana-run' 1055 Run a program under the debugger without prompting, etc. For 1056 example: 1057 1058 % nana-run a.out -x main.gdb 1059 output from program 1060 1061`nana-clg' 1062 Compiles the program, generates the debugger commands and the runs 1063 the program using `nana-run'. For example: 1064 1065 % nana-clg -O3 main.c 1066 output from program 1067 1068 You can change the compiler invoked by `nana-clg' by redefining 1069 the `NANACC' environment variable. For example: 1070 1071 % NANACC=g++ nana-clg -O3 main.cc 1072 1073 The installation also `nana-c++lg' which compiles your code using 1074 a GNU C++ compiler. 1075 1076`nana-trace' 1077 Generates a line by line trace of the execution of a program using 1078 GDB. For example: 1079 1080 % nana-trace a.out 1081 54 printf("main()\n"); 1082 55 x = distance(5,-5); 1083 distance (i=5, j=-5) at test.c:47 1084 47 i = -i; 1085 48 j = -j; 1086 ... 1087 1088 The arguments to `nana-trace' are passed directly to GDB. If you 1089 wish display variables or call procedures on each line then could 1090 use something like: 1091 1092 % nana-trace -x mycommands.gdb a.out 1093 1094 Where the `mycommands.gdb' contains the GDB commands such as 1095 `display x' which causes `x' to be printed every time the debugger 1096 gets control of the program. 1097 1098 1099File: nana.info, Node: Interface, Next: Shortform, Prev: Invoking, Up: Top 1100 1101Interface 1102********* 1103 1104 This section describes the details of the interface to nana library. 1105 1106 All of the files can be included multiple times without ill-effect 1107since they use the C preprocessor to make sure the header declarations 1108are only seen the first by the compiler. Each of the files can also be 1109included individually. 1110 1111* Menu: 1112 1113* nana.h:: 1114* WITHOUT_NANA:: 1115* I.h:: 1116* DI.h:: 1117* L.h:: 1118* L_buffer.h:: 1119* L_times.h:: 1120* DL.h:: 1121* GDB.h:: 1122* Q.h:: 1123* Qstl.h:: 1124* now.h:: 1125* cycles.h:: 1126* eiffel.h:: 1127* assert.h:: 1128* calls.h:: 1129 1130 If any of the following routines have an internal problem (e.g. 1131malloc fails due to lack of memory) they will call the `nana_error' 1132function defined in `nana_error.c'. By default this function prints a 1133message and dumps core using `abort'. If you wish to override this 1134behaviour you should define your own handler before linking in the nana 1135library. 1136 1137 1138File: nana.info, Node: nana.h, Next: WITHOUT_NANA, Prev: Interface, Up: Interface 1139 1140nana.h: the main header file 1141============================ 1142 1143 The `nana.h' file includes most of the other files in the library. 1144In particular it `#include's' the following files: 1145 1146`I.h' 1147 1148`DI.h' 1149 1150`L.h' 1151 1152`DL.h' 1153 1154`Q.h' 1155 1156`GDB.h' 1157 1158File: nana.info, Node: WITHOUT_NANA, Next: I.h, Prev: nana.h, Up: Interface 1159 1160WITHOUT_NANA: disabling all nana code for portability. 1161====================================================== 1162 1163 If you wish to disable all nana code you can `#define' the 1164`WITHOUT_NANA' macro. This selects versions of the macros defined in 1165`I.h',`L.h', etc which map to `/* empty */'. 1166 1167 So if you are using nana for your development but don't wish to 1168force your customers to use it you can add an option to your 1169`configure' script to define/undefine `WITHOUT_NANA'. In addition you 1170will need to distribute copies of the nana header files with your 1171package to get the stubs. 1172 1173 Note that the `L.h' and `DL.h' macros use the macro variable number 1174of arguments extension provided by GNU C. If you wish your code to be 1175portable you should use the macros `VL((..))', etc rather than `L(..)' 1176to avoid problems with non GNU C preprocessors which only take a fixed 1177number of arguments. 1178 1179 1180File: nana.info, Node: I.h, Next: DI.h, Prev: WITHOUT_NANA, Up: Interface 1181 1182I.h: C based invariant checking 1183=============================== 1184 1185 This implements the C based invariant checking code and is a 1186replacement for `assert.h'. The first two macros are the normal user 1187interface; the remainder are used for configuring the behaviour on 1188failure, etc. 1189 1190 - Macro: void I (bool EXPRN) 1191 The EXPRN should always be true if the program is correct. If the 1192 EXPRN is false a message will be printed, followed by core dump.(1) 1193 1194 Checking can be enabled and disabled by using the I_LEVEL and 1195 I_DEFAULT_GUARD macros. See the definitions below for these macros 1196 for further details. 1197 1198 Note that EXPRN should have no side-effects(2) since disabling 1199 checking shouldn't change your programs behaviour. 1200 1201 I(z != 0); 1202 x = y / z; 1203 1204 - Macro: void N (bool EXPRN) 1205 The opposite of `I', i.e. the expression must never ever be true if 1206 the program is working properly. It is equivelant to `I(!(e))' and 1207 exists as a piece of syntactic sugar which may be helpful for 1208 complicated boolean expressions. 1209 1210 char* strdup(char *s) { 1211 N(s == NULL); 1212 ...; 1213 } 1214 1215 - Macro: int I_LEVEL 1216 The `I_LEVEL' macro is used to globally enable and disable 1217 checking by the macros in this file. It can take on one of three 1218 values: 1219 1220 `0' 1221 Disable all checking. Regardless of anything else no code 1222 will be generated for `I', `N', etc. 1223 1224 `1' 1225 Enable checking only if the corresponding guard condition is 1226 true. The guard condition can be used to enable and disable 1227 checking at compile and run time. 1228 1229 `2' 1230 Enable all checking regardless of guard conditions. 1231 1232 `I_LEVEL' defaults to `1'. 1233 1234 - Macro: bool I_DEFAULT_GUARD 1235 The `I_DEFAULT_GUARD' is used to selectively enable or disable 1236 checking at compile or run time. 1237 1238 `I_DEFAULT_GUARD' defaults to `TRUE', i.e. always enabled. 1239 1240 A user would typically define `I_DEFAULT_GUARD' to be global or 1241 local variable which is used to turn checking on or off at 1242 run-time. For example: 1243 1244 #define I_DEFAULT_GUARD i_guard > 0 1245 1246 extern int i_guard; 1247 1248 - Macro: text I_DEFAULT_PARAMS 1249 This is passed off to the `I_DEFAULT_HANDLER' and defaults to 1250 nothing, it is just some text and is intended to pass failure codes 1251 (e.g. `IEH303') or requests (e.g. `HW_DEAD') information off to 1252 the handler. 1253 1254 `I_DEFAULT_PARAMS' defaults to nothing. 1255 1256 - Macro: void I_DEFAULT_HANDLER (char *EXPRN, char *FILE, int LINE, 1257 PARAM) 1258 When an error is detected the `I_DEFAULT_HANDLER' will be called to 1259 handle the error. The arguments are: 1260 1261 `exprn' 1262 A string representation of the expression that has failed, 1263 e.g. `"I(i>=0)"'. 1264 1265 `file' 1266 The file that this error occurred in, i.e. `__FILE__'. 1267 1268 `line' 1269 The line number for the error, i.e. `__LINE__'. 1270 1271 `param' 1272 An optional parameter which can be passed across which 1273 defaults to `I_DEFAULT_PARAMS'. This can be used to pass 1274 failure codes or other information from the checking code to 1275 the handler. 1276 1277 All of the remaining macros are used to individually override the 1278default values defined above. Normally these macros would be used in a 1279system wide header file to define macros appropriate for the 1280application. For example you might use `IH' to define different 1281checking macros for hardware and software faults. 1282 1283 - Macro: void I (bool E) 1284 - Macro: void IG (bool E, bool G) 1285 - Macro: void IH (bool E, Macro H) 1286 - Macro: void IP (bool E, Text P) 1287 - Macro: void IGH (bool E, bool G, Macro H) 1288 - Macro: void IGP (bool E, bool G, Text P) 1289 - Macro: void IHP (bool E, Macro H, Text P) 1290 - Macro: void IGHP (bool E, bool G, Macro H, Text P) 1291 - Macro: void N (bool E) 1292 - Macro: void NG (bool E, bool G) 1293 - Macro: void NH (bool E, Macro H) 1294 - Macro: void NP (bool E, Text P) 1295 - Macro: void NGH (bool E, bool G, Macro H) 1296 - Macro: void NGP (bool E, bool G, Text P) 1297 - Macro: void NHP (bool E, Macro H, Text P) 1298 - Macro: void NGHP (bool E, bool G, Macro H, Text P) 1299 1300 We also provide support for referring to previous values of 1301variables in postconditions. The `ID' macro is used to create variables 1302to save the old state in. The `IS' and `ISG' macros are to set these 1303values. 1304 1305 - Macro: void ID (Text DECLN) 1306 - Macro: void IS (Text ASSIGNMENT) 1307 - Macro: void ISG (Text DECLN, bool G) 1308 1309 For example: 1310 void ex(int &r) { 1311 ID(int oldr = r); /* save parameter */ 1312 g(r); 1313 I(oldr == r); /* check r is unchanged */ 1314 while(more()) { 1315 IS(oldr = r); /* assign r to oldr */ 1316 h(r); 1317 I(oldr == r * r); 1318 } 1319 } 1320 1321 ---------- Footnotes ---------- 1322 1323 (1) If you don't want a core dump then look at stopping the core 1324dumps with `ulimit' rather than changing the handler. 1325 1326 (2) Side-effects include such operations as input/output or 1327assignments, e.g. `x++'. 1328 1329