Commits

Daniel Holth  committed a160305

update docs

  • Participants
  • Parent commits ebd7bcd

Comments (0)

Files changed (2)

 final locations) at any later time.
 
 The wheel project provides a `bdist_wheel` command for setuptools
-(requires distribute >= 0.6.34). Wheel files can be
-installed with a newer `pip` from https://github.com/pypa/pip
-or with wheel's own command line utility.
+(requires setuptools >= 0.8.0). Wheel files can be installed with a
+newer `pip` from https://github.com/pypa/pip or with wheel's own command
+line utility.
 
-The wheel documentation is at http://wheel.rtfd.org/. The
-file format is documented in PEP 427
-(http://www.python.org/dev/peps/pep-0427/).
+The wheel documentation is at http://wheel.rtfd.org/. The file format
+is documented in PEP 427 (http://www.python.org/dev/peps/pep-0427/).
 
 The reference implementation is at http://bitbucket.org/dholth/wheel/
 
 Why not egg?
 ------------
 
-Python's egg format predates the packaging related standards we have today,
-the most important being PEP 376 "Database of Installed Python Distributions"
-which specifies the .dist-info directory (instead of .egg-info) and PEP 345 
-"Metadata for Python Software Packages 1.2" which specifies how to express
-dependencies (instead of requires.txt in .egg-info).
+Python's egg format predates the packaging related standards we have
+today, the most important being PEP 376 "Database of Installed Python
+Distributions" which specifies the .dist-info directory (instead of
+.egg-info) and PEP 426 "Metadata for Python Software Packages 2.0"
+which specifies how to express dependencies (instead of requires.txt
+in .egg-info).
 
 Wheel implements these things. It also provides a richer file naming
-convention that communicates the Python implementation and ABI as well as
-simply the language version used in a particular package.
+convention that communicates the Python implementation and ABI as well
+as simply the language version used in a particular package.
 
-Unlike .egg, wheel will be a fully-documented standard at the binary level
-that is truly easy to install even if you do not want to use the reference
-implementation.
+Unlike .egg, wheel will be a fully-documented standard at the binary
+level that is truly easy to install even if you do not want to use the
+reference implementation.
 

File docs/index.rst

 The current version of wheel can be used to speed up repeated
 installations by reducing the number of times you have to compile your
 software. When you are creating a virtualenv for each revision of your
-software, the savings can be dramatic. This example packages pyramid
+software the savings can be dramatic. This example packages pyramid
 and all its dependencies as wheels, and then installs pyramid from the
 built packages::
 
-        # Install a version of pip that supports wheel
-        pip install -e git+https://github.com/pypa/pip#egg=pip
+        # Make sure you have the latest pip that supports wheel
+        pip install --upgrade pip
+
         # Install wheel
         pip install wheel
 
 For lxml, an up to 3-minute "search for the newest version and compile"
 can become a less-than-1 second "unpack from wheel".
 
+As a side effect the wheel directory, "/tmp/wheelhouse" in the example,
+contains installable copies of the exact versions of your application's
+dependencies. the dependencies.  By installing from those cached wheels
+you can recreate that environment quickly and with no surprises.
+
 To build an individual wheel, run ``python setup.py bdist_wheel``.  Note that
 ``bdist_wheel`` only works with distribute (``import setuptools``); plain
 ``distutils`` does not support pluggable commands like ``bdist_wheel``.  On
 
 Wheel's builtin utility can be invoked directly from wheel's own wheel::
 
-    $ python wheel-0.14.0-py2.py3-none-any.whl/wheel -h
-    usage: wheel [-h] {keygen,sign,verify,unpack,install,convert,help} ...
+    $ python wheel-0.21.0-py2.py3-none-any.whl/wheel -h
+    usage: wheel [-h]
+                 
+                 {keygen,sign,unsign,verify,unpack,install,install-scripts,convert,help}
+                 ...
 
     positional arguments:
-      {keygen,sign,verify,unpack,install,convert,help}
+      {keygen,sign,unsign,verify,unpack,install,install-scripts,convert,help}
                             commands
         keygen              Generate signing key
         sign                Sign wheel
-        unsign              Remove signature from wheel
-        verify              Verify signed wheel
+        unsign              Remove RECORD.jws from a wheel by truncating the zip
+                            file. RECORD.jws must be at the end of the archive.
+                            The zip file must be an ordinary archive, with the
+                            compressed files and the directory in the same order,
+                            and without any non-zip content after the truncation
+                            point.
+        verify              Verify a wheel. The signature will be verified for
+                            internal consistency ONLY and printed. Wheel's own
+                            unpack/install commands verify the manifest against
+                            the signature and file contents.
         unpack              Unpack wheel
         install             Install wheels
+        install-scripts     Install console_scripts
         convert             Convert egg or wininst to wheel
         help                Show this help
 
     optional arguments:
       -h, --help            show this help message and exit
 
+Setuptools scripts handling
+---------------------------
+
+Setuptools' popular `console_scripts` and `gui_scripts` entry points can
+be used to generate platform-specific scripts wrappers.  Most usefully
+these wrappers include `.exe` launchers if they are generated on a
+Windows machine.
+
+By default `bdist_wheel` puts pre-generated versions of these wrappers
+into the `*.data/scripts/` directory of the archive.  This means a
+Windows user may have trouble running scripts from a wheel generated
+on Unix and vice-versa.  As of version 0.21.0 `python setup.py
+bdist_wheel --skip-scripts` is available to create wheels that do not
+contain the setuptools script wrappers. The wheel tool `python -m wheel
+install-scripts packagename` calls setuptools to write the appropriate
+scripts wrappers after an install.
 
 Automatically sign wheel files
 ------------------------------