Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[MRG] Add better checks to confirm proper installation of ghostscript #196

Merged
merged 2 commits into from
Oct 17, 2020
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Add new checks
  • Loading branch information
vinayak-mehta committed Oct 17, 2020
commit de6faa7af1211a6bd1efc26dcde896d8734420dc
99 changes: 29 additions & 70 deletions docs/user/install-deps.rst
Original file line number Diff line number Diff line change
@@ -3,100 +3,59 @@
Installation of dependencies
============================

The dependencies `Tkinter`_ and `ghostscript`_ can be installed using your system's package manager. You can run one of the following, based on your OS.

.. _Tkinter: https://wiki.python.org/moin/TkInter
.. _ghostscript: https://www.ghostscript.com
The dependencies `Ghostscript <https://www.ghostscript.com>`_ and `Tkinter <https://wiki.python.org/moin/TkInter>`_ can be installed using your system's package manager or by running their installer.

OS-specific instructions
------------------------

For Ubuntu
^^^^^^^^^^
Ubuntu
^^^^^^
::

$ apt install python-tk ghostscript

Or for Python 3::

$ apt install python3-tk ghostscript
$ apt install ghostscript python3-tk

For macOS
^^^^^^^^^
MacOS
^^^^^
::

$ brew install tcl-tk ghostscript

For Windows
^^^^^^^^^^^

For Tkinter, you can download the `ActiveTcl Community Edition`_ from ActiveState. For ghostscript, you can get the installer at the `ghostscript downloads page`_.
$ brew install ghostscript tcl-tk

.. _ActiveTcl Community Edition: https://www.activestate.com/activetcl/downloads
.. _ghostscript downloads page: https://www.ghostscript.com/download/gsdnld.html
.. _as shown here: https://java.com/en/download/help/path.xml
Windows
^^^^^^^

Checks to see if dependencies were installed correctly
------------------------------------------------------
For Ghostscript, you can get the installer at their `downloads page <https://www.ghostscript.com/download/gsdnld.html>`_. And for Tkinter, you can download the `ActiveTcl Community Edition <https://www.activestate.com/activetcl/downloads>`_ from ActiveState.

You can do the following checks to see if the dependencies were installed correctly.
Checks to see if dependencies are installed correctly
-----------------------------------------------------

For Tkinter
^^^^^^^^^^^

Launch Python, and then at the prompt, type::
You can run the following checks to see if the dependencies were installed correctly.

>>> import Tkinter

Or in Python 3::

>>> import tkinter

If you have Tkinter, Python will not print an error message, and if not, you will see an ``ImportError``.

For ghostscript
For Ghostscript
^^^^^^^^^^^^^^^

Run the following to check the ghostscript version.
Open the Python REPL and run the following:

For Ubuntu/macOS::
For Ubuntu/MacOS::

$ gs -version
>>> from ctypes.util import find_library
>>> find_library("gs")
"libgs.so.9"

For Windows::

C:\> gswin64c.exe -version

Or for Windows 32-bit::

C:\> gswin32c.exe -version

If you have ghostscript, you should see the ghostscript version and copyright information.

If you choose not to install ghostscript using the Camelot `OS-specific
instructions`_, there is risk of an incomplete installation (for example,
the choosen distribution only installs the ghostscript ``gs`` binary and not
the libraries).
>>> from ctypes.util import find_library
>>> find_library("".join(("gsdll", str(ctypes.sizeof(ctypes.c_voidp) * 8), ".dll"))
<name-of-ghostscript-library-on-windows>

.. _OS-specific instructions: #os-specific-instructions
**Check:** The output of the ``find_library`` function should not be empty.

If the ghostscript application libraries are not installed correctly, the
attempt to use ``read_pdf`` (using the example on the Camelot home page) will
fail as follows (Traceback truncated - full example stack trace available
`here`_)::
If the output is empty, then it's possible that the Ghostscript library is not available one of the ``LD_LIBRARY_PATH``/``DYLD_LIBRARY_PATH``/``PATH`` variables depending on your operating system. In this case, you may have to modify one of those path variables.

>>> import camelot
>>> tables = camelot.read_pdf('foo.pdf')
OSError: dlopen(libgs.so, 6): image not found

.. _here: https://github.com/camelot-dev/camelot/issues/193

A correct installation of ghostscript will result in the example returning a
TableList object::
For Tkinter
^^^^^^^^^^^

>>> import camelot
>>> tables = camelot.read_pdf('foo.pdf')
>>> tables
<TableList n=1>
Launch Python and then import Tkinter::

>>> import tkinter

**Check:** Importing ``tkinter`` should not raise an import error.
31 changes: 12 additions & 19 deletions docs/user/install.rst
Original file line number Diff line number Diff line change
@@ -5,42 +5,35 @@ Installation of Camelot

This part of the documentation covers the steps to install Camelot.

Using conda
-----------
After :ref:`installing the dependencies <install_deps>`, which include `Ghostscript <https://www.ghostscript.com>`_ and `Tkinter <https://wiki.python.org/moin/TkInter>`_, you can use one of the following methods to install Camelot:

The easiest way to install Camelot is to install it with `conda`_, which is a package manager and environment management system for the `Anaconda`_ distribution.
::

$ conda install -c conda-forge camelot-py
.. warning:: The ``lattice`` flavor will fail to run if Ghostscript is not installed. You may run into errors as shown in `issue #193 <https://github.com/camelot-dev/camelot/issues/193>`_.

.. note:: Camelot is available for Python 2.7, 3.5, 3.6 and 3.7 on Linux, macOS and Windows. For Windows, you will need to install ghostscript which you can get from their `downloads page`_.
pip
---

.. _conda: https://conda.io/docs/
.. _Anaconda: http://docs.continuum.io/anaconda/
.. _downloads page: https://www.ghostscript.com/download/gsdnld.html
.. _conda-forge: https://conda-forge.org/
To install Camelot from PyPI using ``pip``, please include the extra ``cv`` requirement as shown::

Using pip
---------
$ pip install "camelot-py[cv]"

After :ref:`installing the dependencies <install_deps>`, which include `Tkinter`_ and `ghostscript`_, you can simply use pip to install Camelot::
conda
-----

$ pip install "camelot-py[cv]"
`conda`_ is a package manager and environment management system for the `Anaconda <https://anaconda.org>`_ distribution. It can be used to install Camelot from the ``conda-forge`` channel::

.. _Tkinter: https://wiki.python.org/moin/TkInter
.. _ghostscript: https://www.ghostscript.com
$ conda install -c conda-forge camelot-py

From the source code
--------------------

After :ref:`installing the dependencies <install_deps>`, you can install from the source by:
After :ref:`installing the dependencies <install_deps>`, you can install Camelot from source by:

1. Cloning the GitHub repository.
::

$ git clone https://www.github.com/camelot-dev/camelot

2. Then simply using pip again.
2. And then simply using pip again.
::

$ cd camelot