1=head1 NAME 2 3Installing mod_perl 2.0 4 5=head1 Description 6 7This chapter provides an in-depth mod_perl 2.0 installation coverage. 8 9 10 11 12 13 14=head1 Prerequisites 15 16Before building mod_perl 2.0 you need to have its prerequisites 17installed. If you don't have them, download and install them first, 18using the information in the following sections. Otherwise proceed 19directly to the mod_perl building instructions. 20 21The mod_perl 2.0 prerequisites are: 22 23=over 24 25=item * Apache 26 27Apache 2.0 is required. mod_perl 2.0 B<does not> work with Apache 1.3. 28 29L<Dynamic|/MP_USE_DSO> (DSO) mod_perl build requires Apache 2.0.47 or 30higher. L<Static|/MP_USE_STATIC> build requires Apache 2.0.51 or 31higher. 32 33=item * Perl 34 35=over 36 37=item Prefork MPM 38 39Requires at least Perl version 5.6.1. 40 41You don't need to have threads-support enabled in Perl. If you do have 42it, it B<must> be I<ithreads> and not I<5005threads>! If you have: 43 44 % perl5.8.0 -V:use5005threads 45 use5005threads='define'; 46 47you must rebuild Perl without threads enabled or with 48C<-Dusethreads>. Remember that threads-support slows things down and 49on some platforms it's unstable (e.g., FreeBSD), so don't enable it 50unless you really need it. 51 52=item 64 bit Linux 53 54If while running C<make test> while building mod_perl 2 you get an error like 55this: 56 57 /usr/bin/ld: /usr/local/lib/perl5/5.10.1/x86_64-linux/CORE/libperl.a(op.o): \ 58 relocation R_X86_64_32S against `PL_sv_yes' can not be used when making a shared \ 59 object; recompile with -fPIC 60 /usr/local/lib/perl5/5.10.1/x86_64-linux/CORE/libperl.a: could not read symbols: Bad \ 61 value 62 63You're likely on 64 bit Linux and will need to build Perl for that platform. 64You can do so by running Perl's C<Configure> with the C<$CFLAGS> environment 65variable and the C<-A> and C<ccflags> options. So if you normally build Perl 66with: 67 68 % ./Configure -des 69 70You would instead configure with: 71 72 % CFLAGS='-m64 -mtune=nocona' ./Configure -des -A ccflags=-fPIC 73 74=item Threaded MPMs 75 76Require at least Perl version 5.8.0 with ithreads support 77built-in. That means that it should report: 78 79 % perl5.8.0 -V:useithreads -V:usemultiplicity 80 useithreads='define'; 81 usemultiplicity='define'; 82 83If that's not what you see rebuild Perl with C<-Dusethreads>. 84 85=item Static prefork build 86 87Perl with ithreads support version 5.6.1 or higher 88 89Perl without ithreads support version 5.8.2 or higher 90 91=item Static non-prefork build 92 93Perl with ithreads support version 5.8.0 or higher 94 95=item threads.pm 96 97If you want to run applications that take benefit of Perl's 98I<threads.pm> Perl version 5.8.1 or higher w/ithreads enabled is 99required. Perl 5.8.0's I<threads.pm> doesn't work with mod_perl 2.0. 100 101=back 102 103=item * CPAN Perl Modules 104 105The mod_perl 2.0 test suite has several requirements on its own. If 106you don't satisfy them, the tests depending on these requirements will 107be skipped, which is OK, but you won't get to run these tests and 108potential problems, which may exhibit themselves in your own code, 109could be missed. We don't require them from C<Makefile.PL>, which 110could have been automated the requirements installation, in order to 111have less dependencies to get mod_perl 2.0 installed. 112 113Also if your code uses any of these modules, chances are that you will 114need to use at least the version numbers listed here. 115 116=over 117 118=item CGI.pm 3.11 119 120=item Compress::Zlib 1.09 121 122=back 123 124Though the easiest way to satisfy all the dependencies is to install 125C<Bundle::Apache2> available from CPAN. 126 127=back 128 129 130 131 132 133 134 135=head2 Downloading Stable Release Sources 136 137If you are going to install mod_perl on a production site, you want to 138use the officially released stable components. Since the latest stable 139versions change all the time you should check for the latest stable 140version at the listed below URLs: 141 142=over 143 144=item Perl 145 146Download from: I<http://cpan.org/src/README.html> 147 148This direct link which symlinks to the latest release should work too: 149I<http://cpan.org/src/stable.tar.gz>. 150 151For the purpose of examples in this chapter we will use the package 152named I<perl-5.8.x.tar.gz>, where I<x> should be replaced with the 153real version number. 154 155=item Apache 156 157Download from: I<http://www.apache.org/dist/httpd/> 158 159For the purpose of examples in this chapter we will use the package 160named I<httpd-2.x.xx.tar.gz>, where I<x.xx> should be replaced with 161the real version number. 162 163 164=back 165 166 167 168=head2 Getting Bleeding Edge Sources 169 170If you really know what you are doing you can use the cvs/svn versions 171of the components. Chances are that you don't want to them on a 172production site. You have been warned! 173 174=over 175 176=item Perl 177 178The cutting edge version of Perl (aka bleadperl or bleedperl) is only 179generally available through an rsync repository maintained by 180ActiveState: 181 182 # (--delete to ensure a clean state) 183 % rsync -acvz --delete --force \ 184 rsync://public.activestate.com/perl-current/ perl-current 185 186If you are re-building Perl after rsync-ing, make sure to cleanup first: 187 188 % make distclean 189 190before running C<./Configure>. 191 192You'll also want to install (at least) LWP if you want to fully test 193mod_perl. You can install LWP with C<CPAN.pm> shell: 194 195 % perl -MCPAN -e 'install("LWP")' 196 197For more details on bleadperl, see I<http://dev.perl.org/perl5/source.html>. 198 199=item Apache 200 201See L<Development mod_perl 2.0 Source 202Distribution|download::source/Development_mod_perl_2_0_Source_Distribution>. 203 204=back 205 206 207 208=head2 Configuring and Installing Prerequisites 209 210If you don't have the prerequisites installed yet, install them now. 211 212 213 214=head3 Perl 215 216 % cd perl-5.8.x 217 % ./Configure -des 218 219If you L<need the threads 220support|docs::2.0::user::install::install/Prerequisites>, run: 221 222 % ./Configure -des -Dusethreads 223 224Most likely you don't want perl-support for threads enabled, in which 225case pass: C<-Uusethreads> instead of C<-Dusethreads>. 226 227If you want to debug mod_perl segmentation faults, add the 228following I<./Configure> options: 229 230 -Doptimize='-g' -Dusedevel 231 232Now build it: 233 234 % make && make test && make install 235 236 237 238 239=head3 Apache 240 241You need to have Apache built and installed prior to building 242mod_perl, only if you intend build a DSO mod_perl. If you intend to 243build a statically linked Apache+mod_perl, you only need to have the 244Apache source available (mod_perl will build and install Apache for 245you), you should skip this step. 246 247 % cd httpd-2.x.xx 248 % ./configure --prefix=$HOME/httpd/prefork --with-mpm=prefork 249 % make && make install 250 251Starting from 2.0.49, the Apache logging API escapes everything that 252goes to F<error_log>, therefore if you're annoyed by this feature 253during the development phase (as your error messages will be all 254messed up) you can disable the escaping during the Apache build time: 255 256 % CFLAGS="-DAP_UNSAFE_ERROR_LOG_UNESCAPED" ./configure ... 257 258Do B<not> use that CFLAGS in production unless you know what you are 259doing. 260 261 262 263 264=head1 Installing mod_perl from Binary Packages 265 266As of this writing only the binaries for the Win32 platform are 267available, kindly prepared and maintained by Randy Kobes. 268See the documentation on L<Win32 binaries|docs::2.0::os::win32::install> 269for details. 270 271Some RPM packages can be found using rpmfind services, e.g.: 272 273http://www.rpmfind.net/linux/rpm2html/search.php?query=mod_perl&submit=Search+... 274However if you have problems using them, you have to contact those who 275have created them. 276 277 278=head1 Installing mod_perl from Source 279 280Building from source is the best option, because it ensures a binary 281compatibility with Apache and Perl. However it's possible that your 282distribution provides a solid binary mod_perl 2.0 package. 283 284For Win32 specific details, see the documentation on 285L<Win32 installation|docs::2.0::os::win32::install>. 286 287=head2 Downloading the mod_perl Source 288 289First download the mod_perl source. 290 291=over 292 293=item Stable Release 294 295Download from I<http://perl.apache.org/download/> or your favorite 296CPAN mirror. 297 298This direct link which symlinks to the latest release should work too: 299I<http://apache.org/dist/perl/mod_perl-2.0-current.tar.gz>. 300 301For the purpose of examples in this chapter we will use the package 302named I<mod_perl-2.x.x.tar.gz>, where I<x.x> should be replaced with 303the real version number. 304 305Open the package with: 306 307 % tar -xvzf mod_perl-2.x.x.tar.gz 308 309or an equivalent command. 310 311=item Development Version 312 313See L<Development mod_perl 2.0 Source 314Distribution|download::source/Development_mod_perl_2_0_Source_Distribution>. 315 316=back 317 318 319 320=head2 Configuring mod_perl 321 322To build mod_perl, you B<must> also use the same compiler that Perl 323was built with. You can find that out by running C<perl -V> and 324looking at the C<Compiler:> section. 325 326Like any other Perl module, mod_perl is configured via the 327I<Makefile.PL> file, but requires one or more configuration options: 328 329 % cd modperl-2.x.x 330 % perl Makefile.PL <options> 331 332where I<options> is an optional list of key/value pairs. These 333options can include all the usual options supported by 334C<ExtUtils::MakeMaker> (e.g., C<PREFIX>, C<LIB>, etc.). 335 336The following sections give the details about all the available 337options, but let's mention first an important one. 338 339Configuration options are discussed in L<Build 340Options|/mod_perl_Build_Options>. 341 342 343 344=head3 Dynamic mod_perl 345 346Before you proceed, make sure that Apache 2.0 has been built and 347installed. mod_perl B<cannot> be built before that. 348 349It seems that most users use pre-packaged Apache installation, most of 350which tend to spread the Apache files across many directories 351(i.e. not using --enable-layout=Apache, which puts all the files under 352the same directory). If Apache 2.0 files are spread under different 353directories, you need to use at least the C<L<MP_APXS|/MP_APXS>> 354option, which should be set to a full path to the C<apxs> 355executable. For example: 356 357 % perl Makefile.PL MP_APXS=/path/to/apxs 358 359For example RedHat Linux system installs the C<httpd> binary, the 360C<apxs> and C<apr-config> scripts (the latter two are needed to build 361mod_perl) all in different locations, therefore they configure 362mod_perl 2.0 as: 363 364 % perl Makefile.PL MP_APXS=/path/to/apxs \ 365 MP_APR_CONFIG=/another/path/to/apr-config <other options> 366 367However a correctly built Apache shouldn't require the 368C<L<MP_APR_CONFIG|/MP_APR_CONFIG>> option, since 369C<L<MP_APXS|/MP_APXS>> should provide the location of this script. 370 371If however all Apache 2.0 files were installed under the same 372directory, mod_perl 2.0's build only needs to know the path to that 373directory, passed via the C<L<MP_AP_PREFIX|/MP_AP_PREFIX>> option: 374 375 % perl Makefile.PL MP_AP_PREFIX=$HOME/httpd/prefork 376 377=head3 Static mod_perl 378 379Before you proceed make sure that Apache 2.0 has been downloaded and 380extracted. mod_perl B<cannot> be built before that. 381 382If this is an svn checkout and not an official distribution tarball, 383you need to first run: 384 385 % cd httpd-2.0 386 % ./buildconf 387 388To enable statically linking mod_perl into Apache, use the 389C<L<MP_USE_STATIC|/MP_USE_STATIC>> flag like this: 390 391 % perl Makefile.PL MP_USE_STATIC=1 \ 392 MP_AP_PREFIX=$HOME/src/httpd-2.x \ 393 MP_AP_CONFIGURE="--with-mpm=prefork" 394 395C<L<MP_AP_PREFIX|/MP_AP_PREFIX>> B<must> point to an extracted Apache 3962.0 source tree. 397 398This will configure Apache by passing C<L<MP_AP_CONFIGURE|/MP_AP_CONFIGURE>> 399to Apache's F<./configure> script. 400 401Here is an example: 402 403 % cd ~/src 404 % tar -xvzf perl-5.8.x.tar.gz 405 % cd perl-5.8.x 406 % ./Configure -des 407 % make install 408 % cd .. 409 % tar -xvzf httpd-2.0.xx.tar.gz 410 % tar -xvzf mod_perl-2.x.x.tar.gz 411 % perl5.8.x Makefile.PL \ 412 MP_USE_STATIC=1 \ 413 MP_AP_PREFIX="$HOME/src/httpd-2.0.xx" \ 414 MP_AP_CONFIGURE="--with-mpm=prefork" 415 % make 416 % make test 417 % make install 418 % ./httpd -l | grep perl 419 mod_perl.c 420 421=head2 mod_perl Build Options 422 423=head3 Boolean Build Options 424 425The following options are boolean and can be set with C<MP_XXX=1> or 426unset with C<MP_XXX=0>, where XXX is the name of the option. 427 428=head4 MP_PROMPT_DEFAULT 429 430Accept default values for all would-be prompts. 431 432=head4 MP_GENERATE_XS 433 434Generate XS code from parsed source headers in I<xs/tables/$httpd_version>. 435Default is 1, set to 0 to disable. 436 437=head4 MP_USE_DSO 438 439Build mod_perl as a DSO (I<mod_perl.so>). This is the default. 440 441=head4 MP_USE_STATIC 442 443Build static mod_perl (I<mod_perl.a>). 444 445=head4 MP_STATIC_EXTS 446 447Build C<Apache2::*.xs> as static extensions. 448 449=head4 MP_USE_GTOP 450 451Link with I<libgtop> and enable I<libgtop> reporting. 452 453=head4 MP_COMPAT_1X 454 455C<MP_COMPAT_1X=1> or a lack of it enables several mod_perl 1.0 456back-compatibility features, which are deprecated in mod_perl 4572.0. It's enabled by default, but can be disabled with 458C<MP_COMPAT_1X=0> during the build process. 459 460When this option is disabled, the following things will happen: 461 462=over 463 464=item * 465 466Deprecated special variable, C<$Apache2::__T> won't be available. Use 467C<${^TAINT}> instead. 468 469=item * 470 471I<$ServerRoot> and I<$ServerRoot/lib/perl> won't be appended to 472C<@INC>. Instead use: 473 474 PerlSwitches -I/path/to/server -I/path/to/server/lib/perl 475 476in I<httpd.conf> or: 477 478 use Apache2::ServerUtil (); 479 use File::Spec::Functions qw(catfile); 480 push @INC, catfile Apache2::ServerUtil::server_root, ""; 481 push @INC, catfile Apache2::ServerUtil::server_root, "lib/perl"; 482 483in I<startup.pl>. 484 485=item * 486 487The following deprecated configuration directives won't be recognized 488by Apache: 489 490 PerlSendHeader 491 PerlSetupEnv 492 PerlHandler 493 PerlTaintCheck 494 PerlWarn 495 496Use L<their 2.0 497equivalents|docs::2.0::user::porting::compat/Configuration_Files_Porting> 498instead. 499 500=back 501 502 503 504=head4 MP_DEBUG 505 506Turn on debugging (C<-g -lperld>) and tracing. 507 508=head4 MP_MAINTAINER 509 510Enable maintainer compile mode, which sets C<MP_DEBUG=1> and adds the 511following C<gcc> flags: 512 513 -DAP_DEBUG -Wall -Wmissing-prototypes -Wstrict-prototypes \ 514 -Wmissing-declarations \ 515 516If gcc version 3.3.2+ is found, not compiling on OpenBSD, 517and C<-Wdeclaration-after-statement> is 518not already part of the C<gcc> flags add it. 519 520To use this mode Apache must be build with 521C<--enable-maintainer-mode>. 522 523=head4 MP_TRACE 524 525Enable tracing 526 527 528=head3 Non-Boolean Build Options 529 530set the non-boolean options with MP_XXX=value. 531 532=head4 MP_APXS 533 534Path to C<apxs>. For example if you've installed Apache 2.0 under 535I</home/httpd/httpd-2.0> as DSO, the default location would be 536I</home/httpd/httpd-2.0/bin/apxs>. 537 538=head4 MP_AP_CONFIGURE 539 540The command-line arguments to pass to httpd's configure script. 541 542=head4 MP_AP_PREFIX 543 544Apache installation prefix, under which the I<include/> directory with 545Apache C header files can be found. For example if you've installed 546Apache 2.0 in directory I<\Apache2> on Win32, you should use: 547 548 MP_AP_PREFIX=\Apache2 549 550If Apache is not installed yet, you can point to the Apache 2.0 source 551directory, but only after you've built or configured Apache in it. For 552example: 553 554 MP_AP_PREFIX=/home/stas/apache.org/httpd-2.0 555 556Though in this case C<make test> won't automatically find C<httpd>, 557therefore you should run C<t/TEST> instead and pass the location of 558C<apxs> or C<httpd>, e.g.: 559 560 % t/TEST -apxs /home/stas/httpd/prefork/bin/apxs 561 562or 563 564 % t/TEST -httpd /home/stas/httpd/prefork/bin/httpd 565 566 567 568 569=head4 MP_AP_DESTDIR 570 571This option exists to make the lives of package maintainers easier. If 572you aren't a package manager you should not need to use this option. 573 574Apache installation destination directory. This path will be prefixed 575to the installation paths for all Apache-specific files during C<make 576install>. For instance, if Apache modules are normally installed into 577I</path/to/httpd-2.0/modules/> and C<MP_AP_DESTDIR> is set to 578I</tmp/foo>, the I<mod_perl.so> will be installed in: 579 580 /tmp/foo/path/to/httpd-2.0/modules/mod_perl.so 581 582 583 584=head4 MP_APR_CONFIG 585 586If APR wasn't installed under the same file tree as httpd, you may 587need to tell the build process where it can find the executable 588C<apr-config>, which can then be used to figure out where the apr and 589aprutil I<include/> and I<lib/> directories can be found. 590 591=head4 MP_CCOPTS 592 593Add to compiler flags, e.g.: 594 595 MP_CCOPTS=-Werror 596 597(Notice that C<-Werror> will work only with the Perl version 5.7 and 598higher.) 599 600=head4 MP_OPTIONS_FILE 601 602Read build options from given file. e.g.: 603 604 MP_OPTIONS_FILE=~/.my_mod_perl2_opts 605 606=head4 MP_APR_LIB 607 608On Win32, in order to build the APR and APR::* modules so as to 609be independent of mod_perl.so, a static library is first built 610containing the needed functions these modules link into. The option 611 612 MP_APR_LIB=aprext 613 614specifies the name that this library has. The default used 615is C<aprext>. This option has no effect on platforms other than 616Win32, as they use a different mechanism to accomplish the 617decoupling of APR and APR::* from mod_perl.so. 618 619=head3 mod_perl-specific Compiler Options 620 621=head4 -DMP_IOBUFSIZE 622 623Change the default mod_perl's 8K IO buffer size, e.g. to 16K: 624 625 MP_CCOPTS=-DMP_IOBUFSIZE=16384 626 627=head3 mod_perl Options File 628 629Options can also be specified in the file I<makepl_args.mod_perl2> or 630I<.makepl_args.mod_perl2>. The file can be placed under C<$ENV{HOME}>, 631the root of the source package or its parent directory. So if you 632unpack the mod_perl source into I</tmp/mod_perl-2.x/> and your home is 633I</home/foo/>, the file will be searched in: 634 635 /tmp/mod_perl-2.x/makepl_args.mod_perl2 636 /tmp/makepl_args.mod_perl2 637 /home/foo/makepl_args.mod_perl2 638 /tmp/mod_perl-2.x/.makepl_args.mod_perl2 639 /tmp/.makepl_args.mod_perl2 640 /home/foo/.makepl_args.mod_perl2 641 642If the file specified in C<MP_OPTIONS_FILE> is found the 643I<makepl_args.mod_perl2> will be ignored. 644 645Options specified on the command line override those from 646I<makepl_args.mod_perl2> and those from C<MP_OPTIONS_FILE>. 647 648If your terminal supports colored text you may want to set the 649environment variable C<APACHE_TEST_COLOR> to 1 to enable the colored 650tracing which makes it easier to tell the reported errors and 651warnings, from the rest of the notifications. 652 653=head2 Re-using Configure Options 654 655Since mod_perl remembers what build options were used to build it if 656first place, you can use this knowledge to rebuild itself using the 657same options. Simply C<chdir(1)> to the mod_perl source directory and 658run: 659 660 % cd modperl-2.x. 661 % perl -MApache2::Build -e rebuild 662 663 664 665=head2 Compiling mod_perl 666 667Next stage is to build mod_perl: 668 669 % make 670 671 672 673=head2 Testing mod_perl 674 675When mod_perl has been built, it's very important to test that 676everything works on your machine: 677 678 % make test 679 680If something goes wrong with the test phase and want to figure out how 681to run individual tests and pass various options to the test suite, 682see the corresponding sections of L<the bug reporting 683guidelines|docs::2.0::user::help::help/_C_make_test___Failures> or 684the L<Apache::Test 685Framework|docs::general::testing::testing/Running_Tests> tutorial. 686 687=head2 Installing mod_perl 688 689Once the test suite has passed, it's a time to install mod_perl. 690 691 % make install 692 693If you install mod_perl system wide, you probably need to become 694I<root> prior to doing the installation: 695 696 % su 697 # make install 698 699 700 701=head1 If Something Goes Wrong 702 703If something goes wrong during the installation, try to repeat the 704installation process from scratch, while verifying all the steps with 705this document. 706 707If the problem persists L<report the 708problem|docs::2.0::user::help::help/Reporting_Problems>. 709 710=head1 Maintainers 711 712Maintainer is the person(s) you should contact with updates, 713corrections and patches. 714 715=over 716 717=item * 718 719Stas Bekman [http://stason.org/] 720 721=back 722 723=head1 Authors 724 725=over 726 727=item * 728 729Stas Bekman [http://stason.org/] 730 731=item * 732 733Doug MacEachern E<lt>dougm (at) covalent.netE<gt> 734 735=back 736 737Only the major authors are listed above. For contributors see the 738Changes file. 739 740 741=cut 742