We wish to completely automate installation of OpenVisualizer. The work in SW-98 provides a standardized setup.py-based install for OpenVisualizer itself. However, we must extend this standardization to OpenVisualizer's requirementsdependencies. The pip installer provides this capability dependency management for Python-based modules, and this page documents how we intend to use pip to implement pip per SW-74.

However, as As we show below, pip itself usually is not sufficient for a completely automated installation. However, it provides a level of automation that is good enough for our present purposes.

In addition, core Python recently has decided to adopt pip as the primary installation mechanism for modules. So, we plan to use the setuptools module, on which pip is based, for the standard tree-based install. This approach provides for a simpler installation in the common case, and we can use pip to install OpenVisualizer itself. At the same time, we plan to retain use of the distutils module for native OS installation, which setuptools does not support.

Required Modules

The OpenVisualizer Confluence page lists the required modules. Some modules are Python based, and some are not. This section provides a detailed review.

...

There is a similar setup.py extension, python-innosetup, for InnoSetup.

Combined Setup and Requirements via pip

If we don't use a traditional installer program, it is possible to install OpenVisualizer and its requirements via pip with a command like this:

   > pip install openVisualizer

This approach requires that we import setuptools rather than distutils for setup.py. setuptools provides the 'install_requires' argument that allows retrieval of requirements from Pypi. setuptools has some drawbacks, particularly the inability to install to arbitrary locations, which is required for the native install mechanism in SW-98.

Research on this topic showed that Python's package installation tools are still under development. A recent LWN article, Rationalizing Python packaging, describes the current roadmap.

Implementation Plan

We plan to use a distutils-based setup, with the option to use pip to install requirements. Outline:

1. User downloads OpenVisualizer sdist archive, either from the Confluence wiki or from Pypi.
2. User extracts the archive.
3. User installs OpenVisualizer via setup.py:
      > python setup.py install 
4. User installs pip and setuptools if necessary.
5. User installs Python requirements via pip and a requirements file provided in the archive:
      > pip install -r requirements.pip

We do not plan to pursue use of an installer a few reasonsa separate installer, for the reasons below:

• An installer seems well suited to an end-user GUI application. It would be more appropriate once we have a desktop Web UI, particularly for simulation.
• Our users are pretty technical, and the requirement to install PyWin32 and TAP is not onerous.
• I have never used these installers, and don't know how much work is required. In contrast, we already have created the source distribution via setup.py, and addition of the pip requirements file is small and simple.

Given the state of Python package installation tools, we likely will get to a desktop UI installer, but not just yet. It's a process. 

Better install/requirements documentation

...

Distutils vs. Setuptools+pip

If we don't use a traditional installer program, we must rely on Python's installation tools. Historically the distutils module provided this capability; however, core Python is switching to use of pip and the setuptools module upon which it is based for Python 3.4. A recent LWN article, Rationalizing Python packaging, describes the roadmap. Also see the Python Packaging User Guide as the definitive resource on the subject.

Use of pip and setuptools means that if they are installed, the user may install OpenVisualizer and its Python dependencies with a single command, either pip-based or setup.py-based. Eventually, pip and setuptools will be included with Python, so the user will not be required to install them manually.

Also, we can use setuptools to read the existing 'requirements.pip' file to determine the modules dependencies to install.

However, setuptools does not support installation to arbitrary directories, which is useful for native setup, particularly for embedded Linux use. For example, Debian uses distutils to generate its Python module packages. Therefore, we plan to retain use of distutils for nativeSetup.py.

Installation

For a setuptools/pip installation, the user follows these steps:

1. User reads Confluence instructions for installation.
2. If necessary, user installs pip and setuptools.
3. User chooses pip-based install or downloads the OpenVisualizer sdist source archive.

For pip install, user enters:
    > pip install openVisualizer

For setup.py install, user performs these steps:

1. Downloads the OpenVisualizer sdist archive, either from the Confluence wiki or Pypi.
2. Extracts the archive.
3. Enters:
      > python setup.py install

Better install/requirements documentation

• A separate page for this documentation is worthwhilemay be worthwhile to remove the clutter of the dependencies table on the main page.
• The table of requirements should be segmented into runtime vs. development, where development includes SCons, yappi, etc. Alternatively, we may wish to create a separate development page for OpenVisualizer to house these requirements.

Other topics

Reuse requirements.pip

We plan to add any necessary required Python modules to the existing, top-level requirements.pip. This file can be copied to the software/openvisualizer directory for archive creation.

Support for upgrades

Installation pip supports package upgrades. See the usage page. In contrast, installation via setup.py does not support upgrades. Depending on the changes in the upgrade, the user may be required to manually uninstall the current version. However, pip does support package upgrades. See the usage page.