[ Index ] |
PHP Cross Reference of Unnamed Project |
[Summary view] [Print] [Text view]
1 =head1 NAME 2 3 INSTALL - How to install and configure DBD::mysql 4 5 6 =head1 SYNOPSIS 7 8 perl Makefile.PL [options] 9 make 10 make test 11 make install 12 13 14 =head1 DESCRIPTION 15 16 This document describes the installation and configuration of 17 DBD::mysql, the Perl DBI driver for the MySQL database. Before 18 reading on, make sure that you have the prerequisites available: 19 Perl, MySQL and DBI. For details see the separate section. 20 L</PREREQUISITES>. 21 22 Depending on your version of Perl, it might be possible to 23 use a binary distribution of DBD::mysql. If possible, this is 24 recommended. Otherwise you need to install from the sources. 25 If so, you will definitely need a C compiler. Installation 26 from binaries and sources are both described in separate 27 sections. L<BINARY INSTALLATION>. L<SOURCE INSTALLATION>. 28 29 Finally, if you encounter any problems, do not forget to 30 read the section on known problems. L<KNOWN PROBLEMS>. If 31 that doesn't help, you should look into the archive of the 32 mailing list B<msql-mysql-modules@lists.mysql.com>. See 33 http://www.mysql.com for archive locations. And if that 34 still doesn't help, please post a question on this mailing 35 list. 36 37 38 =head1 PREREQUISITES 39 40 =over 41 42 =item Perl 43 44 Preferrably a version of Perl, that comes preconfigured with 45 your system. For example, all Linux and FreeBSD distributions 46 come with Perl. For Windows, ActivePerl is recommended, see 47 http://www.activestate.com for details. 48 49 =item MySQL 50 51 You need not install the actual MySQL database server, the 52 client files and the devlopment files are sufficient. For 53 example, the Red Hat Linux distribution comes with RPM files 54 B<mysql-client> and B<mysql-devel>. These are sufficient, 55 if the MySQL server is located on a foreign machine. You may 56 also create client files by compiling from the MySQL source 57 distribution and using 58 59 configure --without-server 60 61 If you are using Windows and need to compile from sources 62 (which is only the case if you are not using ActivePerl), 63 then you must ensure that the header and library files are 64 installed. This may require choosing a "Custom installation" 65 and selecting the appropriate option when running the 66 MySQL setup program. 67 68 =item DBI 69 70 DBD::mysql is a DBI driver, hence you need DBI. It is available 71 from the same source where you got the DBD::mysql distribution 72 from. 73 74 =item C compiler 75 76 A C compiler is only required, if you install from source. In 77 most cases there are binary distributions of DBD::mysql 78 available. However, if you need a C compiler, make sure, that 79 it is the same C compiler that was used for compiling Perl and 80 MySQL! Otherwise you will almost definitely encounter problems 81 because of differences in the underlying C runtime libraries. 82 83 In the worst case, this might mean to compile Perl and MySQL 84 yourself. But believe me, experience shows that a lot of problems 85 are fixed this way. 86 87 =item Gzip libraries 88 89 Late versions of MySQL come with support for compression. Thus 90 it B<may> be required that you have install an RPM package like 91 libz-devel, libgz-devel or something similar. 92 93 =back 94 95 96 =head1 BINARY INSTALLATION 97 98 Binary installation is possible in the most cases, depending 99 on your system. I give some examples: 100 101 102 =head2 Windows 103 104 ActivePerl offers a PPM archive of DBD::mysql. All you need to 105 do is typing 106 107 ppm 108 install DBI 109 install DBD-mysql 110 111 This will fetch the modules via HTTP and install them. If you 112 need to use a WWW proxy server, the environment variable 113 HTTP_proxy must be set: 114 115 set HTTP_proxy=http://my.proxy.server:8000/ 116 ppm 117 install DBI 118 install DBD-mysql 119 120 Of course you need to replace the host name C<my.proxy.server> 121 and the port number C<8000> with your local values. 122 123 If the above procedure doesn't work, please upgrade to the latest 124 version of ActivePerl. Versions before build 623 are known to 125 have problems. 126 127 PPM 3 is said to miss DBD::mysql in the repository. Thus use of 128 PPM 3 is discouraged, in favour of PPM 2. If you need to use 129 PPM 3, try 130 131 ppm 132 rep add PPM2 http://ppm.activestate.com/PPMPackages/5.6plus/ 133 rep 2 134 install DBI 135 install DBD-mysql 136 137 138 139 =head2 Red Hat Linux 140 141 As of version 7.1, Red Hat Linux comes with MySQL and DBD::mysql. 142 You need to ensure that the following RPM's are installed: 143 144 mysql 145 perl-DBI 146 perl-DBD-MySQL 147 148 For installation from source the following RPM's are required 149 150 mysql-devel 151 libz-devel 152 153 Optional are 154 155 mysql-server 156 157 158 =head2 Other systems 159 160 In the case of Linux or FreeBSD distributions it is very likely 161 that all you need comes with your distribution, as in the case 162 of Red Hat Linux. I just cannot give you names, as I am not using 163 these systems. 164 165 Please let me know if you find the files in your SuSE Linux, Debian 166 Linux or FreeBSD distribution so that I can extend the above list. 167 168 169 =head1 SOURCE INSTALLATION 170 171 So you need to install from sources. If you are lucky, the Perl 172 module C<CPAN> will do all for you, thanks to the excellent work 173 of Andreas Koenig. Otherwise you will need to do a manual 174 installation. Some of you, in particular system administrators 175 of multiple sites, will choose automatic installation. All of 176 these installation types have an own section. L</CPAN installation>. 177 L</Manual installation>. L</Configuration>. 178 179 180 =head2 CPAN installation 181 182 Installation of DBD::mysql can be incredibly easy: 183 184 cpan 185 install DBD::mysql 186 187 If you are using the CPAN module for the first time, just answer 188 the questions by accepting the defaults which are fine in most 189 cases. If you are using an older version of Perl, you might 190 instead need a 191 192 perl -MCPAN -e shell 193 install DBD::mysql 194 195 If you cannot get the CPAN module working, you might try manual 196 installation. If installation with CPAN fails because the your 197 local settings have been guessed wrong, you might try to 198 create a script called C<mysql_config>. This is described in 199 more details later. L</Configuration>. 200 201 202 =head2 Manual installation 203 204 For a manual installation you need to fetch the DBD::mysql 205 source distribution. The latest version is always available 206 from 207 208 http://www.cpan.org/modules/by-module/DBD/ 209 210 The name is typically something like 211 212 DBD-mysql-1.2216.tar.gz 213 214 The archive needs to be extracted. On Windows you may use a tool 215 like WinZip, on Unix you type 216 217 gzip -cd DBD-mysql-1.2216.tar.gz | tar xf - 218 219 This will create a subdirectory DBD-mysql-1.2216. Enter this 220 subdirectory and type 221 222 perl Makefile.PL 223 make 224 make test 225 226 (On Windows you may need to replace "make" with "nmake" or 227 "dmake".) If the tests seem to look fine, you may continue with 228 229 make install 230 231 If the tests fail, you might need to configure some settings. 232 For example you might choose a different database, the C 233 compiler or the linker might need some flags. L</Configuration>. 234 L</C Compiler flags>. L</Linker flags>. 235 236 For Windows/CygWin there is a special section below. 237 L<Windows/CygWin>. 238 239 240 =head2 Configuration 241 242 The install script "Makefile.PL" can be configured via a lot of 243 switches. All switches can be used on the command line. For 244 example, the test database: 245 246 perl Makefile.PL --testdb=<db> 247 248 If you do not like configuring these switches on the command 249 line, you may alternatively create a script called C<mysql_config>. 250 This is described later on. 251 252 Available switches are: 253 254 =over 255 256 =item testdb 257 258 Name of the test database, defaults to B<test>. 259 260 =item testuser 261 262 Name of the test user, defaults to empty. If the name is empty, 263 then the currently logged in users name will be used. 264 265 =item testpassword 266 267 Password of the test user, defaults to empty. 268 269 =item testhost 270 271 Host name or IP number of the test database; defaults to localhost. 272 273 =item testport 274 275 Port number of the test database 276 277 =item cflags 278 279 This is a list of flags that you want to give to the C compiler. 280 The most important flag is the location of the MySQL header files. 281 For example, on Red Hat Linux the header files are in /usr/include/mysql 282 and you might try 283 284 -I/usr/include/mysql 285 286 On Windows the header files may be in C:\mysql\include and you might try 287 288 -IC:\mysql\include 289 290 The default flags are determined by running 291 292 mysql_config --cflags 293 294 More details on the C compiler flags can be found in the following 295 section. L</C Compiler flags>. 296 297 =item libs 298 299 This is a list of flags that you want to give to the linker 300 or loader. The most important flags are the locations and names 301 of additional libraries. For example, on Red Hat Linux your 302 MySQL client libraries are in /usr/lib/mysql and you might try 303 304 -L/usr/lib/mysql -lmysqlclient -lz 305 306 On Windows the libraries may be in C:\mysql\lib and 307 308 -LC:\mysql\lib -lmysqlclient 309 310 might be a good choice. The default flags are determined by running 311 312 mysql_config --libs 313 314 More details on the linker flags can be found in a separate section. 315 L<Linker flags>. 316 317 =back 318 319 If a switch is not present on the command line, then the 320 script C<mysql_config> will be executed. This script comes 321 as part of the MySQL distribution. For example, to determine 322 the C compiler flags, we are executing 323 324 mysql_config --cflags 325 mysql_config --libs 326 327 If you want to configure your own settings for database name, 328 database user and so on, then you have to create a script with 329 the same name, that replies 330 331 332 =head2 C Compiler flags 333 334 It is typically not so difficult to determine the appropriate 335 flags for the C compiler. The linker flags, which you find in 336 the next section, are another story. 337 338 The determination of the C compiler flags is usually left to 339 a configuration script called F<mysql_config>, which can be 340 invoked with 341 342 mysql_config --cflags 343 344 When doing so, it will emit a line with suggested C compiler 345 flags, for example like this: 346 347 -L/usr/include/mysql 348 349 The C compiler must find some header files. Header files have 350 the extension C<.h>. MySQL header files are, for example, 351 F<mysql.h> and F<mysql_version.h>. In most cases the header 352 files are not installed by default. For example, on Windows 353 it is an installation option of the MySQL setup program 354 (Custom installation), whether the header files are installed 355 or not. On Red Hat Linux, you need to install an RPM archive 356 F<mysql-devel> or F<MySQL-devel>. 357 358 If you know the location of the header files, then you will 359 need to add an option 360 361 -L<header directory> 362 363 to the C compiler flags, for example C<-L/usr/include/mysql>. 364 365 366 =head2 Linker flags 367 368 Appropriate linker flags are the most common source of problems 369 while installing DBD::mysql. I will only give a rough overview, 370 you'll find more details in the troubleshooting section. 371 L<KNOWN PROBLEMS> 372 373 The determination of the C compiler flags is usually left to 374 a configuration script called F<mysql_config>, which can be 375 invoked with 376 377 mysql_config --libs 378 379 When doing so, it will emit a line with suggested C compiler 380 flags, for example like this: 381 382 -L'/usr/lib/mysql' -lmysqlclient -lnsl -lm -lz -lcrypt 383 384 The following items typically need to be configured for the 385 linker: 386 387 =over 388 389 =item The mysqlclient library 390 391 The MySQL client library comes as part of the MySQL distribution. 392 Depending on your system it may be a file called 393 394 F<libmysqlclient.a> statically linked library, Unix 395 F<libmysqlclient.so> dynamically linked library, Unix 396 F<mysqlclient.lib> statically linked library, Windows 397 F<mysqlclient.dll> dynamically linked library, Windows 398 399 or something similar. 400 401 As in the case of the header files, the client library is typically 402 not installed by default. On Windows you will need to select them 403 while running the MySQL setup program (Custom installation). On 404 Red Hat Linux an RPM archive F<mysql-devel> or F<MySQL-devel> must 405 be installed. 406 407 The linker needs to know the location and name of the mysqlclient 408 library. This can be done by adding the flags 409 410 -L<lib directory> -lmysqlclient 411 412 or by adding the complete path name. Examples: 413 414 -L/usr/lib/mysql -lmysqlclient 415 -LC:\mysql\lib -lmysqlclient 416 417 If you would like to use the static libraries (and there are 418 excellent reasons to do so), you need to create a separate 419 directory, copy the static libraries to that place and use 420 the -L switch above to point to your new directory. For example: 421 422 mkdir /tmp/mysql-static 423 cp /usr/lib/mysql/*.a /tmp/mysql-static 424 perl Makefile.PL --libs="-L/tmp/mysql-static -lmysqlclient" 425 make 426 make test 427 make install 428 rm -rf /tmp/mysql-static 429 430 431 =item The gzip library 432 433 The MySQL client can use compression when talking to the MySQL 434 server, a nice feature when sending or receiving large texts over 435 a slow network. 436 437 On Unix you typically find the appropriate file name by running 438 439 ldconfig -p | grep libz 440 ldconfig -p | grep libgz 441 442 Once you know the name (libz.a or libgz.a is best), just add it 443 to the list of linker flags. If this seems to be causing problem 444 you may also try to link without gzip libraries. 445 446 =back 447 448 449 =head1 SPECIAL SYSTEMS 450 451 Below you find information on particular systems: 452 453 454 =head2 Windows/CygWin 455 456 If you are a user of Cygwin (the Redhat distribution) you already 457 know, it contains a nicely running perl 5.6.1, installation of 458 additional modules usually works as a charme via the standard 459 procedure of 460 461 perl makefile.PL 462 make 463 make test 464 make install 465 466 The Windows binary distribution of MySQL runs smoothly under Cygwin. 467 You can start/stop the server and use all Windows clients without problem. 468 But to install DBD::mysql you have to take a little special action. 469 470 Don't attempt to build DBD::mysql against either the MySQL Windows or 471 Linux/Unix BINARY distributions: neither will work! 472 473 You MUST compile the MySQL clients yourself under Cygwin, to get a 474 'libmysqlclient.a' compiled under Cygwin. Really! You'll only need 475 that library and the header files, you don't need any other client parts. 476 Continue to use the Windows binaries. And don't attempt (currently) to 477 build the MySQL Server part, it is unneccessary, as MySQL AB does an 478 excellent job to deliver optimized binaries for the mainstream 479 operating systems, and it is told, that the server compiled under Cygwin is 480 unstable. 481 482 Install MySQL (if you havn't already) 483 484 =over 485 486 =item - 487 488 download the MySQL Windows Binaries from 489 http://www.mysql.com/downloads/index.html 490 491 =item - 492 493 unzip mysql-<version>-win.zip into some temporary location 494 495 =item - 496 497 start the setup.exe there and follow the instructions 498 499 =item - 500 501 start the server 502 503 =item - 504 505 alternatively download, install and start the server on a remote 506 server, on what supported OS ever 507 508 =back 509 510 511 Build MySQL clients under Cygwin: 512 513 =over 514 515 =item - 516 517 download the MySQL LINUX source from 518 http://www.mysql.com/downloads/index.html 519 520 =item - 521 522 unpack mysql-<version>.tar.gz into some tmp location 523 524 =item - 525 526 cd into the unpacked dir mysql-<version> 527 528 ./configure --prefix=/usr/local/mysql --without-server 529 530 This prepares the Makefile with the installed Cygwin features. It 531 takes some time, but should finish without error. The 'prefix', as 532 given, installs the whole Cygwin/MySQL thingy into a location not 533 normally in your PATH, so that you continue to use already installed 534 Windows binaries. The --without-server parameter tells configure to 535 only build the clients. 536 537 =item - 538 539 make 540 541 This builds all MySQL client parts ... be patient. It should finish 542 finally without any error. 543 544 =item - 545 546 make install 547 548 This installs the compiled client files under /usr/local/mysql/. 549 Remember, you don't need anything except the library under 550 /usr/local/mysql/lib and the headers under /usr/local/mysql/include! 551 552 Essentially you are now done with this part. If you want, you may try 553 your compiled binaries shortly; for that, do: 554 555 =item - 556 557 cd /usr/local/mysql/bin 558 ./mysql -h 127.0.0.1 559 560 The host (-h) parameter 127.0.0.1 targets the local host, but forces 561 the mysql client to use a TCP/IP connection. The default would be a 562 pipe/socket connection (even if you say '-h localhost') and this 563 doesn't work between Cygwin and Windows (as far as I know). 564 565 If you have your MySQL server running on some other box, then please 566 substitute '127.0.0.1' with the name or IP-number of that box. 567 568 =back 569 570 Please note, in my environment the 'mysql' client did not accept a 571 simple RETURN, I had to use CTRL-RETURN to send commands 572 ... strange, 573 but I didn't attempt to fix that, as we are only interested in the 574 built lib and headers. 575 576 At the 'mysql>' prompt do a quick check: 577 578 mysql> use mysql 579 mysql> show tables; 580 mysql> select * from db; 581 mysql> exit 582 583 You are now ready to build DBD::mysql! 584 585 586 Build DBD::mysql: 587 588 =over 589 590 =item - 591 592 download DBD-mysql-<version>.tar.gz from CPAN 593 594 =item - 595 596 unpack DBD-mysql-<version>.tar.gz 597 598 =item - 599 600 cd into unpacked dir DBD-mysql-<version> 601 you probably did that already, if you are reading this! 602 603 =item - 604 605 cp /usr/local/mysql/bin/mysql_config . 606 607 This copies the executable script mentioned in the DBD::mysql docs 608 from your just built Cywin/MySQL client directory; it knows about 609 your Cygwin installation, especially about the right libraries to link 610 with. 611 612 =item - 613 614 perl Makefile.PL --testhost=127.0.0.1 615 616 The --testhost=127.0.0.1 parameter again forces a TCP/IP connection 617 to the MySQL server on the local host instead of a pipe/socket 618 connection for the 'make test' phase. 619 620 =item - 621 622 make 623 624 This should run without error 625 626 =item - 627 628 make test 629 630 with DBD-mysql-2.1022 or earlier you will see several errors in 631 dbdadmin.t, mysql.t and mysql2.t; with later versions you should not 632 get errors (except possibly one, indicating, that some tables could 633 not be dropped. I'm hunting for a solution to that problem, but have 634 none yet). 635 636 =item - 637 638 make install 639 640 This installs DBD::mysql into the Perl hierarchy. 641 642 =back 643 644 Notes: 645 646 This was tested with MySQL version 3.23.54a and DBD::mysql version 647 2.1022. I patched the above mentioned test scripts and sent the 648 patches 649 to the author of DBD::mysql Jochen Wiedman. 650 651 Georg Rehfeld 15. Jan. 2003 652 653 654 =head1 KNOWN PROBLEMS 655 656 =over 657 658 =item 1.) 659 660 Some Linux distributions don't come with a gzip library by default. 661 Running "make" terminates with an error message like 662 663 LD_RUN_PATH="/usr/lib/mysql:/lib:/usr/lib" gcc 664 -o blib/arch/auto/DBD/mysql/mysql.so -shared 665 -L/usr/local/lib dbdimp.o mysql.o -L/usr/lib/mysql 666 -lmysqlclient -lm -L/usr/lib/gcc-lib/i386-redhat-linux/2.96 667 -lgcc -lz 668 /usr/bin/ld: cannot find -lz 669 collect2: ld returned 1 exit status 670 make: *** [blib/arch/auto/DBD/mysql/mysql.so] Error 1 671 672 If this is the case for you, install an RPM archive like 673 libz-devel, libgz-devel, zlib-devel or gzlib-devel or something 674 similar. 675 676 =item 2.) 677 678 If Perl was compiled with gcc or egcs, but MySQL was compiled 679 with another compiler or on another system, an error message like 680 this is very likely when running "Make test": 681 682 t/00base............install_driver(mysql) failed: Can't load 683 '../blib/arch/auto/DBD/mysql/mysql.so' for module DBD::mysql: 684 ../blib/arch/auto/DBD/mysql/mysql.so: undefined symbol: _umoddi3 685 at /usr/local/perl-5.005/lib/5.005/i586-linux-thread/DynaLoader.pm 686 line 168. 687 688 This means, that your linker doesn't include libgcc.a. You have 689 the following options: 690 691 The solution is telling the linker to use libgcc. Run 692 693 gcc --print-libgcc-file 694 695 to determine the exact location of libgcc.a or for older versions 696 of gcc 697 698 gcc -v 699 700 to determine the directory. If you know the directory, add a 701 702 -L<directory> -lgcc 703 704 to the list of C compiler flags. L</Configuration>. L</Linker flags>. 705 706 =item 3.) 707 708 There are known problems with shared versions of libmysqlclient, 709 at least on some Linux boxes. If you receive an error message 710 similar to 711 712 install_driver(mysql) failed: Can't load 713 '/usr/lib/perl5/site_perl/i586-linux/auto/DBD/mysql/mysql.so' 714 for module DBD::mysql: File not found at 715 /usr/lib/perl5/i586-linux/5.00404/DynaLoader.pm line 166 716 717 then this error message can be misleading: It's not mysql.so 718 that fails being loaded, but libmysqlclient.so! The usual 719 problem is that this file is located in a directory like 720 721 /usr/lib/mysql 722 723 where the linker doesn't look for it. 724 725 The best workaround is using a statically linked mysqlclient 726 library, for example 727 728 /usr/lib/mysql/libmysqlclient.a 729 730 The use of a statically linked library is described in the 731 previous section on linker flags. L</Configuration>. 732 L</Linker flags>. 733 734 =item 4.) 735 736 Red Hat 8 & 9 set the Default locale to UTF which causes problems with 737 MakeMaker. To build DBD::mysql on these systems, do a 'unset LANG' 738 before runing 'perl Makefile.PL' 739 740 =back 741 742 743 =head1 SUPPORT 744 745 Finally, if everything else fails, you are not alone. First of 746 all, for an immediate answer, you should look into the archives 747 of the mailing list B<msql-mysql-modules@lists.mysql.com>. See 748 http://www.mysql.com for archive locations. 749 750 If you don't find an appropriate posting and reply in the 751 mailing list, please post a question. Typically a reply will 752 be seen within one or two days.
title
Description
Body
title
Description
Body
title
Description
Body
title
Body
Generated: Tue Mar 17 22:47:18 2015 | Cross-referenced by PHPXref 0.7.1 |