path: root/contrib/bluegnu2.0.3/doc/README.tex

%%
%%

\begin{document}

\title{Release Notice\\BlueGnu Testing Framework\\
Version 2.0.3}
\author{Jan-Willem Neurdenburg\\jotOmega dsc\\
56 Brigham Hill Road\\Grafton~MA~~01519-1135\\
neurdenburgj@acm.org\\Tel: (508) 839-0276\\Fax: (508) 839-7267}

\maketitle

\section{Introduction}
BlueGnu is a framework for testing other programs. It has been created
to be compatible with DejaGnu. Its purpose is to provide a single
front end for all tests. Beyond this, BlueGnu offers several
advantages for testing:

\begin{itemize}

\item The flexibility and consistency of the BlueGnu framework makes it
easy to write tests for any program, with the exception of GUI
applications.

\item BlueGnu provides a layer of abstraction, which makes all tests
(if correctly written) portable to any host or target where a program
must be tested.

\item BlueGnu is written in [incr Tcl], which in turn is based on Tcl
(Tool Command Language). The framework comprises two parts:
\begin{enumerate}
\item the testing framework,
\item the test-suites or test-sets themselves.
\end{enumerate}

\item BlueGnu will work with any Tcl based interpreter as long as
[incr Tcl] has been included. You can include 'expect', 'Tk', and/or
other extensions.

\item Includes DejaGnu release 1.6

\end{itemize}

\section{Requirements}
The following modules should have been installed, before you can
install and/or use BlueGnu:

\begin{itemize}
\item Tcl release 8.0 or higher,
\item incr Tcl release 3.0 or higher.
\end{itemize}

Any other extensions that is compatible with Tcl release 8.0 can be used
as well.

\section{Structure and Contents of the Release}

The root directory of the release contains the README files with
installation instructions and the files needed to build and install
this product. It also contains the executable scripts of the
BlueGnu testing framework.

The top-level directories are listed below:

\begin{description}
\item[lib:] the packages and procedures that make the BlueGnu and
DejaGnu testing framework. This also includes the default target
definition files.

\item[testsets:] the BlueGnu test-suites and test examples. It contains
the following subdirectories.

\begin{description}
\item[BlueGnu:]
test scripts to test the testing framework itself.

\item[examples:]
test suite and test script examples.

\item[config, lib, tools:]
currently empty, but can be used for
test-set dependent configuration files, library files, and tools.
\end{description}

\item[config:]
currently empty.

\item[doc:] the DejaGnu texinfo source and the documentation in
'info', 'dvi', 'ps', and 'pdf' representation, respectively
dejagnu.info*, dejagnu.dvi, dejagnu.ps, and dejagnu.pdf. A DejaGnu man
page is also available.

It also contains
the \TeX{} version (README.tex) of this document as well as the 'dvi', 'ps'
'html', and 'pdf' representation, respectively notice.dvi, notice.ps,
notice.html, and notice.pdf.

\item[testsuite:] contains a mixture of DejaGnu and BlueGnu test
scripts.

\item[contrib:] contains examples how DejaGnu is used at Cygnus.

\item[example:] contains a full DejaGnu test framework example for testing the program 'calc' which is also included.

\end{description}

\section{Installation and use under Unix}

Before you can install and use BlueGnu you need to have installed the
following three packages:
\begin{itemize}
\item Tcl version 8.0.3
\item Tk version 8.0.3
\item incr Tcl version 3.0.1
\end{itemize}
The source for these packages should all be located in one directory.
The subdirectory in the directory should be:
\begin{itemize}
\item tcl8.0.3
\item tk8.0.3
\item itcl3.0.1
\end{itemize}

The following examples use the command `./configure
--prefix=/tools/...`. This will install all packages in a directory
``/tools''. When you omit the ``--prefix''-switch then the
installation default will be the directory ``/usr/local''.

\subsection{Installation of needed Packages}

When you have not installed Tcl and the other needed extensions, then
you need to retrieve the sources from ``www.tcltk.com/itcl''. You need
to `gunzip` the files and do a `tar xf` of all these packages in one
directory, let's call this directory ``TclTk''.

From the directory ``TclTk'', you should do the following to install
the packages:

\begin{verbatim}
% cd tcl8.0.3/unix
% ./configure --prefix=/tools/tcl8.0.3 --enable-gcc --enable-shared
% make
% mkdir /tools/tcl8.0.3
% make install
% cd ../../tk8.0.3/unix
% ./configure --prefix=/tools/tk8.0.3 --enable-gcc --enable-shared
% make
% mkdir /tools/tk8.0.3
% make install
% cd ../../itcl3.0.1
% ./configure --prefix=/tools/itcl3.0.1 --enable-gcc --enable-shared
% make
% mkdir /tools/itcl3.0.1
% make install
\end{verbatim}

\subsection{Installing BlueGnu}
You can now `gunzip` and `tar xf` the BlueGnu version 2.0.3 in the
directory ``TckTk''. This will create the directory
``bluegnu2.0.3''. Now do the following:

\begin{verbatim}
% cd bluegnu2.0.3
% ./configure --prefix=/tools/bluegnu2.0.3
% make
% mkdir /tools/bluegnu2.0.3
% make install
\end{verbatim}

This will install BlueGnu in the directories:
\begin{itemize}
\item /tools/bluegnu2.0.3/bin
\item /tools/bluegnu2.0.3/lib/bluegnu
\item /tools/bluegnu2.0.3/info
\item /tools/bluegnu2.0.3/man
\end{itemize}

\subsection{Using BlueGnu}
When you have installed [incr Tcl] and BlueGnu and you have the
respective ``bin'' directories in your PATH variable, then you can
start running some tests. You can go into the BlueGnu source directory
``bluegnu2.0.3/testsets/examples'' and run the following:

\begin{verbatim}
% bluegnu versionTcl.itcl
% bluegnu ts_001
% bluegnu ts_002
% bluegnu ts_003
\end{verbatim}

The above test result should all be PASS. The following test will give
a result UNKNOWN, because no pass/fail instruction have been given.

\begin{verbatim}
% bluegnu tc001
\end{verbatim}

The last test you can run will fail in its simple form:

\begin{verbatim}
% bluegnu tc002
\end{verbatim}

But will pass if you execute the test as follows:

\begin{verbatim}
% bluegnu tc002[English]
\end{verbatim}

This is because the test scripts need a test case identifier to find
the correct benchmark code.

\section{Changes}
\subsection{Version 2.0.3}
This being the first public release it is not to useful to list all
the changes. BlueGnu has been modeled after DejaGnu and is a complete
new implementation which has been tested thoroughly. When
documentation is being written more changes will be made. An example
of some of these changes as a result of this documentation effort can
be found in the test-suites ts\verb+_+001, ts\verb+_+002, and
ts\verb+_+003. The first two are not as easy to write as the
third. The test suite ts\verb+_+001 is a script implementation of the
command line:
\begin{verbatim}
% cd bluegnu2.0.3/testsets
% bluegnu examples/tc002[English=B] \
> "examples/tc002[Dutch=B]={MSG=Hallo Wereld}"
\end{verbatim}
This may be useful for simple tests but when you want to write more
complex test-suite scripts you would like some more flexibility, so two
procedures were introduced, which are shown in test-suite ts\verb+_+002. This
makes writing rather complex so the procedures have become part of
the procedures 'appendQueue', 'prependQueue', and 'runtest'. The
resulting script is shown in test-suit ts\verb+_+003.

Changes like this will be made in the future!

\section{Future Enhancements}
The following enhancements are being planned:
\begin{itemize}
\item Target code will be made into a class with methods 'start',
'load', 'exit', and 'version'. Instead of the current
'$<$target$>$\verb+_+start', '$<$target$>$\verb+_+load', '$<$target$>$\verb+_+exit', and
'$<$target$>$\verb+_+version', which have been taken from DejaGnu.

\item Procedures will be created that make it easy to test WEB
application from the framework.

\item Other enhancements will be made depending on the use of the
framework in testing different applications.
\end{itemize}
\end{document}