Restore README.md, rename the old README as INSTALL

1 files changed, 253 insertions, 0 deletions

diff --git a/INSTALL b/INSTALL
new file mode 100644
index 0000000..f44b410
--- /dev/null
+++ b/INSTALL
@@ -0,0 +1,253 @@
+====================
+MySQLdb Installation
+====================
+
+.. contents::
+..
+
+Prerequisites
+-------------
+
++ Python 2.3.4 or higher
+
+  * http://www.python.org/
+
+  * Versions lower than 2.3 WON'T WORK.
+
+  * 2.4 is the primary test environment.
+
+  * Red Hat Linux:
+
+    - Make sure you have the Python development headers and libraries
+      (python-devel).
+
++ setuptools
+
+  * http://pypi.python.org/pypi/setuptools
+
++ MySQL 3.23.32 or higher
+
+  * http://www.mysql.com/downloads/
+
+  * Versions lower than 3.22 definitely WON'T WORK.
+
+  * Versions lower than 3.22.19 might not work.
+
+  * MySQL-3.22 might work but isn't supported anymore. It's very old.
+
+  * MySQL-3.23 ought to work, but it's pretty elderly.
+
+  * MySQL-4.0 is supported, but not tested and slightly discouraged.
+
+  * MySQL-4.1 is supported. The prepared statements API is not
+    supported, and won't be until MySQLdb-1.3 or 2.0, if ever.
+
+  * MySQL-5.0 is supported and tested, including stored procedures.
+
+  * MySQL-5.1 is supported (currently a release candidate) but untested.
+    It should work.
+
+  * MySQL-6.0 is sorta-kinda-supported (currently alpha) but untested.
+    It should work.
+
+  * Drizzle <https://launchpad.net/drizzle> is a fork of MySQL. So far
+    the C API looks really similar except everything is renamed.
+    Drizzle support probably won't happen in 1.2. There may be have to
+    be an entirely different module, but still using DB-API.
+
+  * MaxDB, formerly known as SAP DB (and maybe Adabas D?), is a
+    completely different animal. Use the sapdb.sql module that comes
+    with MaxDB.
+
+  * Red Hat Linux packages:
+
+    - mysql-devel to compile
+
+    - mysql and/or mysql-devel to run
+
+  * MySQL.com RPM packages:
+
+    - MySQL-devel to compile
+
+    - MySQL-shared if you want to use their shared
+      library. Otherwise you'll get a statically-linked module,
+      which may or may not be what you want.
+
+    - MySQL-shared to run if you compiled with MySQL-shared installed
+
+  * Transactions (particularly InnoDB tables) are supported for
+    MySQL-3.23 and up. You may need a special package from your vendor
+    with this support turned on.
+
++  zlib
+
+   * Required for MySQL-3.23 and newer.
+
+   * Red Hat Linux
+
+     - zlib-devel to compile
+
+     - zlib to run
+
++ openssl
+
+  * May be needed for MySQL-4.0 or newer, depending on compilation
+    options. If you need it, you probably already have it.
+
+    - you may need openssl-devel on some platforms
+
++ C compiler
+
+  * Most free software-based systems already have this, usually gcc.
+
+  * Most commercial UNIX platforms also come with a C compiler, or
+    you can also use gcc.
+
+  * If you have some Windows flavor, you usually have to pay extra
+    for this, or you can use Cygwin_.
+
+.. _Cygwin: http://www.cygwin.com/
+
+
+Building and installing
+-----------------------
+
+The setup.py script uses mysql_config to find all compiler and linker
+options, and should work as is on any POSIX-like platform, so long as
+mysql_config is in your path.
+
+Depending on which version of MySQL you have, you may have the option
+of using three different client libraries. To select the client library,
+edit the [options] section of site.cfg:
+
+    embedded
+        use embedded server library (libmysqld) if True; otherwise use
+	one of the client libraries (default).
+
+    threadsafe
+        thread-safe client library (libmysqlclient_r) if True (default);
+	otherwise use non-thread-safe (libmysqlclient). You should
+	always use the thread-safe library if you have the option;
+	otherwise you *may* have problems.
+
+    static
+        if True, try to link against a static library; otherwise link
+	against dynamic libraries (default). You may need static linking
+	to use the embedded server.
+
+
+Finally, putting it together::
+
+  $ tar xfz MySQL-python-1.2.1.tar.gz
+  $ cd MySQL-python-1.2.1
+  $ # edit site.cfg if necessary
+  $ python setup.py build
+  $ sudo python setup.py install # or su first
+
+
+Windows
+.......
+
+I don't do Windows. However if someone provides me with a package for
+Windows, I'll make it available. Don't ask me for help with Windows
+because I can't help you.
+
+Generally, though, running setup.py is similar to above::
+
+  C:\...> python setup.py install
+  C:\...> python setup.py bdist_wininst
+
+The latter example should build a Windows installer package, if you
+have the correct tools. In any event, you *must* have a C compiler.
+Additionally, you have to set an environment variable (mysqlroot)
+which is the path to your MySQL installation. In theory, it would be
+possible to get this information out of the registry, but like I said,
+I don't do Windows, but I'll accept a patch that does this.
+
+On Windows, you will definitely have to edit site.cfg since there is
+no mysql_config in the MySQL package.
+
+
+Zope
+....
+
+If you are using a binary package of Zope, you need run setup.py with
+the python executable that came with Zope. Otherwise, you'll install
+into the wrong Python tree and Zope (ZMySQLDA) will not be able to
+find _mysql.
+
+
+Binary Packages
+---------------
+
+I don't plan to make binary packages any more. However, if someone
+contributes one, I will make it available. Several OS vendors have
+their own packages available.
+
+
+RPMs
+....
+
+If you prefer to install RPMs, you can use the bdist_rpm command with
+setup.py. This only builds the RPM; it does not install it. You may
+want to use the --python=XXX option, where XXX is the name of the
+Python executable, i.e. python, python2, python2.4; the default is
+python. Using this will incorporate the Python executable name into
+the package name for the RPM so you have install the package multiple
+times if you need to support more than one version of Python. You can
+also set this in setup.cfg.
+
+
+Red Hat Linux
+.............
+
+MySQL-python is pre-packaged in Red Hat Linux 7.x and newer. This
+includes Fedora Core and Red Hat Enterprise Linux. You can also
+build your own RPM packages as described above.
+
+
+Debian GNU/Linux
+................
+
+Packaged as `python-mysqldb`_::
+
+	# apt-get install python-mysqldb
+
+Or use Synaptic.
+
+.. _`python-mysqldb`: http://packages.debian.org/python-mysqldb
+
+
+Ubuntu
+......
+
+Same as with Debian.
+
+
+Gentoo Linux
+............
+
+Packaged as `mysql-python`_. ::
+
+      # emerge sync
+      # emerge mysql-python
+      # emerge zmysqlda # if you use Zope
+
+.. _`mysql-python`: http://packages.gentoo.org/search/?sstring=mysql-python
+
+
+BSD
+...
+
+MySQL-python is a ported package in FreeBSD, NetBSD, and OpenBSD,
+although the name may vary to match OS conventions.
+
+
+License
+-------
+
+GPL or the original license based on Python 1.5.2's license.
+
+
+:Author: Andy Dustman <andy@dustman.net>
+:Revision: $Id$