Document the library updates, and call special attention to the changes in the...

Document the library updates, and call special attention to the changes in the c-ares configure script that can break on some CFLAGS/LDFLAGS configurations. [skip ci]

changelog.rst

@@ -12,8 +12,8 @@ Unreleased
   Carlos Sanchez.
 - PyPy: Fix a ``DistutilsModuleError`` or ``ImportError`` if the CFFI
   module backing ``gevent.core`` needs to be compiled when the hub is
-  initialized. Now, the module will be compiled when gevent is
-  imported. Reported in :issue:`619` by Thinh Nguyen with
+  initialized. Now, the module will be automtically compiled when
+  gevent is imported. Reported in :issue:`619` by Thinh Nguyen with
   contributions by Jay Oster and Matt Dupre.
 
 .. _future: http://python-future.org
@@ -192,6 +192,12 @@ Unreleased
   that this changes the (platform dependent) default, typically from
   buffered to unbuffered. See :pr:`542` by Romuald Brunet.
 - Upgraded c-ares to 1.10.0. See :pr:`579` by Omer Katz.
+
+  .. caution:: The c-ares ``configure`` script is now more strict about the
+               contents of environment variables such as ``CFLAGS`` and ``LDFLAGS``
+               and they may have to be modified (for example, ``CFLAGS`` is no
+               longer allowed to include ``-I`` directives, which must instead be
+               placed in ``CPPFLAGS``).
 - Add a ``count`` argument to ``gevent.greenlet.wait``. See :pr:`482` by
   wiggin15.
 - Add a ``timeout`` argument to ``gevent.queue.JoinableQueue.wait``

doc/mytheme/static/basic.css_t

@@ -887,6 +887,18 @@ div.warning {
     border: 1px solid #f66;
 }
 
+
+div.caution {
+    background-color: #fff6f1;
+    border: 1px solid #ffaaa3;
+}
+
+div.hint, div.tip {
+    border-left-style: solid;
+    border-left-width: 2px;
+    border-left-color: #B7D897;
+}
+
 p.admonition-title {
     display: inline;
 }

doc/whatsnew_1_1.rst

@@ -111,6 +111,27 @@ include:
   another (e.g., :meth:`Greenlet.get <gevent.Greenlet.get>`),
   the original traceback is preserved and raised.
 
+Library Updates
+===============
+
+The two C libraries that are bundled with gevent have been updated.
+libev has been updated from 4.19 to 4.20 (`libev release notes`_) and
+c-ares has been updated from 1.9.1 to 1.10.0 (`c-ares release notes`_).
+
+.. caution:: The c-ares ``configure`` script is now *much* stricter
+             about the contents of compilation environment variables
+             such as ``$CFLAGS`` and ``$LDFLAGS``. For example,
+             ``$CFLAGS`` is no longer allowed to contain ``-I``
+             directives; instead, these must be placed in
+             ``$CPPFLAGS``. That's one common cause of an error
+             like the following when compiling from scratch on a POSIX
+             platform::
+
+                 Running '(cd  "/tmp/easy_install-NT921u/gevent-1.1b2/c-ares"  && if [ -e ares_build.h ]; then cp ares_build.h ares_build.h.orig; fi   && /bin/sh ./configure CONFIG_COMMANDS= CONFIG_FILES=   && cp ares_config.h ares_build.h "$OLDPWD"   && mv ares_build.h.orig ares_build.h) > configure-output.txt' in /tmp/easy_install-NT921u/gevent-1.1b2/build/temp.linux-x86_64-2.7/c-ares
+                 configure: error: Can not continue. Fix errors mentioned immediately above this line.
+
+.. _libev release notes: https://github.com/gevent/gevent/blob/master/libev/Changes#L17
+.. _c-ares release notes: https://raw.githubusercontent.com/bagder/c-ares/cares-1_10_0/RELEASE-NOTES
 
 Compatibility
 =============