diff --git a/docs/reference/pip_install.rst b/docs/reference/pip_install.rst index fb389f5b9..2e672ea68 100644 --- a/docs/reference/pip_install.rst +++ b/docs/reference/pip_install.rst @@ -339,6 +339,46 @@ To have the dependency located from a local directory and not crawl PyPI, add th find_links = file:///path/to/local/archives +Build System Interface +++++++++++++++++++++++ + +In order for pip to install a package from source, ``setup.py`` must implement +the following commands:: + + setup.py egg_info [--egg-base XXX] + setup.py install --record XXX [--single-version-externally-managed] [--root XXX] [--compile|--no-compile] [--install-headers XXX] + +The ``egg_info`` command should create egg metadata for the package, as +described in the setuptools documentation at +http://pythonhosted.org/setuptools/setuptools.html#egg-info-create-egg-metadata-and-set-build-tags + +The ``install`` command should implement the complete process of installing the +package to the target directory XXX. + +To install a package in "editable" mode (``pip install -e``), ``setup.py`` must +implement the following command:: + + setup.py develop --no-deps + +This should implement the complete process of installing the package in +"editable" mode. + +One further ``setup.py`` command is invoked by ``pip install``:: + + setup.py clean + +This command is invoked to clean up temporary commands from the build. (TODO: +Investigate in more detail when this command is required). + +No other build system commands are invoked by the ``pip install`` command. + +Installing a package from a wheel does not invoke the build system at all. + +.. _PyPI: http://pypi.python.org/pypi/ +.. _setuptools extras: http://packages.python.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies + + + .. _`pip install Options`: Options @@ -436,40 +476,3 @@ Examples $ pip install --pre SomePackage -Build System Interface -********************** - -In order for pip to install a package from source, ``setup.py`` must implement -the following commands:: - - setup.py egg_info [--egg-base XXX] - setup.py install --record XXX [--single-version-externally-managed] [--root XXX] [--compile|--no-compile] [--install-headers XXX] - -The ``egg_info`` command should create egg metadata for the package, as -described in the setuptools documentation at -http://pythonhosted.org/setuptools/setuptools.html#egg-info-create-egg-metadata-and-set-build-tags - -The ``install`` command should implement the complete process of installing the -package to the target directory XXX. - -To install a package in "editable" mode (``pip install -e``), ``setup.py`` must -implement the following command:: - - setup.py develop --no-deps - -This should implement the complete process of installing the package in -"editable" mode. - -One further ``setup.py`` command is invoked by ``pip install``:: - - setup.py clean - -This command is invoked to clean up temporary commands from the build. (TODO: -Investigate in more detail when this command is required). - -No other build system commands are invoked by the ``pip install`` command. - -Installing a package from a wheel does not invoke the build system at all. - -.. _PyPI: http://pypi.python.org/pypi/ -.. _setuptools extras: http://packages.python.org/setuptools/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies diff --git a/docs/reference/pip_wheel.rst b/docs/reference/pip_wheel.rst index 5e99e4cd4..2559fd6fc 100644 --- a/docs/reference/pip_wheel.rst +++ b/docs/reference/pip_wheel.rst @@ -18,27 +18,8 @@ Description .. pip-command-description:: wheel -Options -******* - -.. pip-command-options:: wheel - -.. pip-index-options:: - - -Examples -******** - -1. Build wheels for a requirement (and all its dependencies), and then install - - :: - - $ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage - $ pip install --no-index --find-links=/tmp/wheelhouse SomePackage - - Build System Interface -********************** +++++++++++++++++++++++ In order for pip to build a wheel, ``setup.py`` must implement the ``bdist_wheel`` command with the following syntax:: @@ -70,3 +51,25 @@ which passes a preprocessor symbol to the extension build. Such usage is considered highly build-system specific and more an accident of the current implementation than a supported interface. + + + +Options +******* + +.. pip-command-options:: wheel + +.. pip-index-options:: + + +Examples +******** + +1. Build wheels for a requirement (and all its dependencies), and then install + + :: + + $ pip wheel --wheel-dir=/tmp/wheelhouse SomePackage + $ pip install --no-index --find-links=/tmp/wheelhouse SomePackage + +