
Q eQuational Programming System Version 4.6
Copyright (c) 1991-2004 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		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, and a system interface featuring binary and C-style
  formatted I/O, file system and process manipulation utilities, POSIX
  threads, BSD sockets, regular expression matching, ...

The distribution includes the Q programming tools, the standard library, a
collection of useful add-on modules for interfacing to various third-party
libraries and software, such as GNU Octave, GNU dbm, ODBC, GGI, ImageMagick,
Tcl/Tk and IBM's Data Explorer, as well as Q language modes for Emacs and
Kate. A Windows GUI frontend can be obtained as a separate package. For more
information please check out the Q homepage at SourceForge:

	http://q-lang.sourceforge.net

GETTING Q
=========

As of December 2003, Q has become a SourceForge-hosted project, which can be
found at the following URL:

	http://sourceforge.net/projects/q-lang/

There you can obtain released source and binary packages, as well as the
latest and greatest development sources in CVS, under the following URLs.

Download area:

	http://sourceforge.net/project/showfiles.php?group_id=96881

CVS access:

	http://sourceforge.net/cvs/?group_id=96881

Note that to build Q from the cvs sources you will first have to run the
autogen.sh script which creates the configure script and the Makefile.in
files. (You need autoconf, automake and libtool to do this.) Then you proceed
to configure and compile the sources as explained under "INSTALLING FROM THE
SOURCES" below.

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

See the INSTALL file for generic (UNIX) installation instructions. This
software has been tested on FreeBSD, Linux, Mac OS X and Windows, 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 FreeBSD, Linux and Windows systems 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, BeOS and Mac OS X. See also
the comments on specific systems below.

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 README files
with 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, but newer autotools versions should work as
well. 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.]

POST-INSTALL
------------

To complete the installation, you might wish to install Emacs Q mode. To these
ends, 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 and at the beginning of the q-mode.el file. In the etc directory
you also find a syntax file to enjoy Q syntax highlighting in the advanced KDE
editor Kate. Just copy the q.xml file into your kde/share/apps/katepart/syntax
directory and you're set. Moreover, a plugin which lets you run Q sessions in
GNU TeXmacs, the free scientific text editor (see http://www.texmacs.org), is
available as a separate tarball from the Q homepage.

TROUBLESHOOTING
---------------

When compiling from the sources, 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), gdbm (GNU dbm library, needed for the gdbm module), odbc
(ODBC library, needed for the odbc module), ggi (GGI libraries, needed for the
ggi module), magick (ImageMagick library, needed for the magick module), 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
------

Last time I 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. Cygwin has since advanced quite a bit so these problems
might be fixed in the newer versions.

FREEBSD
-------

(As of version 4.3.2, tested on FreeBSD 5.1-RELEASE. The same build procedure
might work on the other BSDs as well, but I have not tested this. Binary
packages and a port for FreeBSD 5.1 can be found on the Q homepage.)

Make sure you have a recent gmp library, as well as the libraries for the
modules that you want (gdbm, odbc, tk, etc., all available in the ports
tree). You'll also have to specify some compilation flags to enable the
compiler to find things in /usr/local. If you want multithreading, add
--with-pthread=-lc_r to the configure command.

Sample configure command (omit the Tcl/Tk include paths and --with-tk option
if you don't need the tk module):

CFLAGS="-O3 -I/usr/local/include -I/usr/local/include/tcl8.4 \
-I/usr/local/include/tk8.4 -L/usr/local/lib" \
./configure --with-tk="-ltcl84 -ltk84" --with-pthread=-lc_r

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 rpm
packages for some popular Linux distributions are available on the Q homepage.

On Linux (as well as other systems having an ISO C99-compliant printf function
which supports the %a conversion flag) you can add -DHAVE_ISO99_PRINTF to the
list of compilation flags. This will enable some special code in the `save'
and `load' commands which allows saved floating point values always to be
reconstructed exactly, without any rounding errors. To get this, configure
with `CFLAGS=-DHAVE_ISO99_PRINTF ./configure'.

MAC OS X
--- -- -

As of version 4.2, the sources can be compiled with the gcc 3.1 from the Mac
OS X development pack (10.2.4 has been tested, YMMV). The preprocessor of this
gcc version seems to be broken, but this can be worked around using gcc's
-no-cpp-precomp option. Configure as follows (using bash):

CFLAGS=-no-cpp-precomp ./configure --prefix=/usr

NOTE: Q-Tk applications currently require that you have an X11-based Tcl/Tk
installed and must be run in an X server, which is available from
http://www.apple.com/macosx/x11/. An X-less version which uses the native
(Aqua) Tcl/Tk is being worked on.

To get an X11 version of Tcl/Tk running on your system, you'll have to install
Tcl/Tk from source. First install the X11 server so that the necessary X11
libraries are available. Then get the Tcl/Tk 8.4 sources from
http://www.tcl.tk and follow the instructions for Unix installation. (*Don't*
use the OS X installation procedure, otherwise you will get the Aqua version.)

SOLARIS
-------

The sources should compile cleanly with gcc (versions up to 4.3.1 have been
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 an MSI installer package, 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.

All required libraries and other support files are included in this package,
except ImageMagick and Tcl/Tk, which you will have to install separately if
you want to use the corresponding modules. You can find Windows installers for
these libraries at the following URLs:

- ImageMagick: http://www.imagemagick.org/www/archives.html

- Tcl/Tk: http://aspn.activestate.com/ASPN/Downloads/ActiveTcl/

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.

If you want to build the native Windows port yourself, you need a recent
version of Mingw and Msys, both available at http://www.mingw.org. To build
the entire distribution, you'll also need MS Visual C/C++ and a bunch of
additional libraries. To ease porting, the Q homepage has a zip file with the
complete build tree used to create the current Windows release, including the
Qpad sources, the add-on modules, and all dependencies except ImageMagick and
Tcl/Tk.

OPTIONAL SOFTWARE
======== ========

The Q distribution comes with some add-on modules which can be found in the
`modules' directory of the Q source tree. (Other add-on modules are
distributed separately; please check the Q homepage for more information about
these.) `Clib', Q's "system" module which provides access to some important
functions from the C library, is now an integrated part of the standard
library, and is documented in the Q language manual. Some other modules are
provided to access various useful third-party software. Currently the
following optional software can be used with Q:

GDBM
----

Q's `gdbm' module provides an interface to the GNU dbm library, see gdbm(3).
If you have a Linux system then most likely you already have this library,
otherwise you can get it from http://www.gnu.org or one of its mirrors. This
module is also supported on FreeBSD, OS X and Windows. See README-Gdbm for
more information.

GGI
---

The `ggi' module provides access to the GGI (General Graphics Interface)
library, available from http://www.ggi-project.org. This module allows you to
create raster graphics on a variety of display devices. See README-GGI for
more information.

Please note that GGI itself doesn't provide any custom font support for text
rendering, but Q's `ggi' module does. To make this work, you'll also need
version 2 of the FreeType library, available from http://www.freetype.org/.

GHOSTSCRIPT
-----------

Q provides access to PostScript graphics via the `graphics' script contained
in the standard library. This script also provides an interface to
Ghostscript, a PostScript previewer which is available for a great variety of
systems and can be obtained from http://www.ghostscript.com.

IMAGEMAGICK
-----------

The `magick' module lets you access most common image formats using the
ImageMagick library, available from http://www.imagemagick.org. Using this
module you can, e.g., perform various image manipulation operations and render
image files in a GGI visual. See README-Magick for more information.

OCTAVE
------

The `octave' module provides access to John W. Eaton's Octave, a comprehensive
MATLAB-like software for performing advanced numeric computations. To use this
module, you must have Octave installed on your system, which is available from
http://www.octave.org. You can also find some additional items including
information about binary packages for Windows at the GNU Octave Repository
(http://octave.sourceforge.net/). See README-Octave for more information.

ODBC
----

ODBC has become the industry standard for portable and vendor independent
database access. Q's ODBC interface lets you connect to ODBC-compatible
databases and retrieve or modify data using SQL statements. To use this
module, you need an ODBC driver manager on your system, as well as the
database and corresponding ODBC driver you want to use. Two well-known open
source ODBC implementations are iODBC (http://www.iodbc.org/) and unixODBC
(http://www.unixodbc.org/). Two popular ODBC-compatible open source databases
are MySQL (http://www.mysql.com/) and PostgreSQL (http://www.postgresql.org/).
Under Windows you can also connect to various proprietary databases such as MS
Access. See README-ODBC for more information.

OPENDX
------

The `dxl' ("DX-Link") module provides an interface to IBM's Open Data
Explorer, a powerful scientific data visualization software. This software
needs Motif, and is only available for Unix and Linux systems at this
time. (At least there is no straightforward way to make it run on other
systems.) You can get it at http://www.opendx.org. See README-DXL for more
information.

TCL/TK
------

The `tk' module provides an interface to Tcl/Tk, John Ousterhout's command
language and graphical user interface toolkit. Using the `tk' module, you can
employ Tcl/Tk to create high-quality graphical user interfaces which are
portable across most popular operating systems and windowing environments,
including Unix/X11, Mac OS and MS Windows. See README-Tk for more information.

FEEDBACK
========

This software is provided free of charge and without any warranty, but that
does *not* mean that I'm not fixing bugs or listening to new ideas. ;-) So
your questions, comments, suggestions, contributions and, in particular, bug
reports and patches are always welcome. I'd also like to hear about your
experiences using Q, and which applications you use it for.

To these ends, the SourceForge project website provides an area where you can
post bug reports and patches, as well as support and feature requests.
Moreover, the site also offers two mailing lists for discussing Q development
and usage.


Enjoy!

January 2004  Albert Graef
