Changes between Initial Version and Version 1 of PreAndPostInstallUtilities


Ignore:
Timestamp:
May 16, 2016, 3:37:47 PM (3 years ago)
Author:
flip
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • PreAndPostInstallUtilities

    v1 v1  
     1= Pre- and Post-Install Utilities =
     2
     3This document describes
     4[source:/trunk/vespa/check_dependencies.py Vespa's dependency checker],
     5the [source:/trunk/vespa/requirements.txt requirements.txt file] that it uses,
     6and the pre-install utility.
     7
     8These utilities are primarily intended for end users, but they can also
     9be useful to Vespa developers when troubleshooting a user's Vespa installation.
     10
     11== The Pre-Install Utility ==
     12
     13The pre-install utility was written to address one of the most common problems
     14for people installing Vespa. Users would often have multiple Pythons installed
     15and somehow install Vespa's dependencies to one Python and Vespa to another,
     16with the result that Vespa would report to the user that its dependencies
     17were not installed.
     18
     19The pre-install utility ensures that a desirable Python is first in the
     20user's PATH during installation. (See the code for details -- it's
     21well-documented.) As long as users follow the admonition to run all the
     22install commands in the terminal window where the pre-install utility ran,
     23they should get their dependencies and Vespa installed to the correct Python
     24100% of the time.
     25
     26[source:/trunk/vespa/create_shortcuts.py Vespa's shortcut creator] creates
     27shortcuts that contain absolute paths the Python executable (rather than
     28just `python`), so once Vespa is installed it's insulated from PATH changes.
     29
     30== The Post-Install Utility (Dependency Checker) ==
     31
     32Once Vespa's installation is complete, the dependency checker can ensure that
     33things look the way they're supposed to.
     34
     35The dependency checker relies on `requirements.txt`. That's a valid
     36[https://pip.pypa.io/en/stable/user_guide/#requirements-files pip requirements file],
     37although due to our complicated dependencies we can't actually use it as such.
     38
     39I wrote it in the hopes that we would be able to install all of Vespa's
     40dependencies like so --
     41{{{
     42pip install -r requirements.txt
     43}}}
     44
     45I learned that we can't, due to various quirks. (`numpy` & `scipy` aren't pip-installable
     46on Windows, PyWavelets isn't pip-installable on OS X and Linux, wxPython isn't
     47pip-installable anywhere, etc.) We can hope that someday all our dreams
     48will come true, but in the meantime we're stuck with a grimy reality that could
     49use a bath.
     50
     51Nevertheless, `requirements.txt` is a good place to describe Vespa's dependencies
     52for two reasons. First of all, it positions Vespa well for a future where
     53we ''can'' use it the way it was meant to be used. Second, it leverages the predefined
     54[https://pip.pypa.io/en/stable/reference/pip_install/#requirements-file-format requirements.txt syntax]
     55and the [https://pypi.python.org/pypi/packaging PyPI module for parsing that syntax].
     56
     57
     58
     59
     60
     61
     62
     63