stas 2002/09/02 20:55:49 Modified: src/docs/2.0/user/install install.pod Log: rewrite the installation instructions, bringing them up to date Revision Changes Path 1.29 +162 -70 modperl-docs/src/docs/2.0/user/install/install.pod Index: install.pod =================================================================== RCS file: /home/cvs/modperl-docs/src/docs/2.0/user/install/install.pod,v retrieving revision 1.28 retrieving revision 1.29 diff -u -r1.28 -r1.29 --- install.pod 2 Sep 2002 06:34:51 -0000 1.28 +++ install.pod 3 Sep 2002 03:55:49 -0000 1.29 @@ -1,13 +1,23 @@ =head1 NAME -Installing mod_perl +Installing mod_perl 2.0 =head1 Description This chapter provides an in-depth mod_perl 2.0 installation coverage. + + + + + =head1 Prerequisites +Before building mod_perl 2.0 you need to have its prerequisites +installed. If you don't have them, download and install them first, +using the information in the following sections. Otherwise proceed +directly to the mod_perl building instructions. + The mod_perl 2.0 prerequisites are: =over @@ -51,35 +61,80 @@ =back +=head2 Downloading Stable Release Sources +If you are going to install mod_perl on a production site, you want to +use the officially released stable components. Since the latest stable +versions change all the time you should check for the latest stable +version at the listed below URLs: +=over +=item Perl -=head1 Installing from Source +Download from: I<http://cpan.org/src/README.html> -First of all: +This direct link which symlinks to the latest release should work too: +I<http://cpan.org/src/stable.tar.gz>. - Apache 2.0 doesn't work with mod_perl 1.0. - Apache 1.0 doesn't work with mod_perl 2.0. +For the purpose of examples in this chapter we will use the package +named I<perl-5.8.x.tar.gz>, where I<x> should be replaced with the +real version number. + +=item Apache + +Download from: I<http://www.apache.org/dist/httpd/> + +For the purpose of examples in this chapter we will use the package +named I<httpd-2.x.xx.tar.gz>, where I<x.xx> should be replaced with +the real version number. + + +=back + + + +=head2 Getting Bleeding Edge CVS Sources + +If you really know what you are doing you can use the cvs versions of +the components. Chances are that you don't want to them on a +production site. You have been warned! + +=over + +=item Perl + + # (--delete to ensure a clean state) + % rsync -acvz --delete --force \ + rsync://ftp.linux.activestate.com/perl-current/ perl-current + +If you are re-building Perl after rsync-ing, make sure to cleanup first: + + % make distclean + +before running C<./Configure>. + +You'll also want to install (at least) LWP if you want to fully test +mod_perl. You can install LWP with C<CPAN.pm> shell: + + % perl -MCPAN -e 'install("LWP")' -For Win32 specific details, see the documentation on -L<Win32 installation|docs::2.0::os::win32::install>. -Download the httpd-2.0 and modperl-2.0 tarballs, and extract them in the -same directory. +=item Apache -Or use anoncvs (password is "anoncvs"): +To download the cvs version of httpd-2.0 and bring it to the same +state of the distribution package, execute the following commands: % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login - % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co modperl-2.0 + +The password is "anoncvs". + % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co httpd-2.0 % cd httpd-2.0/srclib % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co apr % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co apr-util % cd .. % ./buildconf - % ./configure --prefix=$HOME/apache-2.0 --with-mpm=prefork - % make && make install Once extracted, whenever you want to sync with the latest httpd-2.0 version and rebuild, run: @@ -87,46 +142,83 @@ % cd httpd-2.0 % cvs up -dP % make distclean && ./buildconf - % ./configure --prefix=$HOME/apache-2.0 --with-mpm=prefork - % make && make install -For bleeding edge Perl: +=back - # (--delete to ensure a clean state) - % rsync -acvz --delete --force \ - rsync://ftp.linux.activestate.com/perl-current/ perl-current - % cd perl-current - % ./Configure -des -Dprefix=$HOME/bleedperl \ - -Dusethreads -Doptimize='-g' -Dusedevel + + +=head2 Condiguring and Installing Prerequisites + +If you don't have the prerequisites installed yet, install them now. + +=over + +=item Perl + + % cd perl-5.8.x + % ./Configure -des -Dusethreads % make && make test && make install - % ln -s $HOME/bleedperl/bin/perl5.x.x $HOME/bleedperl/bin/perl -or otherwise make sure that your perl was built with threads enabled if -you want to use a threaded MPM. +If you want to debug mod_perl segmentation faults, add the +following I<./Configure> options: -If you are re-building Perl after rsync-ing, make sure to cleanup: + -Doptimize='-g' -Dusedevel - % make distclean -before running C<./Configure>. +=item Apache + + % cd httpd-2.x.xx + % ./configure --prefix=$HOME/httpd/prefork --with-mpm=prefork + % make && make install + +=back + + +=head1 Installing mod_perl from Source + +Building from source is the best option, because it ensures a binary +compatibility with Apache and Perl. + +For Win32 specific details, see the documentation on +L<Win32 installation|docs::2.0::os::win32::install>. + +=head2 Downloading the mod_perl Source + +First download the mod_perl source. + +=over + +=item Stable Release -You'll also want to install (at least) LWP into the bleedperl/lib -directory if you want to fully test mod_perl, because normally a -privately installed bleedperl won't find libraries installed in the -normal places; it only looks in it's own lib tree. You can install LWP -with CPAN.pm shell: +Download from: I<http://perl.apache.org/download/> - % $HOME/bleedperl/bin/perl -MCPAN -e 'install("LWP")' +This direct link which symlinks to the latest release should work too: +I<http://perl.apache.org/dist/mod_perl-2.0-current.tar.gz>. +For the purpose of examples in this chapter we will use the package +named I<mod_perl-2.x.xx.tar.gz>, where I<x.xx> should be replaced with +the real version number. -=head1 Compiling +=item CVS Bleeding-Edge Version -=head2 Create the build environment +To download the cvs version of modperl-2.0 execute the following +commands: + + % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic login + +The password is "anoncvs". + + % cvs -d :pserver:[EMAIL PROTECTED]:/home/cvspublic co modperl-2.0 + +=back + + + +=head2 Configuring mod_perl % cd modperl-2.0 - % perl Makefile.PL MP_AP_PREFIX=/home/stas/httpd/prefork \ + % perl Makefile.PL MP_AP_PREFIX=$HOME/httpd/prefork \ MP_INST_APACHE2=1 - % make XXX: MP_INST_APACHE2=1 should become the default @@ -281,7 +373,7 @@ MP_CCOPTS=-DMP_IOBUFSIZE=16384 -=head3 Options File +=head3 mod_perl Options File Options can also be specified in the file I<makepl_args.mod_perl2> or I<.makepl_args.mod_perl2>. The file can be placed under C<$ENV{HOME}>, @@ -307,53 +399,49 @@ tracing which makes it easier to tell the reported errors and warnings, from the rest of the notifications. -=head2 Compile mod_perl - % make +=head2 Re-using Configure Options -=head2 Configure and compile Apache +Since mod_perl remembers what build options were used to build it if +first place, you can use this knowledge to rebuild itself using the +same options. Simply C<chdir(1)> to the mod_perl source directory and +run: - % cd ../httpd-2.0 - % ./configure --with-mpm=prefork - % make + % cd modperl-2.x.xx + % perl -MApache::Build -e rebuild -=head2 Test mod_perl - % make test -L<Apache::Test Framework|docs::general::testing::testing> document covers the -C<make test> suite. +=head2 Compiling mod_perl -META: probably need to link directly to the 'Running Tests' section. +Next stage is to build mod_perl: -=head2 Howto generate source tables + % make -All mod_perl-2.0 xs code is generated from parsed header files. While -in pre-release mode, a version of these tables will be checked in to -I<xs/tables/current>. Should you wish to update these tables, here's -how: -NOTE: requires C::Scan 0.75, which at the moment is unreleased, there -is a working copy here: http://perl.apache.org/~dougm/Scan.pm -NOTE: source_scan.pl is a HEAVY process, do not be alarmed. +=head2 Testing mod_perl - % perl build/source_scan.pl apxs $apache_prefix/bin/apxs +When mod_perl has been built, it's very important to test that +everything works on your machine: -META: this is covered in L<Core -Explained|devel::core_explained::core_explained> should probably -move/point there. + % make test -=head2 Re-using Build Options +If something goes wrong with the test phase and want to figure out how +to run individual tests and pass various options to the test suite, +refer to the L<Apache::Test +Framework|docs::general::testing::testing/Running_Tests> manual. -Since mod_perl remembers what build options were used to build it, you -can use this knowledge to rebuild itself using the same -options. Simply chdir(1) to the mod_perl source directory and run: +=head2 Installing mod_perl - % cd modperl-2.0 - % perl -MApache::Build -e rebuild +Once the test suite has passed, it's a time to install mod_perl. -=head1 Installing from Binary Packages + % make install + +If you install mod_perl system wide, you probably need to become +I<root> prior to doing the installation. + +=head1 Installing mod_perl from Binary Packages As of this writing only the binaries for the Win32 platform are available, kindly prepared and maintained by Randy Kobes. @@ -369,13 +457,17 @@ =item * -Doug MacEachern E<lt>dougm (at) covalent.netE<gt> +Stas Bekman E<lt>stas (at) stason.orgE<gt> =back =head1 Authors =over + +=item * + +Stas Bekman E<lt>stas (at) stason.orgE<gt> =item *
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
