diskimage-builder/diskimage_builder/elements/pip-and-virtualenv
melissaml a6322c6ed0 Replace git.openstack.org URLs with opendev.org URLs
Change-Id: I03e9162d5a59a2aa1631a9ecf6f6833bb7ac6050
2019-05-16 14:45:52 +08:00
..
install.d/pip-and-virtualenv-source-install Fix opensuse 42.3 pip-and-virtualenv 2019-02-25 15:37:17 +11:00
post-install.d Add pip cache cleanup to pip-and-virtualenv 2018-05-09 09:31:17 -07:00
test-elements Fix opensuse 42.3 pip-and-virtualenv 2019-02-25 15:37:17 +11:00
element-deps Remove installed packages before pip install 2018-04-17 16:09:04 +10:00
package-installs.yaml Replace git.openstack.org URLs with opendev.org URLs 2019-05-16 14:45:52 +08:00
pkg-map pip-and-virtualenv: Install python3 on openSUSE 2017-07-04 08:40:34 +01:00
README.rst Revert "Dont install python-pip for py3k" 2018-01-10 15:48:03 +11:00
source-repository-pip-and-virtualenv Move elements & lib relative to diskimage_builder package 2016-11-01 17:27:41 -07:00

==================
pip-and-virtualenv
==================

This element installs pip and virtualenv in the image.

.. note:: This element setups and Python 2 and Python 3 environment.
          This means it will bring in python2 packages, so isn't
          appropriate if you want a python3 only environment.

Package install
===============

If the package installtype is used then these programs are installed
from distribution packages.  In this case, ``pip`` and ``virtualenv``
will be installed *only* for the python version identified by
``dib-python`` (i.e. the default python for the platform).

Distribution packages have worked out name-spacing such that only
python2 or python3 owns common scripts like ``/usr/bin/pip`` (on most
platforms, ``pip`` refers to python2 pip, and ``pip3`` refers to
python3 pip, although some may choose the reverse).

To install pip and virtualenv from package::

  export DIB_INSTALLTYPE_pip_and_virtualenv=package

Source install
==============

Source install is the default.  If the source installtype is used,
``pip`` and ``virtualenv`` are installed from the latest upstream
releases.

Source installs from these tools are not name-spaced.  It is
inconsistent across platforms if the first or last install gets to own
common scripts like ``/usr/bin/pip`` and ``virtualenv``.

To avoid inconsistency, we firstly install the packaged python 2
**and** 3 versions of ``pip`` and ``virtualenv``.  This prevents a
later install of these distribution packages conflicting with the
source install.  We then overwrite ``pip`` and ``virtualenv`` via
``get-pip.py`` and ``pip`` respectively.

The system will be left in the following state:

* ``/usr/bin/pip`` : python2 pip
* ``/usr/bin/pip2`` : python2 pip (same as prior)
* ``/usr/bin/pip3`` : python3 pip
* ``/usr/bin/virtualenv`` : python2 virtualenv

(note python3 ``virtualenv`` script is *not* installed, see below)

Source install is supported on limited platforms.  See the code, but
this includes Ubuntu and RedHat platforms.

Using the tools
===============

Due to the essentially unsolvable problem of "who owns the script", it
is recommended to *not* call ``pip`` or ``virtualenv`` directly.  You
can directly call them with the ``-m`` argument to the python
interpreter you wish to install with.

For example, to create a python3 environment do::

  # python3 -m virtualenv myenv
  # myenv/bin/pip install mytool

To install a python2 tool from pip::

  # python2 -m pip install mytool

In this way, you can always know which interpreter is being used (and
affected by) the call.

Ordering
========
Any element that uses these commands must be designated as
05-* or higher to ensure that they are first installed.