Installation guide
==================
 
Requirements
------------

Synopsis uses features found in Python 2.2 and up.
It requires relatively recent versions of the Boost libraries, as well
as LLVM (trunk).
The build system requires a posix environment with GNU make and GNU
autoconf installed.
However, it is possible to build Synopsis for a native windows
platform, running with the win32 python installation and emulating
a MSVC compiler.

Configuring
-----------

* If the sources are checked out from svn, run './autogen.sh' to generate
  the configure scripts. This step requires autoconf to be installed.

* Run 'python setup.py config' to configure the subprojects 
  (see 'python setup.py config --help' for available options).

* Be careful to pass the same '--prefix' option you are going to pass
  to the 'install' command, if you plan to install synopsis. See
  the section about installing for details.

Building
--------

* Run 'python setup.py build' to compile everything.
  This will place all files that are going to be installed under build/
  This step requires GNU make to be installed. If the executable 'make'
  is not GNU make, you have to set the 'MAKE' environment variable to
  GNU make.

  If you do not want to install, but rather try synopsis out from within the
  source directory, you may consider 'python setup.py build_ext --inplace'
  as an alternative, which will only compile the C/C++ extensions and put
  them right into the source tree.

  If you have checked out the source code from the repository, you will
  find a 'setup.cfg' file containing convenient default parameters during
  development. However, if you plan to install synopsis, you have to remove
  (or at least rename) this file or else distutils will get confused and
  not install extensions.

* To build for windows native, just use the appropriate python interpreter
  to run the build script. You will need a mingw-compatible version of the
  python library (libpythonxx.a), which you have to build first. Instructions
  for this are at http://www.python.org/doc/current/inst/index.html.

Testing
-------

* The tests require version 2.2 of qmtest (http://www.qmtest.com),
  as well as tidy (http://www.w3.org/People/Raggett/tidy/)

* run 'python setup.py test [--suite=<id>]' where the optional
  argument --suite specifies a test suite to run. The default
  is to run all tests.

Building documentation
----------------------

* 'python setup.py build_doc' will compile printable and html versions of
  the Tutorial as well as the Manual, and put them under share/doc/Synopsis

* All four targets require xsltproc, and the printable Tutorial requires
  additionally fop (from http://xml.apache.org)

* If you only want to build the html versions, run 
  'python setup.py build_doc --html'

* If you only want the Tutorial, run 'python setup.py build_doc --tutorial'

* etc.

Installing
----------

* To install synopsis in <prefix>, run 'python setup.py install --prefix=<prefix>'
  The default prefix is the one from the python interpreter used during the build.
  If you chose a different prefix, make sure to set the PYTHONPATH appropriately
  so the package can be found by the python interpreter.

* If documentation was built before, it will be installed into 
  <prefix>/share/doc/Synopsis

Using Synopsis
--------------

* Remember to set the PYTHONPATH variable if necessary.

* Read the tutorial to learn how to get started using synopsis.

Reporting Bugs
--------------

Please report bugs to http://synopsis.fresco.org/issues