==============================================================================
README.  Generated from README.in by configure.
==============================================================================

General information
===================

Name		: mupad-combinat
Version		: 1.2.1
Summary		: MuPAD-Combinat -- Algebraic Combinatorics package for MuPAD
License		: LGPL
Vendor:		: Nicolas M. Thiéry <nthiery@users.sourceforge.net>
URL		: http://mupad-combinat.sourceforge.net/
Requires	: MuPAD 
Description	:
MuPAD-Combinat is an open-source algebraic combinatorics package for
the Computer Algebra System MuPAD 2.0.0 and higher.
Main features:
 * classical combinatorial classes such as partitions or tableaux;
 * classical combinatorial algebras such as symmetric functions;
 * tools for building user defined combinatorial classes and algebras.


Requirements
============

The computer algebra system MuPAD, version 2.0.0 or above. This system
is available in binary form for many operating systems.

	http://www.mupad.de

Using the lastest version of MuPAD (currently 2.5.2) is recommended,
as some features are more efficient there. Also, for older versions of
MuPAD, the package comes with some compatibility fixes to the MuPAD
library; those might break accidently some other parts of MuPAD; in
case of doubt, please try to upgrade.

Free licences for MuPAD are available for personnal use and (up to a
point) research; check the web page of Sciface for details:

	http://www.sciface.com

Most of the library is written in pure MuPAD, and should work on all
operating systems supported by MuPAD, including Windows. The
installation procedure however is quite UNIX oriented; it has
currently been successfully tested on various flavors of Linux, on
Open-BSD (note that there is no official port of MuPAD for this
system), as well as on Mac OS X (up to one remaining glitch with the
GLIP dynamic module).

Here are the precise requirements outside of the library itself:

For the C++ dynamic modules:
 - gcc >= 2.95.
For the dvi, ps, and pdf documentation:
 - a fairly recent distribution of latex, such as tetex-1.*;
 - pdflatex
For the installation procedure:
 - gnu make
   Hopefuly in the future any version of make will work.
   Note: there are systems where GNU make is installed by default
   under a different name, like 'gmake'. Just use this name instead of
   'make' in all the 'make' commands below.

For the C generation feature of the library combinat::decomposableObjects:
 - gmp >= 4.0.0

Download and Installation
=========================

mupad-combinat is distributed on the web page (see above) in precompiled
RPMs (GNU/linux i386), source RPMs, and source code. Upon request, we
may build other binary distributions, including packages for debian,
slackware, or solaris. The latest development version can be obtained
by anonymous CVS (see below).

Under UNIX and Mac OS X, the installation from source code follows the
usual scheme configure / make / make install. See the file 'INSTALL'
for generic instructions and 'QuickInstall' for a brief summary.

Users of Windows should be prepared to do the installation by hand,
and are welcome to contact us for support. Note furthermore that the
dynamic modules cannot be compiled yet. Help to build an installer and
to setup a build system for windows would be very much appreciated.

In fact, a large part of the functionnalities are right away
integrated in MuPAD Pro 3.1.0, and nothing specific needs to be
installed. For the other functionnalities, the full package needs to
be installed as follow:

Download mupad-combinat-<version>.tar.gz, and unpack it (windows will
probably take care of this automatically). Rename the created
directory into MuPAD-Combinat, and move it into

	C:\Program Files\Sciface\MuPAD Pro 3.1.0\packages\

(or something similar). Afterward, you should be able to load the
package in your MuPAD session by typing:

	>> package("MuPAD-Combinat"):

In any cases, we strongly recommend that you join the users mailing list:

http://lists.sourceforge.net/mailman/listinfo/mupad-combinat-users

License
=======

mupad-combinat is open source software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public License, a
copy of which is provided in the file 'COPYING.LIB'.

If you use this software for your research, please cite it as you
would cite any journal or book. We would also appreciate if you could
let us know about it (either by e-mail, or better via the Wiki
http://mupad-combinat.sourceforge.net/Wiki/UserTestimonials). This
will help us find support for further development of this package. And
this makes us feel useful :-)

External programs included in the distribution:
===============================================

mupad-combinat contains optional interfaces with external C/C++
programs. For the user convenience we have included the sources of
most of those programs in our distribution. We would like to thank
their original copyright holder for allowing us to do so. We however
do not own those software copyright, and they may bear other licences
than the LGPL.

If you plan to redistribute mupad-combinat, you may safely strip away those
sources from the distribution. Otherwise, please make sure those
licences are compatible with the distribution mean, and/or contact
their respective copyright holder for permission.

Symmetrica:
 - Copyright Axel Kohnert & all
 - License: public domain
 - URL: http://www.mathe2.uni-bayreuth.de/axel/symneu_engl.html
 - Source directory: src/Symmetrica
 - Configure option: --(en/dis)able-symmetrica

Littlewood-Richardson Calculator:
 - Copyright (C) 1999 Anders S. Buch (abuch@math.mit.edu)
 - License: GPL
 - URL: http://www-math.mit.edu/~abuch/lrcalc/
 - Source directory: src/lrcalc
 - Configure option: --(en/dis)able-lrcalc

Nauty 2.2: (not yet included by default)
 - Copyright Brendan McKay, bdm@cs.anu.edu.au
 - License: see src/nauty/nauty.h
 - URL: http://cs.anu.edu.au/~bdm/nauty
 - Source directory: src/nauty
 - Configure option: --(en/dis)able-nauty

MuPAD Documentation tools and LaTeX style files:
 - Copyright 2002 SciFace Software GmbH
 - License: LaTeX Project Public License
 - URL: ftp://ftp.mupad.de/MuPAD/distrib/doc-utils
 - Source directories: src/TOOLS, src/STYLES

Bug reports & mailing lists
===========================

The web page (see General Information above) provides access to
mailing-lists as well as to a bug tracking system. Please use them
for bug reports, suggestions, flames and other comments. Any
contribution will be warmly welcomed. If you don't have web access,
feel free to contact directly the authors (see the file 'AUTHORS').

Please include the following information in any bug report:
 - Some information about your system:
   - What operating system and version,
   - For Linux, what version of the C library,
   - The version of the compiler (if you know),
   - Anything else you think is relevant;
 - A description of the bug itself;
 - If you can reproduce the bug, the exact steps to reproduce it;
 - Anything else which you think is helpful.


Getting the latest version from the CVS repository
==================================================

Anonymous CVS read-only access:

	cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/mupad-combinat login 
	cvs -z3 -d:pserver:anonymous@cvs.sf.net:/cvsroot/mupad-combinat co MuPAD-Combinat

When prompted for a password for anonymous, simply press the Enter key.


Developer CVS access via SSH:

Only project developers can access the CVS tree via this method. SSH1
must be installed on your client machine. Substitute developername
with the proper value. Enter your site password when prompted.

	export CVS_RSH=ssh 
 	cvs -z3 -d:ext:developername@cvs.sf.net:/cvsroot/mupad-combinat co MuPAD-Combinat

Once checked out, the rest of the configuration and installation is as
usual (./configure; make; make install). Later on, you just need to
run `cvs update -d` in the MuPAD-Combinat directory to update to the
latest version.

See also http://sourceforge.net/cvs/?group_id=20513

==============================================================================
Directory structure of the distribution
=======================================

Combinat-<version>/
    lib/		        // MuPAD source code of the package
        init.mu			// Main initialization file

        LIBFILES/		// Initialization files of the libraries
            combinat.mu
            muEC.mu

        COMBINAT/		// Library combinat
            partitions.mu	// source code of combinat::partitions
            ...
            TEST/		// test files
                partitions.tst	// test file for combinat::partitions
                ...
	    DOC/		// TeX source for the documentation
		partitions.tex	// documentation for combinat::partitions
		...

        MUEC/			// Library muEC
            COMP/		// Library muEC::COMP 
		DOC/		// documentation for muEC::COMP
            PART/, SYMF/, SG/, SP/, ERR/, TYP/
            TEST/		// test files for muEC

        DOMAINS/		// Domains, axioms and categories
            AXIOM/
            CATEGORY/
            DOMAIN/

    src/			// C / C++ source code that is needed
				// for the dynamic modules

        MAPITL/			// standard distribution of MAPITL
        GLIP/			// standard distribution of GLIP
        Symmetrica/		// standard? distribution of symmetrica

			        // C++ source code of the dynamic modules
        gordan/
        GLIP-module/
        Symmetrica-module/

    doc/			// Documentation
	dvi/			// Documentation in large format for
				// the MuPAD help tool
	    combinat.mdvi
	    combinat.ps
	    combinat.pdf
	    ...

	    checklog		// complete log of all the documentation tests
	    combinat.res	// results of documentation tests for combinat
	    combinat.checklog	// log of documentation tests for combinat

	dvia4/			// Documentation for printing on a4 paper
	    combinat.mdvi
	    combinat.ps
	    combinat.pdf
	    ...
	html/			// Documentation in html
	    combinat.html
	    ...
	ascii/			// Documentation in ascii
	    combinat.help
	    ...
	STYLES			// style files from the MuPAD distrib
	    misc/		// style files missing in some LaTeX distribs
	FONTS/			// fonts from the MuPAD distrib
	TOOLS/			// documentation tools from the MuPAD distrib


    modules/
        <arch>/<version>	// contains links/copies of the dynamic modules
        			// to enable preinstallation tests and use
        			// with package(".");

    test/			// Results of test files
	checklog		// complete log of all the tests
        COMBINAT/
	    combinat.res	// results of tests for combinat
	    combinat.checklog	// log of tests for combinat
	    partitions.res	// results of tests for combinat::partitions
	    partitions.checklog	// log of tests for combinat::partitions
	    ...
        MUEC/
        DOMAINS/
            AXIOM/
            CATEGORY/
            DOMAIN/

    Papers/			// Papers & affiliated about MuPAD-Combinat
	SLC49/main.pdf, main.dvi, ...
	Poster/main.pdf, main.dvi, ...

Directory structure after installation:

<prefix>/MuPAD-Combinat
    lib				// As in the distribution
    modules/
        <arch>			// contains all the dynamic modules
    doc/			// As in the distribution

==============================================================================
Notes for the maintainer
========================

The configure script is generated by automake/autoconf. You need
automake >= 1.8, autoconf >= 2.59, and libtool >= 1.5. Here is the
sequence of commands to recompile fully from scratch:

	make maintainer-clean
	rm -f config.cache configure
	autoreconf
	./configure --enable-maintainer-mode --config-cache
	make
	make check
	make install

Building binary packages (rpm's, deb's, ...)
--------------------------------------------

This requires epm (http://www.easysw.com/epm/) and, obviously, the
appropriate package building tools (rpmbuild, dpkg, ...). Here is how
to build a rpm:

	make epm-prepare
	make epm-rpm		# or epm-deb, epm-osx, epm-pkg, ...
	make epm-clean

Similar rules exist for most packaging systems; see the doc of epm for
details. The binary packages are put in the distribution/
subdirectory.

Creating a new release
----------------------

Update the files configure.ac, NEWS and ChangeLog, rerun bootstrap as
above, and issue:

	make release

Adding a new dynamic module called bla
--------------------------------------
 - Create a new directory src/bla, taking example over src/gordan/
 - The main source file should be src/bla/bla.mcc
 - Edit the file src/bla/Makefile.am appropriately
 - Edit the file configure.in:
    - Add src/bla/Makefile in AC_OUTPUT
    - Add a new conditional bla, taking example over what's done for gordan
 - rerun bootstrap as above

------------------------------------------------------------------------------
Updating files on the MuPAD CVS server (DANGEROUS)
------------------------------------------------------------------------------

Editing the list of files to be transfered to the MuPAD standard library:
-------------------------------------------------------------------------
See the variables MUPAD_LIBRARY_FILES and MUPAD_DOC_FILES in the main
Makefile.am

Commiting the files to the MuPAD standard library CVS repository:
-----------------------------------------------------------------

Be really sure that you know what you are doing!

You need to have a developers login on the MuPAD CVS server, and to
have the mupad library and documentation directories checked out
somewhere on your system with read-write permissions. The variables
MUPAD_LIBRARY_CVS MUPAD_DOC_CVS in the main Makefile.am specifies
where those directories are. You can also specify them on the command
line.

	make mupad-update-cvs MUPAD_LIBRARY_CVS=... MUPAD_DOC_CVS=...

Commiting the package to the MuPAD standard packages CVS repository:
--------------------------------------------------------------------

Be really sure that you know what you are doing!

You need to have a developers login on the MuPAD CVS server. The
variable MUPAD_CVS_LOGIN in the main Makefile.am specifies your
developers login on the MuPAD CVS server. You can also specify it on
the command line.

	make update-mupad-cvs-package MUPAD_CVS_LOGIN=nthiery


==============================================================================
Notes for developers:
=====================

This section has moved to the Wiki:

http://mupad-combinat.sourceforge.net/Wiki/index.php/ProgrammingTipsAndTricks
