
Q eQuational Programming System Version 3.3
Copyright (c) 1991-2002 by Albert Graef
<ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de>

The Q programming system is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.

The Q programming system is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

(See the file "COPYING" included in the distribution for the GNU General
Public License.)


Author's address:

Albert Graef			Johannes Gutenberg-Universitaet Mainz
Schmittpforte 11                Musikwissenschaftliches Institut
55599 Wonsheim/Germany          Bereich Musikinformatik
Dr.Graef@t-online.de		P.O. Box 3980
				55099 Mainz/Germany
				ag@muwiinfa.geschichte.uni-mainz.de

URL: http://www.musikwissenschaft.uni-mainz.de/~ag


-----------------------------------------------------------------------------


Q is a powerful and extensible functional programming language based on the
term rewriting calculus. You specify an arbitrary system of equations which
the interpreter uses as rewrite rules to reduce expressions to normal form. Q
is useful for scientific programming and other advanced applications, and also
as a sophisticated kind of desktop calculator.

Q's main features:

- advanced symbolic expression manipulation, using equations supplied by the
  programmer

- fast bytecode interpreter, which executes Q scripts almost as fast as
  interpreted Lisp or Haskell

- built-in support for arbitrary precision integers, double precision floating
  point numbers, strings, lists, tuples, curried function applications, lazy
  evaluation, exception handling, and user-defined object-oriented data types
  with single inheritance

- simple but powerful module system which lets you manage large scripts with
  ease, and a libtool-based interface to external C modules which allows such
  modules to be loaded at runtime

- comprehensive standard library written mostly in Q itself, which includes
  powerful list processing functions, a collection of useful container data
  structures, an implementation of the lambda calculus, an interface to the
  PostScript language, binary and C-style formatted I/O, system utilities,
  POSIX threads, regular expression matching, ...

The distribution includes the Q programming tools, the standard library,
add-on modules for interfacing to GNU Octave, Tcl/Tk and IBM's Data Explorer,
and an Emacs mode. A Windows GUI frontend can be obtained as a separate
package. For more information please check out the Q homepage at:
http://www.musikwissenschaft.uni-mainz.de/~ag/q

(As you'll see, I don't update this page very frequently, as I'm usually busy
with other things. But there you can find new releases as they become
available.)

INSTALLATION
============

See the INSTALL file for generic (UNIX) installation instructions. This
release has been tested on Linux, Solaris, Windows and BeOS, and should also
work (with minor tweaking) on most other modern UNIX/POSIX-based
platforms. Please report any patches required to build the package on other
systems s.t. they can be included in the next release.

Binary packages for Intel-based Linux and Windows systems platforms are
available on the Q homepage. If you can contribute binaries for other systems
please let me know.

INSTALLING FROM THE SOURCES
===========================

If you have a Bourne-compatible shell, a POSIX-compatible C library, and
either gcc (recommended) or another decent C compiler with ANSI C support,
chances are that you will be able to build this package from source without
too much hassle.

You'll need the GNU multiprecision library version 3.0 or later. If this
library is not available on your system, get it at http://www.swox.com/gmp/
and install it first.

Usually you just run:

	./configure && make && make install

If you want optimized executables use something like:

	CFLAGS=-O3 ./configure && make && make install

If all is well, this will install Q in the default location (/usr/local); you
can invoke the configure script with the --prefix option to change this. There
are a number of other configure options to play with; run configure with the
--help option for a list of the available options.

Once the interpreter is installed, you can run a simple test suite with

	make test

This is by no means an exhaustive check of the interpreter's internals, but if
any of these simple tests fails then there's probably a portability bug that
needs to be fixed.

The same build process should also work on Cygwin and BeOS. See also the
comments on specific systems below.

To install Emacs Q mode, copy the q-mode.el file under <prefix>/share/q/etc to
your Emacs site-lisp directory, and set up your .emacs file as described in
Appendix E of the manual.

Documentation is available in texinfo format, from which you can create both
online and printed manuals in a variety of formats. The online manual in info
format will be installed on your system. Furthermore, additional information
about the installed modules can be found in <prefix>/share/q/etc.

[MAINTAINER'S NOTE: The current release was prepared using autoconf 2.52,
automake 1.5 and libtool 1.4.2. Other versions might work as well, but have
not been tested. A bootstrap script is included in the source distribution.
Note that you only need these tools if you want to work on the configure
scripts and automake Makefiles.]

TROUBLESHOOTING
===============

The most common problem probably is that shared libraries and external modules
refuse to build on your system. In this case, you can disable dynamic modules
altogether with the --disable-shared configure option. This should work on
*any* system supported by libtool, and you will still be able to use the
modules bundled with the Q distribution since these will be linked directly
into the interpreter.

If you *can* build the modules successfully, you may still encounter problems
loading them in the interpreter. (Libtool's dynamic module loader, libltdl, is
still under development and does not work on some systems at this time.) In
this case, if you have a custom libltdl on your system, you can try to use
that with the --with-installed-ltdl configure option. (Use this option with
care. If you do not have libltdl on your system or configure cannot locate it,
the bundled libltdl will be built and installed on your system, which may
cause problems with other libltdl-based applications.)

Another potential obstacle is that the GNU readline library bundled with the Q
distribution, which the interpreter uses to provide advanced command line
editing features, refuses to compile. In this case you can disable readline
support with the --without-rl option. If you have a readline library on your
system, you can also specify --with-rl=-lreadline to tell configure to use the
installed library.

More generally, if configure fails to locate some required or optional
third-party libraries on your system, you can specify --with-PKG=LIBS and
--with-PKG-includes=INCLUDES to tell configure how to link these libraries
(-L, -l etc.), and which additional includes (-I) are required to access the
corresponding header files. Currently PKG can be gmp (GNU multiprecision
library), dmalloc (dmalloc support), pthread (multithreading support), rl
(readline library), tk (Tcl/Tk libraries, needed for the tk module) or dxl
(Data Explorer DXLink library, needed for the dxl module). Among these only
the gmp library is strictly necessary for building the package. Multithreading
support will be enabled by default if the POSIX thread library is found, but
can be disabled with the --without-pthread option.

For instance, if your gmp library is in /root/lib and the gmp.h header file in
/root/include, then you would configure with:
./configure --with-gmp="-L/root/lib -lgmp" --with-gmp-includes=-I/root/include

SYSTEM-SPECIFIC NOTES
=====================

BEOS
----

The bundled readline 4.2 won't compile, and the module loader in the stock
libltdl is broken. I suggest that you install the readline library from the
GeekGadgets package and the fixed libtool package, both available from
http://www.bebits.com. Then you can build the package with:

./configure --with-rl=-lreadline --with-installed-ltdl

Otherwise you'll have to live without readline and dynamic loader support, and
you should configure as follows:

./configure --without-rl --disable-shared

Note that currently there's no multithreading support, as there's no pthread
library for BeOS.

CYGWIN
------

When I last checked, dynamic modules failed to compile properly, and Cygwin's
pthread support was lacking, so you might have to build with --disable-shared
and --without-pthread.

LINUX
-----

Linux is the primary development platform for this software, and the sources
should build out of the box on all recent Linux distributions. Binary packages
in rpm format are available on the Q homepage.

SOLARIS
-------

The sources compile cleanly with gcc (tested with gcc 2.95.2 under Solaris
2.8/x86). Configure as follows:

./configure --with-rl=-lreadline --with-pthread="-lpthread -lrt"

This assumes that you have SUN's software companion cd installed. Otherwise
omit the --with-rl option. The -lrt (-lposix4 on older Solaris systems) is
needed to get the semaphore functions, if you're building with pthread
support.

WINDOWS
-------

A binary release for all current 32 bit Windows systems, the Qpad package, is
available from the Q homepage. It provides a setup program, a user-friendly
Windows GUI frontend to the interpreter, extensive online documentation
including the full Q language manual in html help format, and of course
precompiled binaries of the Q programming tools, libraries and modules.

If you want to build the native Windows port yourself, you need Mingw
(http://www.mingw.org). (A few optional parts of the distribution also require
the MS Visual C compiler.) All necessary additional Makefiles are included in
the distribution, and some other required bits (like precompiled native
Windows binaries of the gmp and readline libraries) are available from the Q
homepage.

If you would like to use q-mode.el under Windows, you should get a Win32
version of Emacs which supports processes (and hence comint). Two nice Windows
ports of Emacs are NT Emacs (see http://www.cs.washington.edu/homes/voelker/
ntemacs.html) and XEmacs (http://www.xemacs.org). After installing Qpad, you
can find q-mode.el in Qpad\etc under your program files directory. Copy this
file to your Emacs site-lisp directory, and set up your .emacs file as
described in Appendix E of the manual.


Enjoy!

April 2002  Albert Graef
