diff options
author | Picca Frédéric-Emmanuel <picca@synchrotron-soleil.fr> | 2017-08-18 14:48:52 +0200 |
---|---|---|
committer | Picca Frédéric-Emmanuel <picca@synchrotron-soleil.fr> | 2017-08-18 14:48:52 +0200 |
commit | f7bdc2acff3c13a6d632c28c4569690ab106eed7 (patch) | |
tree | 9d67cdb7152ee4e711379e03fe0546c7c3b97303 /doc/source/install.rst |
Import Upstream version 0.5.0+dfsg
Diffstat (limited to 'doc/source/install.rst')
-rw-r--r-- | doc/source/install.rst | 306 |
1 files changed, 306 insertions, 0 deletions
diff --git a/doc/source/install.rst b/doc/source/install.rst new file mode 100644 index 0000000..1bf5b9d --- /dev/null +++ b/doc/source/install.rst @@ -0,0 +1,306 @@ + +Installation steps +================== + +*silx* supports `Python <https://www.python.org/>`_ versions 2.7, 3.4 and 3.5. + +To install *silx* on Windows, read the `Windows instructions`_. + +To install *silx* on Linux, read the `Linux instructions`_. + +To install *silx* on MacOS, read the `MacOS instructions`_. + +You will find the simple instructions for each platform at the beginning of each section, followed by more detailed instructions concerning dependencies and alternative installation methods. + +For all platform, to install *silx* from the source, see `Installing from source`_. + +To install *silx* in a virtualenv, read :ref:`silx-venv`. + +Dependencies +------------ + +The only mandatory dependency of *silx* is `numpy <http://www.numpy.org/>`_. + +Yet, a set of `Optional dependencies`_ is necessary to enable all *silx* features. + +Optional dependencies ++++++++++++++++++++++ + +The GUI widgets depend on the following extra packages: + +* A Qt binding: either `PyQt5, PyQt4 <https://riverbankcomputing.com/software/pyqt/intro>`_ or `PySide <https://pypi.python.org/pypi/PySide/>`_ +* `matplotlib <http://matplotlib.org/>`_ +* `PyOpenGL <http://pyopengl.sourceforge.net/>`_ +* `IPython <https://ipython.org/>`_ and `qt_console <https://pypi.python.org/pypi/qtconsole>`_ for the ``silx.gui.console`` widget. + +Tools for reading and writing files depend on the following packages: + +* `h5py <http://docs.h5py.org/en/latest/build.html>`_ for HDF5 files +* `fabio <https://github.com/silx-kit/fabio>`_ for multiple image formats + +*silx.opencl* and *silx.image.sift* further depends on OpenCL and the following packages to : + +* `pyopencl <https://mathema.tician.de/software/pyopencl/>`_ +* `Mako <http://www.makotemplates.org/>`_ + +Build dependencies +++++++++++++++++++ + +In addition to run-time dependencies, building *silx* requires a C/C++ compiler, `numpy <http://www.numpy.org/>`_ and `cython <http://cython.org>`_ (optional). + +On Windows it is recommended to use Python 3.5, because with previous versions of Python, it might be difficult to compile the extensions. + +This project uses cython to generate C files. +Cython is not mandatory to build *silx* and is only needed when developing binary modules. +If using cython, *silx* requires at least version 0.18 (with memory-view support). + + +Linux instructions +------------------ + +If NumPy is not installed on your system, you need to install it first +either with the package manager of your system (recommended way) or with pip:: + + pip install numpy --user + +On Linux, you can install *silx* in your home directory:: + + pip install silx --user + +.. note:: + + Replace the ``pip`` command with ``pip3`` to install *silx* or any other library for Python 3. + +.. note:: + + This installs *silx* without the optional dependencies. + +To install *silx* on Debian 8, see `Installing a Debian package`_. +This method requires **sudo** privileges, but has the benefit of installing dependencies in a simple way. + +CentOS 7 rpm packages are provided by Max IV at the following url: http://pubrepo.maxiv.lu.se/rpm/el7/x86_64/ + +Fedora 23 rpm packages are provided by Max IV at http://pubrepo.maxiv.lu.se/rpm/fc23/x86_64/ + +An Arch Linux (AUR) package is also available: https://aur.archlinux.org/packages/python-silx + +You can also choose to compile and install *silx* from it's sources: +see `Installing from source`_. + + + +Installing a Debian package ++++++++++++++++++++++++++++ + +Debian 8 (Jessie) packages are available on http://www.silx.org/pub/debian/ for amd64 computers. +To install it, you need to download this file:: + + http://www.silx.org/pub/debian/silx.list + +and copy it into the /etc/apt/source.list.d folder. +Then run ``apt-get update`` and ``apt-get install python-silx`` + +:: + + wget http://www.silx.org/pub/debian/silx.list + sudo cp silx.list /etc/apt/sources.list.d + sudo apt-get update + sudo apt-get install python-silx python3-silx + +.. note:: + + The packages are built automatically, hence not signed. + You have to accept the installation of non-signed packages. + +If the packages are not installed, it might be due to the priority list. +You can display the priority list using `apt-cache policy python-silx`. +If the Pin-number of silx.org is too low compared to other sources: +download http://www.silx.org/pub/debian/silx.pref into /etc/apt/preferences.d +and start the update/install procedure again. + + +Windows instructions +-------------------- + +The simple way of installing the *silx* library on Windows is to type following +commands in a command prompt:: + + pip install silx + +.. note:: + + This installs *silx* without the optional dependencies. + Instructions on how to install dependencies are given in the + `Installing dependencies`_ section. + +This assumes you have Python and pip installed and configured. If you don't, +read the following sections. + + +Installing Python ++++++++++++++++++ + +Download and install Python from `python.org <https://www.python.org/downloads/>`_. + +We recommend that you install the 64bits version of Python, which is not the default version suggested on the Python website. The 32bits version is limited to 2 GB of memory, and also we don't provide a silx wheel for it. This means that you would have to install silx from its sources, which requires you to install a C compiler first. + +We also encourage you to use Python 3.5 or newer. + +Configure Python as explained on `docs.python.org +<https://docs.python.org/3/using/windows.html#configuring-python>`_ to add +the python installation directory to your PATH environment variable. + +Alternative Scientific Python stacks exists, such as `WinPython <http://winpython.github.io/>`_. +They all offer most of the scientific packages already installed which makes the installation of dependencies much easier. + +Installing pip +++++++++++++++ + +Recent version of Python (`> 2.7.9` or `> 3.4`) provide pip by default. + +If you have an older version of Python and you do not wish to upgrade it, +you can install pip yourself. + +Download the script https://bootstrap.pypa.io/get-pip.py and execute it in a +command prompt:: + + python get-pip.py + + +Using pip ++++++++++ + +Configure your PATH environment variable to include the pip installation +directory, the same way as described for Python. + +The pip installation directory will likely be ``C:\Python35\Scripts\``. + +Then you will be able to use all pip commands listed in following in a command +prompt. + + +Installing dependencies ++++++++++++++++++++++++ + +Some of the dependencies may be simply installed with pip:: + + pip install numpy + pip install matplotlib + pip install PyOpenGL + pip install PyQt5 + pip install PySide + +Regarding the `h5py` and `PyQt4` modules, you can find the wheels at +Christoph Gohlke's repository: + +http://www.lfd.uci.edu/~gohlke/pythonlibs/ + +Download the appropriate `.whl` file for your system and install them with pip:: + + pip install h5py*.whl + pip install PyQt4*.whl + +`PyQt5` can be downloaded as a binary package for `Python 3.5` on the +`Riverbank Computing website <https://www.riverbankcomputing.com/software/pyqt/download5>`_. +This package contains everything needed for `PyQt5`, including `Qt`. + + +Installing *silx* ++++++++++++++++++ + +Provided numpy is installed, you can install *silx* with:: + + pip install silx + + +MacOS instructions +------------------ + +The easy way to install *silx* on MacOS, is:: + + pip install silx + +This should work without issues, as binary wheels of *silx* are provided on +PyPi. + +Wheels are available for *h5py* on MacOS, so you can install it with:: + + pip install h5py + +If at the time of your installation a new version of *h5py* has been released but +the corresponding MacOS wheel is not ready, you should install the latest version including +a wheel: ``pip install h5py==2.6.0`` + +A PyQt5 wheel is now available for Python 3.5 on MacOS: https://pypi.python.org/simple/pyqt5/. +Download it and install it with:: + + pip install PyQt5-5.6-cp35-cp35m-macosx_10_6_intel.whl + +This should work for all versions of MacOS from 10.6. + + +Installing from source +---------------------- + +Building *silx* from the source requires some `Build dependencies`_. + +Building from source +++++++++++++++++++++ + +Source package of *silx* releases can be downloaded from `the pypi project page <https://pypi.python.org/pypi/silx>`_. + +After downloading the `silx-x.y.z.tar.gz` archive, extract its content:: + + tar xzvf silx-x.y.z.tar.gz + +Alternatively, you can get the latest source code from the master branch of the `git repository <https://github.com/silx-kit/silx>`_: https://github.com/silx-kit/silx/archive/master.zip + +You can now build and install *silx* from its sources:: + + cd silx-x.y.z + pip uninstall -y silx + pip install . [--user] + +Known issues +............ + +There are specific issues related to MacOSX. If you get this error:: + + UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 1335: ordinal not in range(128) + +This is related to the two environment variable LC_ALL and LANG not defined (or wrongly defined to UTF-8). +To set the environment variable, type on the command line:: + + export LC_ALL=en_US.UTF-8 + export LANG=en_US.UTF-8 + +Advanced build options +++++++++++++++++++++++ + +In case you want more control over the build procedure, the build command is:: + + python setup.py build + +After this build, you will still need to install *silx* to be able to use it:: + + python setup.py install [--user] + +There are few advanced options to ``setup.py build``: + +* ``--no-cython``: Prevent Cython (even if installed) to re-generate the C source code. + Use the one provided by the development team. +* ``--no-openmp``: Recompiles the Cython code without OpenMP support (default for MacOSX). +* ``--openmp``: Recompiles the Cython code with OpenMP support (default for Windows and Linux). + +To build the documentation (this requires `Sphinx <http://www.sphinx-doc.org/>`_), run:: + + python setup.py build build_doc + + +Testing ++++++++ + +To run the tests of an installed version of *silx*, from the python interpreter, run: + +>>> import silx.test +>>> silx.test.run_tests() |