--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/common/tools/lib/DBD/mysql/INSTALL.pod	Tue Jul 13 14:37:59 2010 +0100
@@ -0,0 +1,801 @@
+=head1 NAME
+
+INSTALL - How to install and configure DBD::mysql
+
+
+=head1 SYNOPSIS
+
+  perl Makefile.PL [options]
+  make
+  make test
+  make install
+
+
+=head1 DESCRIPTION
+
+This document describes the installation and configuration of
+DBD::mysql, the Perl DBI driver for the MySQL database. Before
+reading on, make sure that you have the prerequisites available:
+Perl, MySQL and DBI. For details see the separate section.
+L</PREREQUISITES>.
+
+Depending on your version of Perl, it might be possible to
+use a binary distribution of DBD::mysql. If possible, this is
+recommended. Otherwise you need to install from the sources.
+If so, you will definitely need a C compiler. Installation
+from binaries and sources are both described in separate
+sections. L<BINARY INSTALLATION>. L<SOURCE INSTALLATION>.
+
+Finally, if you encounter any problems, do not forget to
+read the section on known problems. L<KNOWN PROBLEMS>. If
+that doesn't help, you should look into the archive of the
+mailing list B<perl@lists.mysql.com>. See
+http://www.mysql.com for archive locations. And if that
+still doesn't help, please post a question on this mailing
+list.
+
+
+=head1 PREREQUISITES
+
+=over
+
+=item Perl
+
+Preferrably a version of Perl, that comes preconfigured with
+your system. For example, all Linux and FreeBSD distributions
+come with Perl. For Windows, ActivePerl is recommended, see
+http://www.activestate.com for details.
+
+=item MySQL
+
+You need not install the actual MySQL database server, the
+client files and the devlopment files are sufficient. For
+example, Fedora Core 4 Linux distribution comes with RPM files
+(using YUM) B<mysql.i386> and B<mysql-server.i386> (use "yum search" 
+to find exact package names). These are sufficient, if the MySQL 
+server is located on a foreign machine.  You may also create client
+files by compiling from the MySQL source distribution and using
+
+  configure --without-server
+
+If you are using Windows and need to compile from sources
+(which is only the case if you are not using ActivePerl),
+then you must ensure that the header and library files are
+installed. This may require choosing a "Custom installation"
+and selecting the appropriate option when running the
+MySQL setup program.
+
+=item DBI
+
+DBD::mysql is a DBI driver, hence you need DBI. It is available
+from the same source where you got the DBD::mysql distribution
+from.
+
+=item C compiler
+
+A C compiler is only required, if you install from source. In
+most cases there are binary distributions of DBD::mysql
+available. However, if you need a C compiler, make sure, that
+it is the same C compiler that was used for compiling Perl and
+MySQL! Otherwise you will almost definitely encounter problems
+because of differences in the underlying C runtime libraries.
+
+In the worst case, this might mean to compile Perl and MySQL
+yourself. But believe me, experience shows that a lot of problems
+are fixed this way.
+
+=item Gzip libraries
+
+Late versions of MySQL come with support for compression. Thus
+it B<may> be required that you have install an RPM package like
+libz-devel, libgz-devel or something similar.
+
+=back
+
+
+=head1 BINARY INSTALLATION
+
+Binary installation is possible in the most cases, depending
+on your system. I give some examples:
+
+
+=head2 Windows
+
+ActivePerl offers a PPM archive of DBD::mysql. All you need to
+do is typing
+
+  ppm
+  install DBI
+  install DBD-mysql
+
+This will fetch the modules via HTTP and install them. If you
+need to use a WWW proxy server, the environment variable
+HTTP_proxy must be set:
+
+  set HTTP_proxy=http://my.proxy.server:8000/
+  ppm
+  install DBI
+  install DBD-mysql
+
+Of course you need to replace the host name C<my.proxy.server>
+and the port number C<8000> with your local values.
+
+If the above procedure doesn't work, please upgrade to the latest
+version of ActivePerl. Versions before build 623 are known to
+have problems.
+
+PPM 3 is said to miss DBD::mysql in the repository. Thus use of
+PPM 3 is discouraged, in favour of PPM 2. If you need to use
+PPM 3, try
+
+  ppm
+  rep add PPM2 http://ppm.activestate.com/PPMPackages/5.6plus/
+  rep 2
+  install DBI
+  install DBD-mysql
+
+
+
+=head2 Red Hat Linux
+
+As of version 7.1, Red Hat Linux comes with MySQL and DBD::mysql.
+You need to ensure that the following RPM's are installed:
+
+  mysql
+  perl-DBI
+  perl-DBD-MySQL
+
+For installation from source the following RPM's are required
+
+  mysql-devel
+  libz-devel
+
+Optional are
+
+  mysql-server
+
+=head2 Fedora Core Linux
+
+As of version 3, Fedora Linux comes with MySQL and DBD::mysql.
+You need to ensure that the following RPM's are installed:
+
+  mysql or mysql-server
+  perl-DBD-MySQL
+
+For installation from source the following RPM's are required
+
+  mysql-devel
+  libz-devel
+
+Please try 
+
+  yum search mysql
+
+To see the exact names
+
+Note: (important) FC 3 comes with MySQL 3.x, and some people have
+upgraded using MySQL RPMs for newer versions. If you do this, you 
+must re-compile you DBD::mysql because your existing DBD::mysql will be
+linked against the old version of MySQL's client libs. CPAN has no way to
+know or detect that you have upgraded MySQL.
+
+=head2 Other systems
+
+In the case of Linux or FreeBSD distributions it is very likely
+that all you need comes with your distribution, as in the case
+of Red Hat Linux. I just cannot give you names, as I am not using
+these systems.
+
+Please let me know if you find the files in your SuSE Linux, Debian
+Linux or FreeBSD distribution so that I can extend the above list.
+
+
+=head1 SOURCE INSTALLATION
+
+So you need to install from sources. If you are lucky, the Perl
+module C<CPAN> will do all for you, thanks to the excellent work
+of Andreas Koenig. Otherwise you will need to do a manual
+installation. Some of you, in particular system administrators
+of multiple sites, will choose automatic installation. All of
+these installation types have an own section. L</CPAN installation>.
+L</Manual installation>. L</Configuration>.
+
+The DBD::mysql Makefile.PL needs to know where to find your MySQL
+installation. This may be achieved using command line switches
+(see L</Configuration>) or automatically using the mysql_config binary
+which comes with most MySQL distributions. If your MySQL distribution
+contains mysql_config the easiest method is to ensure this binary
+is on your path.
+ 
+e.g.
+
+  PATH=$PATH:/usr/local/mysql/bin
+  export PATH
+
+
+=head2 CPAN installation
+
+Installation of DBD::mysql can be incredibly easy:
+
+  cpan
+  install DBD::mysql
+
+If you are using the CPAN module for the first time, just answer
+the questions by accepting the defaults which are fine in most
+cases. If you are using an older version of Perl, you might
+instead need a
+
+  perl -MCPAN -e shell
+  install DBD::mysql
+
+If you cannot get the CPAN module working, you might try manual
+installation. If installation with CPAN fails because the your local
+settings have been guessed wrong, you need to ensure MySQL's
+mysql_config is on your path (see L</SOURCE INSTALLATION>) or
+alternatively create a script called C<mysql_config>. This is
+described in more details later. L</Configuration>.
+
+
+=head2 Manual installation
+
+For a manual installation you need to fetch the DBD::mysql
+source distribution. The latest version is always available
+from
+
+  http://www.cpan.org/modules/by-module/DBD/
+
+The name is typically something like
+
+  DBD-mysql-1.2216.tar.gz
+
+The archive needs to be extracted. On Windows you may use a tool
+like WinZip, on Unix you type
+
+  gzip -cd DBD-mysql-1.2216.tar.gz | tar xf -
+
+This will create a subdirectory DBD-mysql-1.2216. Enter this
+subdirectory and type
+
+  perl Makefile.PL
+  make
+  make test
+
+(On Windows you may need to replace "make" with "nmake" or
+"dmake".) If the tests seem to look fine, you may continue with
+
+  make install
+
+If the compilation (make) or tests fail, you might need to
+configure some settings.
+
+For example you might choose a different database, the C
+compiler or the linker might need some flags. L</Configuration>.
+L</Compiler flags>. L</Linker flags>.
+
+For Windows/CygWin there is a special section below.
+L<Windows/CygWin>.
+ 
+
+=head2 Configuration
+
+The install script "Makefile.PL" can be configured via a lot of
+switches. All switches can be used on the command line. For
+example, the test database:
+
+  perl Makefile.PL --testdb=<db>
+
+If you do not like configuring these switches on the command
+line, you may alternatively create a script called C<mysql_config>.
+This is described later on.
+
+Available switches are:
+
+=over
+
+=item testdb
+
+Name of the test database, defaults to B<test>.
+
+=item testuser
+
+Name of the test user, defaults to empty. If the name is empty,
+then the currently logged in users name will be used.
+
+=item testpassword
+
+Password of the test user, defaults to empty.
+
+=item testhost
+
+Host name or IP number of the test database; defaults to localhost.
+
+=item testport
+
+Port number of the test database
+
+=item ps-protcol=1 or 0
+
+Whether to run the test suite using server prepared statements or driver
+emulated prepared statemetns. ps-protocol=1 means use server prepare,
+ps-protocol=0 means driver emulated.
+
+=item cflags
+
+This is a list of flags that you want to give to the C compiler.
+The most important flag is the location of the MySQL header files.
+For example, on Red Hat Linux the header files are in /usr/include/mysql
+and you might try
+
+  -I/usr/include/mysql
+
+On Windows the header files may be in C:\mysql\include and you might try
+
+  -IC:\mysql\include
+
+The default flags are determined by running
+
+  mysql_config --cflags
+
+More details on the C compiler flags can be found in the following
+section. L</Compiler flags>.
+
+=item libs
+
+This is a list of flags that you want to give to the linker
+or loader. The most important flags are the locations and names
+of additional libraries. For example, on Red Hat Linux your
+MySQL client libraries are in /usr/lib/mysql and you might try
+
+  -L/usr/lib/mysql -lmysqlclient -lz
+
+On Windows the libraries may be in C:\mysql\lib and
+
+  -LC:\mysql\lib -lmysqlclient
+
+might be a good choice. The default flags are determined by running
+
+  mysql_config --libs
+
+More details on the linker flags can be found in a separate section.
+L<Linker flags>.
+
+=back
+
+If a switch is not present on the command line, then the
+script C<mysql_config> will be executed. This script comes
+as part of the MySQL distribution. For example, to determine
+the C compiler flags, we are executing
+
+  mysql_config --cflags
+  mysql_config --libs
+
+If you want to configure your own settings for database name,
+database user and so on, then you have to create a script with
+the same name, that replies
+
+  
+=head2 Compiler flags
+
+Note: the folling info about compiler and linker flags, you shouldn't have
+to use these options because Makefile.PL is pretty good at utilising
+mysql_config to get the flags that you need for a successful compile.
+
+It is typically not so difficult to determine the appropriate
+flags for the C compiler. The linker flags, which you find in
+the next section, are another story.
+
+The determination of the C compiler flags is usually left to
+a configuration script called F<mysql_config>, which can be
+invoked with
+
+  mysql_config --cflags
+
+When doing so, it will emit a line with suggested C compiler
+flags, for example like this:
+
+  -L/usr/include/mysql
+
+The C compiler must find some header files. Header files have
+the extension C<.h>. MySQL header files are, for example,
+F<mysql.h> and F<mysql_version.h>. In most cases the header
+files are not installed by default. For example, on Windows
+it is an installation option of the MySQL setup program
+(Custom installation), whether the header files are installed
+or not. On Red Hat Linux, you need to install an RPM archive
+F<mysql-devel> or F<MySQL-devel>.
+
+If you know the location of the header files, then you will
+need to add an option
+
+  -L<header directory>
+
+to the C compiler flags, for example C<-L/usr/include/mysql>.
+
+
+=head2 Linker flags
+
+Appropriate linker flags are the most common source of problems
+while installing DBD::mysql. I will only give a rough overview,
+you'll find more details in the troubleshooting section.
+L<KNOWN PROBLEMS>
+
+The determination of the C compiler flags is usually left to
+a configuration script called F<mysql_config>, which can be
+invoked with
+
+  mysql_config --libs
+
+When doing so, it will emit a line with suggested C compiler
+flags, for example like this:
+
+   -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm   -lz -lcrypt
+
+The following items typically need to be configured for the
+linker:
+
+=over
+
+=item The mysqlclient library
+
+The MySQL client library comes as part of the MySQL distribution.
+Depending on your system it may be a file called
+
+  F<libmysqlclient.a>   statically linked library, Unix
+  F<libmysqlclient.so>  dynamically linked library, Unix
+  F<mysqlclient.lib>    statically linked library, Windows
+  F<mysqlclient.dll>    dynamically linked library, Windows
+
+or something similar.
+
+As in the case of the header files, the client library is typically
+not installed by default. On Windows you will need to select them
+while running the MySQL setup program (Custom installation). On
+Red Hat Linux an RPM archive F<mysql-devel> or F<MySQL-devel> must
+be installed.
+
+The linker needs to know the location and name of the mysqlclient
+library. This can be done by adding the flags
+
+  -L<lib directory> -lmysqlclient
+
+or by adding the complete path name. Examples:
+
+  -L/usr/lib/mysql -lmysqlclient
+  -LC:\mysql\lib -lmysqlclient
+
+If you would like to use the static libraries (and there are
+excellent reasons to do so), you need to create a separate
+directory, copy the static libraries to that place and use
+the -L switch above to point to your new directory. For example:
+
+  mkdir /tmp/mysql-static
+  cp /usr/lib/mysql/*.a /tmp/mysql-static
+  perl Makefile.PL --libs="-L/tmp/mysql-static -lmysqlclient"
+  make
+  make test
+  make install
+  rm -rf /tmp/mysql-static
+
+
+=item The gzip library
+
+The MySQL client can use compression when talking to the MySQL
+server, a nice feature when sending or receiving large texts over
+a slow network.
+
+On Unix you typically find the appropriate file name by running
+
+  ldconfig -p | grep libz
+  ldconfig -p | grep libgz
+
+Once you know the name (libz.a or libgz.a is best), just add it
+to the list of linker flags. If this seems to be causing problem
+you may also try to link without gzip libraries.
+
+=back
+
+
+=head1 SPECIAL SYSTEMS
+
+Below you find information on particular systems:
+
+
+=head2 Windows/CygWin
+
+If you are a user of Cygwin (the Redhat distribution) you already
+know, it contains a nicely running perl 5.6.1, installation of
+additional modules usually works as a charme via the standard
+procedure of
+
+    perl makefile.PL
+    make
+    make test
+    make install
+
+The Windows binary distribution of MySQL runs smoothly under Cygwin.
+You can start/stop the server and use all Windows clients without problem.
+But to install DBD::mysql you have to take a little special action.
+
+Don't attempt to build DBD::mysql against either the MySQL Windows or
+Linux/Unix BINARY distributions: neither will work!
+
+You MUST compile the MySQL clients yourself under Cygwin, to get a
+'libmysqlclient.a' compiled under Cygwin. Really! You'll only need
+that library and the header files, you don't need any other client parts.
+Continue to use the Windows binaries. And don't attempt (currently) to
+build the MySQL Server part, it is unneccessary, as MySQL AB does an
+excellent job to deliver optimized binaries for the mainstream
+operating systems, and it is told, that the server compiled under Cygwin is
+unstable.
+
+Install MySQL (if you havn't already)
+
+=over
+
+=item -
+
+download the MySQL Windows Binaries from
+http://www.mysql.com/downloads/index.html
+
+=item -
+
+unzip mysql-<version>-win.zip into some temporary location
+
+=item -
+
+start the setup.exe there and follow the instructions
+
+=item -
+
+start the server
+
+=item -
+
+alternatively download, install and start the server on a remote
+server, on what supported OS ever
+
+=back
+
+
+Build MySQL clients under Cygwin:
+
+=over
+
+=item -
+
+download the MySQL LINUX source from
+http://www.mysql.com/downloads/index.html
+
+=item -
+
+unpack mysql-<version>.tar.gz into some tmp location
+
+=item -
+
+cd into the unpacked dir mysql-<version>
+
+  ./configure --prefix=/usr/local/mysql --without-server
+
+This prepares the Makefile with the installed Cygwin features. It
+takes some time, but should finish without error. The 'prefix', as
+given, installs the whole Cygwin/MySQL thingy into a location not
+normally in your PATH, so that you continue to use already installed
+Windows binaries. The --without-server parameter tells configure to
+only build the clients.
+
+=item -
+
+  make
+
+This builds all MySQL client parts ... be patient. It should finish
+finally without any error.
+
+=item -
+
+  make install
+
+This installs the compiled client files under /usr/local/mysql/.
+Remember, you don't need anything except the library under
+/usr/local/mysql/lib and the headers under /usr/local/mysql/include!
+
+Essentially you are now done with this part. If you want, you may try
+your compiled binaries shortly; for that, do:
+
+=item -
+
+  cd /usr/local/mysql/bin
+  ./mysql -h 127.0.0.1
+
+The host (-h) parameter 127.0.0.1 targets the local host, but forces
+the mysql client to use a TCP/IP connection. The default would be a
+pipe/socket connection (even if you say '-h localhost') and this
+doesn't work between Cygwin and Windows (as far as I know).
+
+If you have your MySQL server running on some other box, then please
+substitute '127.0.0.1' with the name or IP-number of that box.
+
+=back
+
+Please note, in my environment the 'mysql' client did not accept a
+simple RETURN, I had to use CTRL-RETURN to send commands
+... strange,
+but I didn't attempt to fix that, as we are only interested in the
+built lib and headers.
+
+At the 'mysql>' prompt do a quick check:
+
+  mysql> use mysql
+  mysql> show tables;
+  mysql> select * from db;
+  mysql> exit
+
+You are now ready to build DBD::mysql!
+
+
+Build DBD::mysql:
+
+=over
+
+=item -
+
+download DBD-mysql-<version>.tar.gz from CPAN
+
+=item -
+
+unpack DBD-mysql-<version>.tar.gz
+
+=item -
+
+cd into unpacked dir DBD-mysql-<version>
+you probably did that already, if you are reading this!
+
+=item -
+
+  cp /usr/local/mysql/bin/mysql_config .
+
+This copies the executable script mentioned in the DBD::mysql docs
+from your just built Cywin/MySQL client directory; it knows about
+your Cygwin installation, especially about the right libraries to link
+with.
+
+=item -
+
+  perl Makefile.PL --testhost=127.0.0.1
+
+The --testhost=127.0.0.1 parameter again forces a TCP/IP connection
+to the MySQL server on the local host instead of a pipe/socket
+connection for the 'make test' phase.
+
+=item -
+
+  make
+
+This should run without error
+
+=item -
+
+  make test
+
+with DBD-mysql-2.1022 or earlier you will see several errors in
+dbdadmin.t, mysql.t and mysql2.t; with later versions you should not
+get errors (except possibly one, indicating, that some tables could
+not be dropped. I'm hunting for a solution to that problem, but have
+none yet).
+
+=item -
+
+  make install
+
+This installs DBD::mysql into the Perl hierarchy.
+
+=back
+
+Notes:
+
+This was tested with MySQL version 3.23.54a and DBD::mysql version
+2.1022. I patched the above mentioned test scripts and sent the
+patches
+to the author of DBD::mysql Jochen Wiedman.
+
+Georg Rehfeld          15. Jan. 2003
+
+
+=head1 KNOWN PROBLEMS
+
+=over
+
+=item 1.)
+
+Some Linux distributions don't come with a gzip library by default.
+Running "make" terminates with an error message like
+
+  LD_RUN_PATH="/usr/lib/mysql:/lib:/usr/lib" gcc
+    -o blib/arch/auto/DBD/mysql/mysql.so  -shared
+    -L/usr/local/lib dbdimp.o mysql.o -L/usr/lib/mysql
+    -lmysqlclient -lm -L/usr/lib/gcc-lib/i386-redhat-linux/2.96
+    -lgcc -lz 
+  /usr/bin/ld: cannot find -lz
+  collect2: ld returned 1 exit status
+  make: *** [blib/arch/auto/DBD/mysql/mysql.so] Error 1
+
+If this is the case for you, install an RPM archive like
+libz-devel, libgz-devel, zlib-devel or gzlib-devel or something
+similar.
+
+=item 2.)
+
+If Perl was compiled with gcc or egcs, but MySQL was compiled
+with another compiler or on another system, an error message like
+this is very likely when running "Make test":
+
+  t/00base............install_driver(mysql) failed: Can't load
+  '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql:
+  ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3
+  at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm
+  line 168.
+
+This means, that your linker doesn't include libgcc.a. You have
+the following options:
+
+The solution is telling the linker to use libgcc. Run
+
+  gcc --print-libgcc-file
+
+to determine the exact location of libgcc.a or for older versions
+of gcc
+
+  gcc -v
+
+to determine the directory. If you know the directory, add a
+
+  -L<directory> -lgcc
+
+to the list of C compiler flags. L</Configuration>. L</Linker flags>.
+
+=item 3.)
+
+There are known problems with shared versions of libmysqlclient,
+at least on some Linux boxes. If you receive an error message
+similar to
+
+  install_driver(mysql) failed: Can't load
+  '/usr/lib/perl5/site_perl/i586-linux/auto/DBD/mysql/mysql.so'
+  for module DBD::mysql: File not found at
+  /usr/lib/perl5/i586-linux/5.00404/DynaLoader.pm line 166
+
+then this error message can be misleading: It's not mysql.so
+that fails being loaded, but libmysqlclient.so! The usual
+problem is that this file is located in a directory like
+
+  /usr/lib/mysql
+
+where the linker doesn't look for it.
+
+The best workaround is using a statically linked mysqlclient
+library, for example
+
+  /usr/lib/mysql/libmysqlclient.a
+
+The use of a statically linked library is described in the
+previous section on linker flags. L</Configuration>.
+L</Linker flags>.  
+
+=item 4.)
+
+Red Hat 8 & 9 set the Default locale to UTF which causes problems with 
+MakeMaker.  To build DBD::mysql on these systems, do a 'unset LANG' 
+before runing 'perl Makefile.PL'
+
+=back
+
+
+=head1 SUPPORT
+
+Finally, if everything else fails, you are not alone. First of
+all, for an immediate answer, you should look into the archives
+of the mailing list B<perl@lists.mysql.com>. See
+http://www.mysql.com for archive locations.
+
+If you don't find an appropriate posting and reply in the
+mailing list, please post a question. Typically a reply will
+be seen within one or two days.