Files changed (5)
+ `USE variables in Gentoo emerge <http://www.gentoo.org/proj/en/devrel/handbook/handbook.xml?part=2&chap=1#doc_chap2_sect5>`_ ). Repositories of shrinkwrapped packages are easy to make with the
-Shrinkwrap provides tools to create Python package wrappers around non-Python software, and to install such software in a Pythonic way.
+Shrinkwrap provides tools to create lightweight Python package wrappers around non-Python software, and to install such software from project-specific repositories using virtualenv and pip.
-Shrinkwrapped packages can be uploaded to a Python package index, facilitating project-specific repositories that leverage familiar tools such as pip and virtualenv.
+A shrinkwrap package is a minimal python package that downloads, compiles and installs software to the virtualenv base directory. The shrinkwrap package behaves just like a regular python package, so both shrinkwrap and non-shrinkwrap packages can be dependencies of each other. We find that this greatly simplifies deployment of Python packages that depend on compiled libraries *without* requiring the use of system-wide packaging tools, like apt or yum. Shrinkwrap is **not** an API wrapper generator like `SWIG <http://www.swig.org/>`_, but does make it easier to install C libraries into a virtualenv before installing a separate Python wrapper around its API.
+.. note:: To avoid cluttering PyPI with non-Python software, please do not ever upload shrinkwrap-generated packages there! Hosting shrinkwrap packages yourself is easy, and described further in :ref:`running_package_index`.
Shrinkwrap is `available on PyPI <http://pypi.python.org/pypi/shrinkwrap/0.7>`_ and can be installed via ``pip install shrinkwrap``, ``easy_install shrinkwrap``, or by downloading the package and installing with ``python setup.py install``.
For those interested in the newest features should use the development version of shrinkwrap, `available on bitbucket <https://bitbucket.org/seibert/shrinkwrap>`_::
A shrinkwrap package may either use a built-in installer function (for common installation methods) or define a custom one.
-An installer for software using autoconf is available to simplify things. For example, to package `curl`, one may write the following (as, e.g. `curl-7.27.0.py`)::
-Here, the ``shrinkwrap_installer`` argument to ``setup()`` is set to our own installer function. The installer uses two shrinkwrap-provided convenience functions, ``download_and_unpack_tarball`` and ``make`` to download, untar, and compile the bzip2 library. By passing extra options to make, the software is installed into the root of the active virtualenv.
+Here, the ``shrinkwrap_installer`` argument to ``setup()`` is set to our own installer function. The installer uses two shrinkwrap-provided convenience functions, ``download_and_unpack_tarball`` and ``make`` to download, untar, and compile the bzip2 library. See :ref:`shrinkwrap_install_api` for a complete list of convenice functions. By passing extra options to make, the software is installed into the root of the active virtualenv.
.. note:: For several examples of custom installers, see `https://bitbucket.org/seibert/shrinkwrap_pkgs <https://bitbucket.org/seibert/shrinkwrap_pkgs>`_.
Examples include getting code from version control, installing with cmake, and customizing install paths.
+package, so if your library uses `SCons <http://www.scons.org/>`_ as the build system, you can list it in the ``shrinkwrap_requires`` field::
+`the package file for CERN's ROOT library <https://bitbucket.org/seibert/shrinkwrap_pkgs/src/127a74fa3a17/root.py#cl-31>`_
-To share shrinkwrap packages via a package index like PyPI, you must create distribution tarballs. Shrinkwrap includes a tool to create these automatically from wrapper packages::
-This will create a tarball suitable for uploading. Wildcards are valid, for tarring up many packages at once.
-If you wish to serve your own package index, use the ``-p`` option to place output tarballs into one properly-formatted directory::
-Simply serve the `packages` directory on the web, and pip clients can interact with it just like PyPI::
+* Automated testing suite. Due to the nature of shrinkwrap, this will require the testing framework to repeatedly create and destroy entire virtualenvs for each test, which requires some non-trivial infrastructure coding.
+* An interface for shrinkwrap packages to test and report whether the wrapped software is already installed system-wide. This would allow a shrinkwrap package to optionally skip a lengthy compile and install step when the appropriate system packages are already present.