From cebdc9244c019224846cb8d2668080fe386a6adc Mon Sep 17 00:00:00 2001 From: Alexandre Marie Date: Mon, 17 Dec 2018 12:28:24 +0100 Subject: New upstream version 0.9.0+dfsg --- doc/source/install.rst | 267 ++++++++++++++++++++++--------------------------- 1 file changed, 119 insertions(+), 148 deletions(-) (limited to 'doc/source/install.rst') diff --git a/doc/source/install.rst b/doc/source/install.rst index 93b9df0..7941a7b 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -2,38 +2,71 @@ Installation steps ================== -*silx* supports most operating systems, different version of the Python +*silx* supports most operating systems and different versions of the Python programming language. -While `numpy `_ is the only mandatory dependency, -graphical widgets require Qt, management of data files requires -`h5py `_ and -`fabio `_, and high performance data-analysis -code on GPU requires `pyopencl `_. -This table summarized the the support matrix of silx v0.7: +This table summarizes the support matrix of silx: +------------+--------------+---------------------+ | System | Python vers. | Qt and its bindings | +------------+--------------+---------------------+ -| `Windows`_ | 3.5, 3.6 | PyQt5.6+ | +| `Windows`_ | 3.5, 3.6-3.7 | PyQt5.6+, PySide2 | +------------+--------------+---------------------+ -| `MacOS`_ | 2.7, 3.5-3.6 | PyQt5.6+ | +| `MacOS`_ | 2.7, 3.5-3.7 | PyQt5.6+, PySide2 | +------------+--------------+---------------------+ -| `Linux`_ | 2.7, 3.4-3.6 | PyQt4.8+, PyQt5.3+ | +| `Linux`_ | 2.7, 3.4-3.7 | PyQt5.3+, PySide2 | +------------+--------------+---------------------+ -For all platform, you can install *silx* from the source, see `Installing from source`_. +For the description of *silx* dependencies, see the Dependencies_ section. + +For all platforms, you can install *silx* with pip, see `Installing with pip`_. To install *silx* in a `Virtual Environment`_, there is short version here-after -and a `longer description :ref:`silx-venv`. +and a longer description: :ref:`silx-venv`. + +You can also install *silx* from the source, see `Installing from source`_. + + +Installing with pip +------------------- + +To install silx (and all its dependencies_), run: + +.. code-block:: bash + + pip install silx[full] + +To install silx with a minimal set of dependencies, run: + +.. code-block:: bash + + pip install silx + +.. note:: + + Use pip's ``--user`` option to install locally for the current user. + +.. note:: + + - If numpy is not yet installed, you might need to install it first. + - Replace the ``pip`` command with ``pip3`` to install *silx* or any other library for Python 3. + Dependencies ------------ +.. _dependencies: + +The mandatory dependencies are: + +- `numpy `_ +- `h5py `_ +- `fabio `_ + The GUI widgets depend on the following extra packages: -* A Qt binding: either `PyQt5, PyQt4 `_, - `PySide `_, or `PySide2 `_ +* A Qt binding: either `PyQt5 `_, + or `PySide2 `_ * `matplotlib `_ * `PyOpenGL `_ * `qt_console `_ @@ -45,13 +78,13 @@ Tools for reading and writing files depend on the following packages: * `h5py `_ for HDF5 files * `fabio `_ for multiple image formats -*silx.opencl* further depends on OpenCL and the following packages to : +*silx.opencl* further depends on OpenCL and the following packages too : * `pyopencl `_ * `Mako `_ The complete list of dependencies with the minimal version is described in the -`requirement.txt `_ +`requirement.txt `_ at the top level of the source package. Build dependencies @@ -64,63 +97,36 @@ On Windows it is recommended to use Python 3.5, because with previous versions of Python, it might be difficult to compile extensions (i.e. binary modules). This project uses Cython (version > 0.21) to generate C files. -Cython is now mandatory to build *silx* from the development branch and is only -needed when compiling binary modules. +Cython is mandatory to build *silx* from the development branch. The complete list of dependencies for building the package, including its documentation, is described in the -`requirement-dev.txt `_ +`requirement-dev.txt `_ at the top level of the source package. - Linux ----- -If NumPy is not installed on your system, you need to install it first, -preferably with the package manager of your system. -If you cannot use the package manager of your system (which requires the root -access), please refer to the `Virtual Environment`_ procedure. - -On Linux, you can install *silx* in your home directory - -.. code-block:: bash - - 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 or Ubuntu systems, 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 `_ and -`Fedora 23 rpm packages `_ -are provided by the Max IV institute at Lund, Sweden. - -An `Arch Linux (AUR) package `_ -is provided by Leonid Bloch. +Packages are available for a few distributions: -You can also choose to compile and install *silx* from it's sources: -see `Installing from source`_. +- Debian 8: see `Installing a Debian package`_. +- `CentOS 7 RPM packages `_ provided by the Max IV institute at Lund, Sweden. +- `Fedora 23 rpm packages `_ provided by the Max IV institute at Lund, Sweden. +- `Arch Linux (AUR) package `_ provided by Leonid Bloch. -.. note:: +You can also follow one of those installation procedures: - The Debian packages `python-silx` and `python3-silx` will not install executables - (`silx view`, `silx convert` ...). Please install the silx package. +- `Installing with pip`_ +- Installing in a `Virtual Environment`_ +- `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 +To install it, you need to download this file : .. code-block:: bash @@ -136,6 +142,9 @@ Then run ``apt-get update`` and ``apt-get install python-silx`` sudo apt-get update sudo apt-get install python-silx python3-silx silx +The `python-silx` and `python3-silx` packages provide the library, +while the `silx` package provides the executable (`silx view`, `silx convert` ...). + .. note:: The packages are built automatically, hence not signed. @@ -147,88 +156,42 @@ 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. -Virtual Environment -------------------- - -Virtual environments are self-contained directory tree that contains a Python -installation for a particular version of Python, plus a number of additional -packages. -They do require administrator privileges, nor *root* access. - -To create a virtual environment, decide upon a directory where you want to place -it (for example *myenv*), and run the *venv* module as a script with the directory path: - -.. code-block:: bash - - python3 -m venv myenv - -This will create the *myenv* directory if it doesn’t exist, and also create -directories inside it containing a copy of the Python interpreter, the standard -library, and various supporting files. - -Once you’ve created a virtual environment, you may activate it. - -On Windows, run: - -.. code-block:: bash - - myenv\\Scripts\\activate.bat - -On Unix or MacOS, run: - -.. code-block:: bash - - source myenv/bin/activate - -You can install, upgrade, and remove packages using a program called *pip* within -your virtual environment. - -.. code-block:: bash - - pip install numpy - pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements.txt - pip install silx Windows ------- -The simple way of installing the *silx* library on Windows is to type the following -commands in a command prompt: +The simplest way of installing *silx* on Windows is to install it with ``pip``, see `Installing with pip`_:: -.. code-block:: bash + pip install silx[full] - 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. +This assumes you have Python and pip installed and configured. +If you don't, read the following sections. + +Alternatively, you can check: +- Installing in a `Virtual Environment`_ +- `Installing from source`_ Installing Python +++++++++++++++++ Download and install Python from `python.org `_. -We recommend that you install the 64bits version of Python, which is not the +We recommend that you install the 64bit 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 +The 32bit version has limited memory, and also we don't provide a binary 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, former versions are no more +We also encourage you to use Python 3.5 or newer as former versions are no longer officially supported. Configure Python as explained on `docs.python.org `_ to add the python installation directory to your PATH environment variable. -Alternative Scientific Python stacks exists, such as +Alternative Scientific Python stacks exists such as `WinPython `_ or `Anaconda `_. They all offer most of the scientific packages already installed which makes the installation of dependencies much easier. @@ -241,49 +204,63 @@ 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 +Then you will be able to use all the pip commands listed below in a command prompt. -Installing dependencies -+++++++++++++++++++++++ +MacOS +----- -All dependencies may be simply installed with pip:: +While Apple ships Python 2.7 by default on their operating systems, we recommend +using Python 3.5 or newer to ease the installation of the Qt library. -.. code-block:: bash +Then, install *silx* with ``pip``, see `Installing with pip`_:: - pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements.txt + pip install silx[full] +This should work without issues, as binary wheels of *silx* are provided on +PyPi. -Installing *silx* -+++++++++++++++++ -Provided numpy is installed, you can install *silx* with:: +Virtual Environment +------------------- -.. code-block:: bash +Virtual environments are self-contained directory trees that contain a Python +installation for a particular version of Python, plus a number of additional +packages. +They do not require administrator privileges, nor *root* access. - pip install silx +To create a virtual environment, decide upon a directory where you want to place +it (for example *myenv*), and run the *venv* module as a script with the directory path: +.. code-block:: bash -MacOS ------ + python3 -m venv myenv -While Apple ships Python 2.7 by default on their operating systems, we recommand -using Python 3.5 or newer to ease the installation of the Qt library. -This can simply be performed by: +This will create the *myenv* directory if it doesn’t exist, and also create +directories inside it containing a copy of the Python interpreter, the standard +library, and various supporting files. -.. code-block:: bash +Once you’ve created a virtual environment, you may activate it. - pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements.txt +On Windows, run: -Then install *silx* with: +.. code-block:: bash -.. code-block:: bash + myenv\\Scripts\\activate.bat - pip install silx +On Unix or MacOS, run: -This should work without issues, as binary wheels of *silx* are provided on -PyPi. +.. code-block:: bash + + source myenv/bin/activate + +You can install, upgrade, and remove packages using a program called *pip* within +your virtual environment (see `Installing with pip`_). + +.. code-block:: bash + + pip install silx[full] Installing from source @@ -294,7 +271,7 @@ installed using: .. code-block:: bash - pip install -r https://github.com/silx-kit/silx/raw/0.7/requirements-dev.txt + pip install -r https://github.com/silx-kit/silx/raw/0.8/requirements-dev.txt Building from source @@ -326,8 +303,8 @@ 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: +This is related to the two environment variables LC_ALL and LANG not being defined (or wrongly defined to UTF-8). +To set the environment variables, type on the command line: .. code-block:: bash @@ -345,18 +322,12 @@ In case you want more control over the build procedure, the build command is: There are few advanced options to ``setup.py build``: -* ``--no-cython``: Prevent Cython (even if installed) to re-generate the C source code. +* ``--no-cython``: Prevent Cython (even if installed) from re-generating 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). -Run the test suite of silx (may take a couple of minutes): - -.. code-block:: bash - - python run_tests.py - -Package the built into a wheel and install it: +Package the build into a wheel and install it: .. code-block:: bash @@ -373,7 +344,7 @@ To build the documentation, using `Sphinx `_: Testing +++++++ -To run the tests of an installed version of *silx*, from the python interpreter, run: +To run the tests of an installed version of *silx*, run the following on the python interpreter: .. code-block:: python -- cgit v1.2.3