diff -r 7659931b2194 -r ead96bc104ea common/tools/lib/DBD/mysql/INSTALL.pod --- /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. + +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. L. + +Finally, if you encounter any problems, do not forget to +read the section on known problems. L. If +that doesn't help, you should look into the archive of the +mailing list B. 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 and B (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 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 +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 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. +L. L. + +The DBD::mysql Makefile.PL needs to know where to find your MySQL +installation. This may be achieved using command line switches +(see L) 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) or +alternatively create a script called C. This is +described in more details later. L. + + +=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. +L. L. + +For Windows/CygWin there is a special section below. +L. + + +=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= + +If you do not like configuring these switches on the command +line, you may alternatively create a script called C. +This is described later on. + +Available switches are: + +=over + +=item testdb + +Name of the test database, defaults to B. + +=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. + +=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. + +=back + +If a switch is not present on the command line, then the +script C 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, 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 and F. 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 or F. + +If you know the location of the header files, then you will +need to add an option + + -L
+ +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 + +The determination of the C compiler flags is usually left to +a configuration script called F, 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 statically linked library, Unix + F dynamically linked library, Unix + F statically linked library, Windows + F 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 or F 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 -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--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-.tar.gz into some tmp location + +=item - + +cd into the unpacked dir mysql- + + ./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-.tar.gz from CPAN + +=item - + +unpack DBD-mysql-.tar.gz + +=item - + +cd into unpacked dir DBD-mysql- +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 -lgcc + +to the list of C compiler flags. L. L. + +=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. +L. + +=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. 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.