Veusz Installation
==================

1. INSTALLING FROM SOURCE
*************************

Veusz uses distutils for its installation. See below for how to use it.

Requirements:
 python2 >= 2.6 or python3 >= 3.3
                 http://www.python.org/
 PyQt >= 4.6     http://www.riverbankcomputing.co.uk/software/pyqt/
 numpy >= 1.0    http://numpy.scipy.org/

PyQt requires
 Qt4 >= 4.7      http://www.trolltech.com/products/qt/ (free version)
                 latest version recommended
 SIP >= 4.12     http://www.riverbankcomputing.co.uk/software/sip/

Optional requirements:
 h5py            http://www.h5py.org/
 Astropy >= 0.2  http://www.astropy.org
 pyemf >= 2.0.0  http://pyemf.sourceforge.net/
 PyMinuit        http://code.google.com/p/pyminuit/
 dbus-python     http://dbus.freedesktop.org/doc/dbus-python/

Python 3 support is included in veusz-1.19+, although it has less
testing than Python 2 support. Note that the source code is compatible
with both python versions and does not need translation with 2to3. The
optional dependency pyemf does not have Python 3 support.

1.1 Full installation with distutils
====================================
There are a number of ways to install programs using distutils. I will
list a few of the possible method here:

To install on linux to the standard location on the hard disk

# cd veusz-1.23.2
# python setup.py build
# su
[enter root password]
# python setup.py install 
# exit

If you do not have a root account (as is default on Ubuntu), do
# sudo python setup.py install
instead of the final three lines

On Windows, it should just be a matter of running the python setup.py
build and install steps with the requirements installed.

1.1.1 Testing
=============
After veusz has been installed into the Python path (in the standard
location or in PYTHONPATH), you can run the runselftest.py executable
in the tests directory (note that resources may need to be specified:
see below). This will compare the generated output of example
documents with the expected output. The return code of the
runselftest.py script is the number of tests that have failed (0 for
success).

On Unix/Linux, Qt requires the DISPLAY environment to be set to an X11
server for the self test to run. Packagers can use Xvfb in a non
graphical environment to create a hidden X11 server:

# xvfb-run -a --server-args "-screen 0 640x480x24" \
    python tests/runselftest.py

1.1.2 Separate resources directory
==================================
By default, setup.py installs certain resource files (VERSION, icons,
ui, and examples) in the veusz python module directory. This may not
be desired behaviour for unix packagers, for example, who want to
separate the code from the data files.

It is possible to install these files in a different location by using
the setup.py option "--veusz-resource-dir" (for example with
/usr/share/veusz). If you do this, then you need to tell veusz where
these resources are on runtime or when testing. This can be done by
using a symlink "resources" in the the veusz module directory which
points to the location of these files and directories. Alternatively,
the environment variable VEUSZ_RESOURCE_DIR can be set.

There is an addition setup.py option "--disable-install-examples"
which disables installation of the example files. This may be helpful
for packagers who want to place the example files in
/usr/share/doc. As veusz shows these files on the help menu and when
testing, it is suggested that an "examples" symlink is added to the
resources directory to point to the location of the example files.

1.3 Running in-place
====================
If you don't want to install veusz fully or are doing development, it
can currently be run from its own directory. Do

# tar xzf veusz-1.23.2.tar.gz                [change version here]
# cd veusz-1.23.2
# ./run_veusz_inplace

Certain features will be disabled if you do this. You will not be able
to do contour plotting. Plotting will be much slower and export file
sizes can be larger. It is therefore recommended to build the binary
modules and copy them to the correct location:

# python setup.py build
# cp build/*/veusz/helpers/*.so veusz/helpers/

2. BINARY INSTALL
*****************

2.1 Linux binary
================
If your distribution does not include an up to date package, you can
use the Linux binary instead (for i386/x86_64). Note that this may not
work on all distributions due to glibc/library
incompatibilities. Simply unpack the tar file and run the main
executable:

# tar xzf veusz-linux-i386-1.23.2.tar.gz     [change version here]
# cd veusz-linux-i386-1.23.2
# ./veusz

2.2 Installing in Windows
=========================
Simply run the setup.exe binary installer. Add the location of the
embed.py file to your PYTHONPATH if you want to use the embedding
module.

2.3 Installing on Mac OS X
==========================
A binary is available for Mac OS X. Simply drag the Veusz application
into your Applications directory.

3. NOTES FOR PACKAGERS
**********************
- It is recommended to run the self test above (if possible)

- Please see the above section on separate resource files which shows
  how to easily separate the installation of the code and data files
  (resources).

- Veusz is mostly platform-independent python code and data files with
  a separate "helpers" module containing platform-dependent code. It
  may save space in repositories to separate out the helpers
  sub-module.

- Veusz includes man pages in Documents/veusz.1 Documents/veusz_listen.1
  These are not automatically installed by distutils.

- Veusz also includes freedesktop mime, desktop and appdata files in
  the support subdirectory which can be installed to better integrate
  with desktop environments.

- Icons are also included in the icons directory with the names
  veusz_16.png, _32, _48, _64 and _128. A scalable icon can be found
  in veusz.svg.
