Merge pull request #158 from p-push/install-instructions

Updated installation instructions

5 files changed, 44 insertions, 91 deletions

diff --git a/INSTALL b/INSTALL.rst
index 4440e7a..f96fa55 100644
--- a/INSTALL
+++ b/INSTALL.rst
@@ -1,3 +1,6 @@
+PycURL Installation
+===================
+
 NOTE: You need Python and libcurl installed on your system to use or
 build pycurl.  Some RPM distributions of curl/libcurl do not include
 everything necessary to build pycurl, in which case you need to
@@ -7,7 +10,7 @@ install the developer specific RPM which is usually called curl-dev.
 Distutils
 ---------
 
-Build and install pycurl with the following commands:
+Build and install pycurl with the following commands::
 
     (if necessary, become root)
     tar -zxvf pycurl-$VER.tar.gz
@@ -19,8 +22,8 @@ $VER should be substituted with the pycurl version number, e.g. 7.10.5.
 Note that the installation script assumes that 'curl-config' can be
 located in your path setting.  If curl-config is installed outside
 your path or you want to force installation to use a particular
-version of curl-config, use the '--curl-config' commandline option to
-specify the location of curl-config.  Example:
+version of curl-config, use the '--curl-config' command line option to
+specify the location of curl-config.  Example::
 
     python setup.py install --curl-config=/usr/local/bin/curl-config
 
@@ -29,37 +32,44 @@ LD_LIBRARY_PATH environment variable accordingly.  This normally
 applies only if there is more than one version of libcurl installed,
 e.g. one in /usr/lib and one in /usr/local/lib.
 
+PycURL requires that the SSL library that it is built against is the same
+one libcurl, and therefore PycURL, uses at runtime. PycURL's ``setup.py``
+uses ``curl-config`` to attempt to figure out which SSL library libcurl
+was compiled against, however this does not always work. If PycURL is unable
+to determine the SSL library in use it will print a warning similar to
+the following::
+
+    src/pycurl.c:137:4: warning: #warning "libcurl was compiled with SSL support, but configure could not determine which " "library was used; thus no SSL crypto locking callbacks will be set, which may " "cause random crashes on SSL requests" [-Wcpp]
+
+It will then fail at runtime as follows::
+
+    ImportError: pycurl: libcurl link-time ssl backend (openssl) is different from compile-time ssl backend (none/other)
+
+To fix this, you need to tell ``setup.py`` what SSL backend is used::
+
+    python setup.py --with-[ssl|gnutls|nss] install
+
 
 easy_install / pip
-----------------
+------------------
+
+::
 
     easy_install pycurl
     pip install pycurl
 
 If you need to specify an alternate curl-config, it can be done via an
-environment variable:
+environment variable::
 
     export PYCURL_CURL_CONFIG=/usr/local/bin/curl-config
     easy_install pycurl
 
 The same applies to the SSL backend, if you need to specify it (see the SSL
-section below):
+note above)::
 
-    export PYCURL_SSL_LIBRARY=openssl
+    export PYCURL_SSL_LIBRARY=[openssl|gnutls|nss]
     easy_install pycurl
 
-
-SSL
----
-
-PycURL has locks around crypto functions. In order to compile correct locking
-code, it has to know which SSL library is going to be used by libcurl at
-runtime. setup.py will attempt to automatically detect the SSL library that
-libcurl uses, but this does not always work. In the cases when setup.py cannot
-figure out the SSL library, it must be provided via --with-ssl/--with-gnutls/
---with-nss arguments, just like libcurl's configure script uses, or via
-PYCURL_SSL_LIBRARY=openssl|gnutls|nss environment variable.
-
 Please note the difference in spelling that concerns OpenSSL: the command-line
 argument is --with-ssl, to match libcurl, but the environment variable value is
 "openssl".
@@ -73,22 +83,21 @@ or source packages that you are going to compile yourself.
 
 For a minimum build you will just need libcurl source. Follow its Windows
 build instructions to build either a static or a DLL version of the library,
-then configure PycURL as follows to use it:
+then configure PycURL as follows to use it::
 
     python setup.py --curl-dir=c:\dev\curl-7.33.0\builds\libcurl-vc-x86-release-dll-ipv6-sspi-spnego-winssl --use-libcurl-dll
 
-Note that --curl-dir does not point to libcurl source but rather to headers
+Note that ``--curl-dir`` does not point to libcurl source but rather to headers
 and compiled libraries.
 
 Additional Windows setup.py options:
 
---use-libcurl-dll - build against libcurl DLL, if not given PycURL will be built
-against libcurl statically.
-
---libcurl-lib-name=libcurl_imp.lib - specify a different name for libcurl
-import library. The default is libcurl.lib which is appropriate for static
-linking and is sometimes the correct choice for dynamic linking as well. The
-other possibility for dynamic linking is libcurl_imp.lib.
+- ``--use-libcurl-dll`` - build against libcurl DLL, if not given PycURL will
+  be built against libcurl statically.
+- ``--libcurl-lib-name=libcurl_imp.lib`` - specify a different name for libcurl
+  import library. The default is ``libcurl.lib`` which is appropriate for
+  static linking and is sometimes the correct choice for dynamic linking as
+  well. The other possibility for dynamic linking is ``libcurl_imp.lib``.
 
-A good setup.py target to use is bdist_wininst which produces an executable
-installer that you can run to install PycURL.
+A good ``setup.py`` target to use is ``bdist_wininst`` which produces an
+executable installer that you can run to install PycURL.
diff --git a/MANIFEST.in b/MANIFEST.in
index d2ddfac..648421f 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -6,7 +6,7 @@
 include COPYING-LGPL
 include COPYING-MIT
 include ChangeLog
-include INSTALL
+include INSTALL.rst
 include MANIFEST.in
 include Makefile
 include README.rst
diff --git a/README.rst b/README.rst
index 679a58a..1f9dd50 100644
--- a/README.rst
+++ b/README.rst
@@ -46,63 +46,7 @@ Requirements
 Installation
 ------------
 
-You can install the most recent PycURL version using `easy_install`_::
-
-    easy_install pycurl
-
-or `pip`_::
-
-    pip install pycurl
-
-Installing from source is performed via ``setup.py``::
-
-    python setup.py install
-
-You will need libcurl headers and libraries installed to install PycURL
-from source. PycURL uses ``curl-config`` to determine correct flags/libraries
-to use during compilation; you can override the location of ``curl-config``
-if it is not in PATH or you want to use a custom libcurl installation::
-
-    python setup.py --curl-config=/path/to/curl-config install
-
-Sometimes it is more convenient to use an environment variable, if
-you are not directly invoking ``setup.py``::
-
-    PYCURL_CURL_CONFIG=/path/to/curl-config python setup.py install
-
-``curl-config`` is expected to support the following options:
-
-- ``--version``
-- ``--cflags``
-- ``--libs``
-- ``--static-libs`` (if ``--libs`` does not work)
-
-PycURL requires that the SSL library that it is built against is the same
-one libcurl, and therefore PycURL, uses at runtime. PycURL's ``setup.py``
-uses ``curl-config`` to attempt to figure out which SSL library libcurl
-was compiled against, however this does not always work. If PycURL is unable
-to determine the SSL library in use it will print a warning similar to
-the following::
-
-    src/pycurl.c:137:4: warning: #warning "libcurl was compiled with SSL support, but configure could not determine which " "library was used; thus no SSL crypto locking callbacks will be set, which may " "cause random crashes on SSL requests" [-Wcpp]
-
-It will then fail at runtime as follows::
-
-    ImportError: pycurl: libcurl link-time ssl backend (openssl) is different from compile-time ssl backend (none/other)
-
-To fix this, you need to tell ``setup.py`` what SSL backend is used::
-
-    python setup.py --with-[ssl|gnutls|nss] install
-
-Or use an environment variable::
-
-    PYCURL_SSL_LIBRARY=openssl|gnutls|nss python setup.py install
-
-Note the difference between ``--with-ssl`` (for compatibility with libcurl) and
-``PYCURL_SSL_LIBRARY=openssl``.
-
-.. _easy_install: http://peak.telecommunity.com/DevCenter/EasyInstall
-.. _pip: http://pypi.python.org/pypi/pip
+Please see README.rst for installation instructions.
 
 Support
 -------
diff --git a/setup.py b/setup.py
index 8979df2..da627ae 100644
--- a/setup.py
+++ b/setup.py
@@ -380,7 +380,7 @@ def get_data_files():
     else:
         datadir = os.path.join("share", "doc", PACKAGE)
     #
-    files = ["ChangeLog", "COPYING-LGPL", "COPYING-MIT", "INSTALL", "README.rst"]
+    files = ["ChangeLog", "COPYING-LGPL", "COPYING-MIT", "INSTALL.rst", "README.rst"]
     if files:
         data_files.append((os.path.join(datadir), files))
     files = glob.glob(os.path.join("doc", "*.rst"))
diff --git a/tests/ftp_test.py b/tests/ftp_test.py
index a88fc44..5a4d8e8 100644
--- a/tests/ftp_test.py
+++ b/tests/ftp_test.py
@@ -27,7 +27,7 @@ class FtpTest(unittest.TestCase):
         
         result = sio.getvalue().decode()
         assert 'README.rst' in result
-        assert 'INSTALL' in result
+        assert 'INSTALL.rst' in result
     
     # XXX this test needs to be fixed
     def test_quote(self):
@@ -50,4 +50,4 @@ class FtpTest(unittest.TestCase):
         
         result = sio.getvalue().decode()
         assert 'README.rst' in result
-        assert 'INSTALL' in result
+        assert 'INSTALL.rst' in result