Nana uses the normal GNU install method in the same way as `gcc' and `gdb'. To install nana in the default location `/usr/local/{bin,lib,include}' you would use:
% gzcat nana-1.10.tar.gz | tar xvf - % cd nana-1.10 % ./configure % make % make install % make check % make check-mail % make subscribe
The check-mail and subscribe targets both send e-mail. If you need to change the mailer used try something like:
% make MAIL=elm subscribe
Note: we need to install nana before running the `make check' target. The `check-mail' target sends the test report via e-mail to the `nana-bug@cs.ntu.edu.au'.
Of course things are never that simple. If you want to install Nana in a different location or change the behaviour on error detection see section Configure.
Each of the sub-directories nana can be compiled and installed separately, e.g. if you don't need the documentation you can just compile and install from the `src' sub-directory after doing the configure statement.
The following software is possibly required to run nana.
gcc-2.7.2
gdb-4.16
gmake
For a listing of porting results including software versions see:
`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'
In addition to the required software you might also be interested in:
Nana uses a standard GNU autoconf generated configure
script. The configure script checks the setup on your machine and
then generates the appropriate Makefiles. Some of the things checked by
configure include:
-lposix flag to the linker to build programs
on your machine.
unistd.h available on this machine.
In addition `configure' uses the host architecture and operating system to generate the `nana-config.h' file. This file contains some macro definitions which define how nana works on particular operating systems and hardware architectures.
For example on `i386' machines we would use the `asm("hlt")' instruction whenever an assertion fails, on a `sparc' we would use `asm("stp")'. Otherwise we would default to a plain C call to `abort()' If `configure' does not recognise your machine it uses plain C code.
You may wish to change these defaults on installation, one method is to edit
a local copy of the `nana-config.h' file. Alternately you can define
the code yourself in the call to `configure'. For example
to redefine the action we take when an error is detected by the I
macro we can use:
I_DEFAULT_HANDLER="restart_system()" ./configure
As well as simple calls to routines various other bits of information are passed off to the `I_DEFAULT_HANDLER' such as the expression that failure and a failure code. For example:
% I_DEFAULT_HANDLER="restart(line,file,param)" ./configure
The default for `I_DEFAULT_HANDLER' calls a function which prints a message and then dumps core. Different behaviour on failure can be organised by setting the `I_DEFAULT' to `fast', i.e. plain core dump or `verbose' which prints an error messsage and then does the core dump.
% I_DEFAULT=fast ./configure
For nana the following examples may be useful:
./configure
Accept the default values for everything. In particular the files will
be installed in:
`/usr/local/{bin,include,lib,man,info}'
./configure --prefix=~project/tools
Install the files into:
`~project/tools/{bin,include,lib,man,info}'
./configure --bindir=~project/bin --libdir=~/project/lib \
--includedir=~/project/headers --infodir=/usr/local/info \
--mandir=~/project/doc
The install directory for program (`bin'), etc can all be set with
command line arguments to`configure'.
CC=xacc LIBS=-lposix ./configure sun3
If the defaults chosen by `configure' are not correct you can
override them by setting variables such as CC before calling
`configure'. The `sun3' argument is used to identify the
machine we are running on and may be necessary on some machines.
./configure --help
And of course when in doubt ask for help.
For even more details see the file `INSTALL.con' which contains the generic instructions for use with `autoconf' generated `configure' scripts.
The configure program uses the following shell variables to change various defaults. Another method is simply to edit the `nana-config.h' file. Most of these values should be auto detected, so you can ignore this section until your need to save a few bytes of store by using `asm("hlt")' instead of a call to `abort()'.
DI_MAKE_VALID_BREAKPOINT
DL_MAKE_VALID_BREAKPOINT
I_DEFAULT_HANDLER
asm("hlt")
asm("stp")
abort()
restart()
ALWAYS_INCLUDE_MALLOC
Nana has been tested on the following platforms:
The `alpha-dec-osf3.2', `mips-sgi-irix5.3' and `powerpc-ibm-aix3.2.5' implementations have problems when you compile with `-O2' or `-O3' optimisation. This causes some errors in the the debugger based assertion and logging code since variables can be removed or changed by optimisation. At `-O' everything passes. Regardless of optimisation the C based checking code passes all tests on these platforms.
If you use nana on a new platform please send the `check.log' file to `nana-bug@cs.ntu.edu.au' via the `make check-mail' command. A machine generated list of this information is available at:
`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'
Currently Nana works with the GNU GDB debugger which is available on a wide range of platforms including embedded systems and even provides support for remote debugging. Porting to any reasonable debugger with conditional breakpoints and commands is not very difficult.
As an example of an unreasonable debugger, Nana has been ported to
work with the MicroSoft Codeview debugger. The port is small (60 lines of
code) but suffers from a problem with variable scoping in Codeview. If
a breakpoint is set at a point in the code the expressions are not
evaluated from that particular scope. For example setting a breakpoint
in the function f cannot access a variable local to f
directly. Codeview has a unique (expletive deleted) scope operator
which you must use to set the scope `{...}'. This makes the
interface somewhat less than beautiful.
Another good thing about CodeView is to try a debug command which prints a message which contains a single open `{'. This of course causes it to hang and was the main problem during the porting to CodeView which took a whole day(2).
If anyone is interested I may release the CodeView implementation, please contact me if you are interested. Of course a better bet is probably to move to the `gdbserver' system. I think `gdb' has been released as a native even for some MicroSoft operating systems.
Other debuggers like DBX don't seem to be worth the trouble since gdb works on those machines. A redesign of the nana internals may also be useful if we decide portability between debuggers is actually useful.
Nana has the following known features (or perhaps problems):
DI or DL should be on lines by themselves. If you
mix code and nana macros on the same line you will get errors, e.g:
main(){
int x;
x = 5; x--; DI(x == 4);
}
This doesn't work since breakpoints are set at line boundaries rather
than statement ones. Of course anyone who writes code like this deserves
whatever happens to them.
DI(x +
10 > 30);
A few backslashes may solve this particular problem.
% ./configure pdp11-dec-ultrix
configure
script detecting vsnprintf. If configure doesn't find it
and it does exist then simply define it in `nana-config.h' as per
the previous question.
If vsnprintf really doesn't exist then get a new C library,
possibly the GNU libc.
vsprintf opens a security hole since no
bounds checking is done by it. Nana attempts to use vsnprintf
which is safe when it exists but it will resort to vsprintf
if it can't find vsnprintf. All careful people should make
sure that they have a library with vsnprintf.
STL header file errors due to nana.
The C++ STL header files for version 3.0 at least must
be included before the Q.h file. The problem is caused by the STL
files using S as a template argument. Of course Q.h uses
S for summing a series. Namespace pollution strikes again.
(Thanks to Han Holl for this particular problem).
If you think you have found a bug in the Nana library, please investigate it and report it.
If your bug report is good, we will do our best to help you to get a corrected version of the library; if the bug report is poor, we won't do anything about it (apart from asking you to send better bug reports).
Send your bug report to:
`nana-bug@cs.ntu.edu.au'
Copies of bug reports will be kept at:
`http://www.cs.ntu.edu.au/homepages/pjm/nana-bug/'
New versions of nana will be made available at:
`ftp://ftp.cs.ntu.edu.au/pub/nana/'
If you wish to be informed about new releases of nana then subscribe to the nana mailing list. Send a message containing `subscribe' <your e-mail address> to:
`mailto:nana-request@it.ntu.edu.au'.
A hypermail archive of this list is kept at:
`http://www.cs.ntu.edu.au/hypermail/nana-archive'
If you wish to send a message to the list send it to `mailto:nana@it.ntu.edu.au'.
Go to the first, previous, next, last section, table of contents.