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

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

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

Requirements:
 python2 >= 2.7 or python3 >= 3.3
                 https://www.python.org/
 PyQt >= 5.2     https://www.riverbankcomputing.co.uk/software/pyqt/
 numpy >= 1.0    http://www.numpy.org/

PyQt requires
 Qt5 >= 5.5      https://www.qt.io/developers/
                 latest version recommended
 SIP 4.x >= 4.15 https://www.riverbankcomputing.co.uk/software/sip/

Optional requirements:
 h5py            http://www.h5py.org/
 astropy >= 0.4  http://www.astropy.org/
 pyemf >= 2.0.0  http://pyemf.sourceforge.net/
                 (for Python3 see https://github.com/jeremysanders/pyemf)
 iminuit         https://github.com/iminuit/iminuit
 ( or PyMinuit    http://code.google.com/p/pyminuit/ )
 dbus-python     http://dbus.freedesktop.org/doc/dbus-python/
 Ghostscript     https://www.ghostscript.com/ (for EPS/PS output)
 Sphinx          http://www.sphinx-doc.org/en/stable/ (to rebuild manual)

Note that the source code is compatible with both python 2.7+ and
3.3+. It does not need translation with 2to3. The optional dependency
pyemf does not have Python 3 support, but an in-development version of
pyemf for Python 3 can be found at https://github.com/jeremysanders/pyemf.

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 follow
these instructions (note python in these commands should be replaced
by python3 to do a Python 3 installation).

# cd veusz-3.3.1
# 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

Alternatively, the Qt platform can be switched to minimal to avoid the
use of X11:

# QT_QPA_PLATFORM=minimal 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.1.3 SIP parameters
====================

By default the location of the SIP executable, the SIP include file
location and the SIP files are obtained from sipconfig. sipconfig is
now deprecated. If sipconfig is not found, the build will look for the
SIP executable on the current path (as sip/sip5/sip.exe/sip5.exe), the
SIP include file in the Python include directory and the SIP files in
python-prefix/share/sip (excluding share on Windows). If you want to
manually specify these, you can run the Python setup.py build_ext
stage before build, with the parameters:

  --sip-exe=EXE          SIP executable
  --sip-include-dir=DIR  SIP include directory (location of sip.h)
  --sip-dir=DIR          base directory for SIP files

Alternatively, these can be given as environment variables SIP_EXE,
SIP_INCLUDE_DIR and SIP_DIR, respectively. Environment variables have
the advantage that the build_ext stage does not have to be done
separately.

1.1.4 Qt build parameters
=========================

By default, the qmake executable is used to find the locations of the
Qt include and library directories. The build searches for qmake under
the names qmake-qt5, qmake, qmake5.exe and qmake.exe. The location of
qmake and its return values can be overriden with the following
build_ext options:

  --qmake-exe=EXE        qmake exe
  --qt-include-dir=DIR   base Qt include directory
  --qt-library-dir=DIR   Qt library directory

Alternatively, these can be overridden with the enviroment variables
QMAKE_EXE, QT_INCLUDE_DIR and QT_LIBRARY_DIR, respectively.
Environment variables have the advantage that the build_ext stage does
not have to be done separately.

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. Before this can work, the
helper modules must be compiled and copied into the appropriate
location.

# tar xzf veusz-3.3.1.tar.gz                [change version here]
# cd veusz-3.3.1
# python setup.py build                     [or use python3 here]
# cp build/*/veusz/helpers/*.so veusz/helpers/

To run the program run

# python3 ./run_veusz_inplace

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 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 xf veusz-3.3.1-linux-x86_64.tar.xz   [change version here]
# cd veusz-3.3.1-linux-x86_64
# ./veusz.exe                    [note, it's not a windows exe!]

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 MacOS
=======================
A binary is available for MacOS. 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 a man page in Documents/man-page/veusz.1
  This are not automatically installed by distutils.

- A manual in HTML and PDF format can be found in Documents/manual/
  This and the the man page can be regenerated using the Makefile in
  Documents, if Sphinx is installed (make clean; make).

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

- Veusz will periodically (once per week) check for updates. This can
  be disabled by patching veusz/utils/version.py to set
  disableVersionChecks=True.

- Veusz will automatically send anonymous feedback (after
  confirmation) to the developers giving version information and
  counts of feature use. This can be disabled by patching
  veusz/utils/feedback.py to set disableFeedback=True.
