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

Synopsis uses features found in Python 2.2 and up.
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.

* 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.

* Synopsis provides an alternative Cpp parser based on boost.wave.
  It overcomes certain limitations with the old ucpp-based parser, but
  incures a dependency on various boost libraries. Thus it's disabled by default.

  To build with this new Cpp parser, configure with --with-boost, and
  these optional boost-related flags:

  --with-boost-prefix=<boost installation prefix>
  --with-boost-version=<version> (e.g. 1.35)
  --with-boost-lib-suffix=<suffix> (e.g. -gcc41-mt)

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.

* If you want to use an external garbage collector for the Cxx parser
  instead of the built in one, run 
  'python setup.py config --with-gc-prefix=/your/gc/prefix'


* To build within the source tree, it might be best to set up
  a setup.cfg file containing these options::
  
  [build_ext]
  inplace=1
  
  [build_clib]
  build_clib=.

  As a result, libSynopsis.so will be built into lib/, and the
  parser modules will be built right into Synopsis/, so set your
  LD_LIBRARY_PATH and PYTHONPATH variables accordingly.

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

Packaging
---------

Source package:

  * 'python setup.py sdist' creates a source package (compressed tarball).
    For it to include documentation, you need to have run 'python setup.py build_doc'
    first (see above).

Binary packages:

  * 'python setup.py bdist' creates a binary package (compressed tarball).
    Other binary packages may be supported, but may involve more complex setups.

  * rpms: An rpm spec file is provided ('synopsis.spec') which is used to generate
    fedora rpms, and possibly others.

  * windows installer: 'python setup.py bdist_wininst' generates a windows MSI package.

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

* Remember to set the PYTHONPATH variable if necessary, as well as
  LD_LIBRARY_PATH.

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

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

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