Updated build/install/release docs.

Author: behackett

RELEASE.rst

@@ -4,34 +4,31 @@ Some notes on PyMongo releases
 Versioning
 ----------
 
-We shoot for a release every month or so - that will generally just
-increment the middle version number (e.g. 1.6.1 -> 1.7). We're
-getting to the point where a 2.0 release would be reasonable, though -
-a lot has changed since 1.0.
+We shoot for a release every few months - that will generally just
+increment the middle version number (e.g. 2.1.1 -> 2.2).
 
 Minor releases are reserved for bug fixes (in general no new features
 or deprecations) - they only happen in cases where there is a critical
 bug in a recently released version, or when a release has no new
 features or API changes.
 
 In between releases we use a "+" version number to denote the version
-under development. So if we just released 1.6, then the current dev
-version would be 1.6+. When we make the next release (1.6.1 or 1.7) we
-replace all instances of 1.6+ in the docs with the new version number.
+under development. So if we just released 2.1, then the current dev
+version would be 2.1+. When we make the next release (2.1.1 or 2.2) we
+replace all instances of 2.1+ in the docs with the new version number.
 
 Deprecation
 -----------
 
-Changes should be backwards compatible unless absolutely
-necessary. When making API changes the approach is generally to add a
-deprecation warning but keeping the existing API
-functional. Eventually (after at least ~4 releases) we can remove the
-old API.
+Changes should be backwards compatible unless absolutely necessary. When making
+API changes the approach is generally to add a deprecation warning but keeping
+the existing API functional. Eventually (after at least ~4 releases) we can
+remove the old API.
 
 Doing a Release
 ---------------
 
-1. Test release on Python 2.4-2.7 on Windows, Linux and OSX, with and without the C extension. Generally enough to just run the tests on 2.4 and 2.7 with and without the extension on a single platform, and then just test any version on the other platforms as a sanity check. `python setup.py test` will build the extension and test. `python tools/clean.py` will remove the extension, and then `nosetests` will run the tests without it. Can also run the doctests: `python setup.py doc -t`. For building extensions on Windows check section below.
+1. Test release on Python 2.4-2.7 and 3.1-3.2 on Windows, Linux and OSX, with and without the C extension. Generally enough to just run the tests on 2.4, 2.7 and 3.2 with and without the extension on a single platform, and then just test any version on the other platforms as a sanity check. `python setup.py test` will build the extension and test. `python tools/clean.py` will remove the extension, and then `nosetests` will run the tests without it. Can also run the doctests: `python setup.py doc -t`. For building extensions on Windows check section below.
 
 2. Add release notes to doc/changelog.rst. Generally just summarize/clarify the git log, but might add some more long form notes for big changes.
 
@@ -55,12 +52,3 @@ Doing a Release
 
 12. Announce!
 
-Building extensions on Windows
-------------------------------
-Currently the default `python setup.py test` builds extensions on Windows 32 bit only. The default option requires Visual Studio (C++ Express) 2008 and works with Python 2.6 and 2.7. The tests can be run in Python 2.4 and 2.5 by installing MingW32 and running the appropriate command in step 3 below.
-
-1. On your Windows 32 bit machine install Microsoft Visual C++ 2008 Express Edition (or equivalent 2008 edition) in the default location. For Python 2.4 or 2.5 install MingW32 in it's default location.
-
-2. Ensure you have nose installed.
-
-3. Run `\path\to\Python2(6|7) setup.py test` or `\path\to\Python2(4|5) setup.py build -c mingw32 test` to build the C extensions and run pymongo tests.

doc/installation.rst

@@ -21,7 +21,7 @@ to install pymongo on platforms other than Windows::
 
 To get a specific version of pymongo::
 
-  $ pip install pymongo==1.10.1
+  $ pip install pymongo==2.1.1
 
 To upgrade using pip::
 
@@ -39,26 +39,46 @@ To upgrade do::
 
   $ easy_install -U pymongo
 
-Mac OS Snow Leopard Issues
---------------------------
+Dependencies for installing C Extensions on Unix
+------------------------------------------------
 
-By default OSX uses `/usr/bin/easy_install` for third party package installs.
-In OSX 10.6.x this script is hardcoded to use a version of setuptools that is
-older than the version required by PyMongo for python2.7 support. You can work
-around it like this::
+10gen does not provide statically linked binary packages for Unix flavors
+other than OSX. To build the optional C extensions you must have the GNU C
+compiler (gcc) installed. Depending on your flavor of Unix (or Linux
+distribution) you may also need a python development package that provides
+the necessary header files for your version of Python. The package name may
+vary from distro to distro.
 
-  $ easy_install -U setuptools
-  $ python -m easy_install pymongo
+Debian and Ubuntu users should issue the following command::
 
-To upgrade do::
+  $ sudo apt-get install build-essential python-dev
+
+RedHat, CentOS, and Fedora users should issue the following command::
+
+  $ sudo yum install gcc python-devel
+
+OSX
+---
+
+10gen provides pre-built egg packages for Apple provided Python versions on
+Snow Leopard (2.5, 2.6) and Lion (2.5, 2.6, 2.7). If you want to install
+PyMongo for other Python versions you may have to install the following to
+build the C extensions:
+
+**Snow Leopard** - Xcode 3 with 'UNIX Development Support'.
 
-  $ python -m easy_install -U pymongo
+**Lion** - As of the release of PyMongo 2.2 **Xcode 4.1** is required with
+'UNIX Development Support'. See the following for more information:
+
+http://bugs.python.org/issue13590
+
+http://mail.python.org/pipermail/python-dev/2012-February/116210.html
 
 **Snow Leopard Xcode 4 Users**: The Python versions shipped with OSX 10.6.x
 are universal binaries. They support i386, PPC, and (in the case of python2.6)
 x86_64. Since Xcode 4 removed support for PPC the distutils version shipped
 with Apple's builds of Python will fail to build the C extensions if you have
-Xcode 4 installed. This issue may also affect some builds of Python downloaded
+Xcode 4 installed. This issue may also affect builds of Python downloaded
 from python.org. There is a workaround::
 
   # For Apple-supplied Python2.6 (installed at /usr/bin/python2.6)
@@ -71,37 +91,53 @@ from python.org. There is a workaround::
 See `http://bugs.python.org/issue11623 <http://bugs.python.org/issue11623>`_
 for a more detailed explanation.
 
-Install from source
--------------------
+Installing from source
+----------------------
 
 If you'd rather install directly from the source (i.e. to stay on the
-bleeding edge), check out the latest source from github and install
-the driver from the resulting tree::
+bleeding edge), install the C extension dependencies then check out the
+latest source from github and install the driver from the resulting tree::
 
   $ git clone git://github.com/mongodb/mongo-python-driver.git pymongo
   $ cd pymongo/
   $ python setup.py install
 
-Dependencies for installing C Extensions on Unix
-------------------------------------------------
 
-10gen does not currently provide statically linked binary packages for
-Unix flavors other than OSX. To build the optional C extensions you must
-have the GNU C compiler (gcc) installed. Depending on your flavor of Unix
-(or Linux distribution) you may also need a python development package that
-provides the necessary header files for your version of Python. The package
-name may vary from distro to distro. Here are some examples for popular
-Linux distributions:
+Installing from source on Windows
+.................................
+
+.. note::
+
+  10gen provides pre-built exe installers for 32-bit and 64-bit Windows. We
+  recommend that users install those packages (`available from pypi
+  <http://pypi.python.org/pypi/pymongo/>`_).
 
-- RHEL (Red Hat Enterprise Linux)/CentOS: python-devel
-- Debian/Ubuntu: python-dev
+If you want to install PyMongo with C extensions from source the following
+directions apply to both CPython and ActiveState's ActivePython:
 
-Pre-built eggs are available for OSX Snow Leopard on PyPI.
+64-bit Windows
+~~~~~~~~~~~~~~
+
+Install Visual Studio 2008. You must use the full version as Visual C++ 2008
+Express does not provide 64-bit compilers. Make sure that you check the
+"x64 Compilers and Tools" option under Visual C++.
+
+32-bit Windows
+~~~~~~~~~~~~~~
+
+For Python 2.6 and newer install Visual C++ 2008 Express SP1.
+
+For Python 2.4 or 2.5 you must install
+`MingW32 <http://www.mingw.org/wiki/InstallationHOWTOforMinGW>`_ then run the
+following command to install::
+
+  python setup.py build -c mingw32 install
 
 .. _install-no-c:
 
 Installing Without C Extensions
 -------------------------------
+
 By default, the driver attempts to build and install optional C
 extensions (used for increasing performance) when it is installed. If
 any extension fails to build the driver will be installed anyway but a
@@ -113,3 +149,31 @@ build properly. This can be done using a command line option to
 *setup.py*::
 
   $ python setup.py --no_ext install
+
+Building PyMongo egg Packages
+-----------------------------
+
+Some organizations do not allow compilers and other build tools on production
+systems. To install PyMongo on these systems with C extensions you may need to
+build custom egg packages. Make sure that you have installed the dependencies
+listed above for your operating system then run the following command in the
+PyMongo source directory::
+
+  $ python setup.py bdist_egg
+
+The egg package can be found in the dist/ subdirectory. The file name will
+resemble “pymongo-2.2-py2.7-linux-x86_64.egg” but may have a different name
+depending on your platform and the version of python you use to compile.
+
+.. warning::
+
+  These “binary distributions,” will only work on systems that resemble the
+  environment on which you built the package. In other words, ensure that
+  operating systems and versions of Python and architecture (i.e. “32” or “64”
+  bit) match.
+
+Copy this file to the target system and issue the following command to install the
+package::
+
+  $ sudo easy_install pymongo-2.2-py2.7-linux-x86_64.egg
+

setup.py

@@ -125,21 +125,25 @@ class custom_build_ext(build_ext):
     """
 
     warning_message = """
-**************************************************************
+********************************************************************
 WARNING: %s could not
 be compiled. No C extensions are essential for PyMongo to run,
 although they do result in significant speed improvements.
 
 If you are seeing this message on Linux you probably need to
 install GCC and/or the Python development package for your
-version of Python. Python development package names for popular
-Linux distributions include:
+version of Python.
 
-RHEL/CentOS: python-devel
-Debian/Ubuntu: python-dev
+Debian and Ubuntu users should issue the following command:
+
+    $ sudo apt-get install build-essential python-dev
+
+RedHat, CentOS, and Fedora users should issue the following command:
+
+    $ sudo yum install gcc python-devel
 
 %s
-**************************************************************
+********************************************************************
 """
 
     def run(self):