perl-docs-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From s...@apache.org
Subject cvs commit: modperl-docs/src/docs/1.0/win32 Changes.pod binaries.pod compile.pod multithread.pod config.cfg win32_binaries.pod win32_compile.pod win32_multithread.pod
Date Wed, 20 Mar 2002 17:43:29 GMT
stas        02/03/20 09:43:29

  Modified:    src/docs/1.0/win32 config.cfg
  Added:       src/docs/1.0/win32 Changes.pod binaries.pod compile.pod
                        multithread.pod
  Removed:     src/docs/1.0/win32 win32_binaries.pod win32_compile.pod
                        win32_multithread.pod
  Log:
  - using a consistent pages layout
  - adding the Description header where needed (for the benefit of index
    pages)
  - adding the Changes.pod file for the docset
  
  Revision  Changes    Path
  1.2       +11 -11    modperl-docs/src/docs/1.0/win32/config.cfg
  
  Index: config.cfg
  ===================================================================
  RCS file: /home/cvs/modperl-docs/src/docs/1.0/win32/config.cfg,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- config.cfg	5 Jan 2002 19:20:01 -0000	1.1
  +++ config.cfg	20 Mar 2002 17:43:28 -0000	1.2
  @@ -1,17 +1,17 @@
   use vars qw(@c);
   @c = (
  -      id => 'win32',
  +    id => 'win32',
   
  -      title => "mod_perl on Win32",
  +    title => "mod_perl on Win32",
   
  -      abstract => 'Various documents assisting mod_perl users on Win32
  -                   platforms',
  +    abstract => <<EOB,
  +Various documents assisting mod_perl users on Win32 platforms
  +EOB
   
  -      chapters => [
  -          qw(
  -             win32_binaries.pod
  -             win32_compile.pod
  -             win32_multithread.pod
  -            ),
  -      ],
  +    chapters => [qw(
  +        binaries.pod
  +        compile.pod
  +        multithread.pod
  +        Changes.pod
  +    )],
   );
  
  
  
  1.1                  modperl-docs/src/docs/1.0/win32/Changes.pod
  
  Index: Changes.pod
  ===================================================================
  =head1 NAME
  
  CHANGES
  
  =head1 Description
  
  Refer to this document to learn what changes were made to the
  documents, since you've read these last time.
  
  The most recent changes are listed first.
  
  =head1 Fri Dec 21 12:20:02  SGT 2001
  
  * win32::multithread, win32::binaries and win32::compile initial docs
    submitted by Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/1.0/win32/binaries.pod
  
  Index: binaries.pod
  ===================================================================
  =head1 NAME
  
  win32_binaries - obtaining Apache mod_perl-1.xx binaries for Win32
  
  =head1 DESCRIPTION
  
  This document discusses the two major types of binary packages
  available for Win32 mod_perl - all-in-one Perl/Apache/mod_perl
  binaries, and mod_perl ppm (Perl Package Manager) packages.
  
  =head1 ALL-IN-ONE PACKAGES
  
  There are at least two binary packages for Win32 that contain the
  necessary Perl and Apache binaries:
  
    http://www.indigostar.com/
  
    ftp://theoryx5.uwinnipeg.ca/pub/other/perl-win32-bin-x.x.exe
  
  As well as including a number of non-core modules, both of these
  packages contain mod_perl. See the documentation on the web sites and
  that included with the packages for installation instructions. Both of
  these also include an ActiveState-compatible C<ppm> (Perl Package
  Manager) utility for adding and upgrading modules.
  
  For the adventuresome who want a taste of things to come, a 
  mod_perl-2.0/Apache-2.0 binary distribution based on cvs 
  sources is available from
  ftp://theoryx5.uwinnipeg.ca/pub/other/Apache2.tar.gz.
  See the accompanying F<Apache2.readme> file in this directory for more
  details. Be aware though that, being a pre-release version,
  bugs are most likely present.
  
  =head1 PPM Packages
  
  For users of ActivePerl, available from
  
     http://www.activestate.com/
  
  there are also C<PPM> mod_perl packages available. For this, if you
  don't already have it, get and install the latest Win32 Apache binary
  from
  
     http://httpd.apache.org/
  
  Both ActivePerl and Apache binaries are available as C<MSI> files for
  use by the Microsoft Installer - as discussed on the ActiveState site,
  users of Windows 95 and 98 may need to obtain this.  In installing
  these packages, you may find it convenient when transcribing any
  Unix-oriented documentation to choose installation directories that do
  not have spaces in their names (eg, F<C:\Perl> and F<C:\Apache>).
  
  After installing Perl and Apache, you can then install mod_perl via
  the PPM utility. ActiveState does not maintain mod_perl in the ppm
  repository, so you must get it from a different location other than
  ActiveState's site. One way is simply as (broken over two lines for
  readability)
  
    C:\> ppm install
         http://theoryx5.uwinnipeg.ca/ppmpackages/mod_perl.ppd
  
  Another way, which will be useful if you plan on installing additional
  Apache modules, is to set the repository within the C<ppm> shell
  utility as (the C<set repository ...> command has been broken over two
  lines for readability):
  
     C:\> ppm
     PPM> set repository theoryx5 
           http://theoryx5.uwinnipeg.ca/cgi-bin/ppmserver?urn:/PPMServer
     PPM> install mod_perl
     PPM> set save
     PPM> quit
     C:\>
  
  The C<set save> command saves the C<theoryx5> repository to your PPM
  configuration file, so that future PPM sessions will search this
  repository, as well as ActiveState's, for requested packages.
  
  The mod_perl PPM package also includes the necessary Apache DLL
  C<mod_perl.so>; a post-installation script should be run which will
  offer to copy this file to your Apache modules directory (eg,
  F<C:\Apache\modules>).
  
  Note that the mod_perl package available from this site will always
  use the latest mod_perl sources compiled against the latest official
  Apache release; depending on changes made in Apache, you may or may
  not be able to use an earlier Apache binary. However, in the Apache
  Win32 world it is particularly a good idea to use the latest version,
  for bug and security fixes.
  
  =head1 CONFIGURATION
  
  Add this line to F<C:\Apache\conf\httpd.conf>:
  
   LoadModule perl_module modules/mod_perl.so
  
  Be sure that the path to your Perl binary (eg, F<C:\Perl\bin>) is in
  your C<PATH> environment variable. If you have a C<ClearModuleList> 
  directive enabled in F<httpd.conf>, you may also need to add
  
   AddModule mod_perl.c
  
  See the descriptions of the C<ClearModuleList> and C<AddModule>
  directives in the Apache documents for more details, especially
  concerning the relative order of these and the C<LoadModule> directive.
  
  =head2 Registry scripts
  
  Using C<Apache::Registry> to speed up cgi scripts may be done as
  follows. Create a directory, for example, F<C:\Apache\mod_perl>, which
  will hold your scripts.  Insert then in F<C:\Apache\conf\httpd.conf>
  the following directives:
  
    Alias /mod_perl/ "/Apache/mod_perl/"
    <Location /mod_perl>
       SetHandler perl-script
       PerlHandler Apache::Registry
       Options +ExecCGI
       PerlSendHeader On
    </Location>
  
  whereby the script would be called as
  
     http://localhost/mod_perl/name_of_script
  
  =head2 Hello World
  
  As you will discover, there is much to mod_perl beyond simple speed-up
  of cgi scripts. Here is a simple I<Hello, World> example that
  illustrates the use of mod_perl as a content handler.  Create a file
  F<Hello.pm> as follows:
  
    package Apache::Hello;
    use strict;
    use Apache::Constants qw(OK);
  
    sub handler {
       my $r = shift;
       $r->send_http_header;
       $r->print("<html><body>Hello World!</body></html>\n");
       return OK;
     }
  
    1;
  
  and save it in, for example, the F<C:\Perl\site\lib\Apache\>
  directory. Next put the following directives in
  F<C:\Apache\conf\httpd.conf>:
  
    PerlModule Apache::Hello
    <Location /hello>
       SetHandler perl-script
       PerlHandler Apache::Hello
    </Location>
  
  With this, calls to
  
     http://localhost/hello
  
  will use C<Apache::Hello> to deliver the content.
  
  =head1 APACHE MODULES
  
  The C<theorxy5> repository containing the mod_perl ppm package also
  contains a number of other Apache modules, such as C<Apache::ASP>,
  C<HTML::Embperl>, and C<HTML::Mason>. However, there may be ones you
  find that are not available through a repository; in such cases, you
  might try sending a message to the maintainer of the repository asking
  if a particular package could be included, or you could use the
  C<CPAN.pm> module to fetch, build, and install the module - see
  C<perldoc CPAN> for details.
  
  =head1 SEE ALSO
  
  The I<mod_perl> manpage, the L<Apache> manpage,
  http://perl.apache.org/, especially the guide, http://take23.org/,
  http://httpd.apache.org/, and http://www.activestate.com/.
  
  =head1 Maintainers
  
  Maintainer is the person(s) you should contact with updates,
  corrections and patches.
  
  =over
  
  =item * 
  
  Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>
  
  =back
  
  
  =head1 Authors
  
  =over
  
  =item *
  
  Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>
  
  =back
  
  Only the major authors are listed above. For contributors see the
  Changes file.
  
  
  =cut
  
  
  
  
  1.1                  modperl-docs/src/docs/1.0/win32/compile.pod
  
  Index: compile.pod
  ===================================================================
  =head1 NAME
  
  win32_compile - Apache mod_perl-1.xx installation instructions for Win32
  
  =head1 DESCRIPTION
  
  This document discusses how to build, test, configure and
  install mod_perl under Win32.
  
  =head1 PREREQUISITES
  
  =over 3
  
  patience - mod_perl is considered alpha under Win32.
  
  MSVC++ 5.0+, Apache version 1.3-dev or higher and Perl 5.004_02 or higher.
  
  As of version 1.24_01, mod_perl will build on Win32 ActivePerls
  based on Perl-5.6.x (builds 6xx). For binary compatibility you 
  should use the same compiler in building mod_perl that was used 
  to compile your Perl binary; for ActivePerl, this means using VC++ 6.
  
  =back
  
  =head1 BUILDING
  
  Obtain the mod_perl sources from CPAN:
  
    http://www.cpan.org/authors/id/D/DO/DOUGM/mod_perl-1.xx.tar.gz
  
  When unpacked, using Winzip or similar tools, a subdirectory
  F<mod_perl-1.xx> will be created.
  
  There are two ways to build mod_perl - with MS Developer Studio,
  and through command-line arguments to 'perl Makefile.PL'. In both
  cases Apache should previously have been built and installed - if
  you are using a binary build of Apache, make sure that you obtain
  a binary build that includes the Apache libraries and header files.
  
  =head2 Building with MS Developer Studio
  
  =over 3
  
  =item Setup the Perl side
  
  Run, from a DOS window in the top-level directory of the 
  mod_perl sources,
  
    perl Makefile.PL
    nmake
  
  This will set up the Perl side of mod_perl for the library build.
  
  =item Build mod_perl.so
  
  Using MS developer studio, 
  
   select "File -> Open Workspace ...", 
   select "Files of type [Projects (*.dsp)]"
   open mod_perl-x.xx/src/modules/win32/mod_perl.dsp
  
  =item Settings
  
   select "Tools -> Options -> [Directories]"
   
   select "Show directories for: [Include files]", and add
   
     C:\Apache\include
     .  (should expand to C:\...\mod_perl-x.xx\src\modules\perl)
     C:\Perl\lib\Core
  
   select "Project -> Add to Project -> Files", adding:
   
     perl.lib (or perl56.lib)   (e.g. C:\perl\lib\Core\perl.lib)
     ApacheCore.lib (e.g. C:\Apache\ApacheCore.lib)
  
   select "Build -> Set Active Configuration -> [mod_perl - Win32 Release]"
  
   select "Build -> Build mod_perl.so"
  
  You may see some harmless warnings, which can be reduced (along with
  the size of the DLL), by setting:
  
   "Project -> Settings -> [C/C++] -> Category: [Code Generation] -> 
    Use runtime library: [Multithreaded DLL]
  
  =item Testing
  
  Once mod_perl.so is built you may test mod_perl with:
  
     nmake test
  
  after which, assuming the tests are OK,
  
     nmake install
  
  will install the Perl side of mod_perl. The mod_perl.so file
  built under F<mod_perl-1.xx/src/modules/win32/Release> should
  be copied to your Apache modules directory (eg, F<C:\Apache\modules>).
  
  =back
  
  =head2 Building with arguments to C<perl Makefile.PL>
  
  Generating the Makefile as, for example,
  
   perl Makefile.PL APACHE_SRC=\Apache INSTALL_DLL=\Apache\modules
  
  will build mod_perl (including mod_perl.so) entirely from 
  the command line. The arguments accepted include
  
  =over 3
  
  =item APACHE_SRC
  
  This can be one of two values: either the path to the Apache build
  directory (eg, F<..\apache_1.3.xx>), or to the installed Apache location
  (eg, F<\Apache>). This is used to set the locations of ApacheCore.lib
  and the Apache header files.
  
  =item INSTALL_DLL
  
  This gives the location of where to install mod_perl.so
  (eg, F<\Apache\modules>). No default is assumed - if this argument
  is not given, mod_perl.so must be copied manually.
  
  =item DEBUG
  
  If true (DEBUG=1), a Debug version will be built (this assumes
  that a Debug Apache has been built). If false, or not given, 
  a Release version will be built.
  
  =item EAPI
  
  If true (EAPI=1), EAPI (Extended API) will be defined when
  compiling. This is useful when building mod_perl against mod_ssl 
  patched Apache sources. If false, or not given, EAPI will
  not be defined.
  
  =back
  
  After this, running
  
     nmake
     nmake test
     nmake install
  
  will complete the installation.
  
  This latter method of building mod_perl will also install the
  Apache and mod_perl header files, which can then be accessed
  through the Apache::src module.
  
  =head1 CONFIGURATION
  
  Add this line to F<C:\Apache\conf\httpd.conf>:
  
   LoadModule perl_module modules/mod_perl.so
  
  Be sure that the path to your Perl binary (eg, F<C:\Perl\bin>)
  is in your C<PATH> environment variable. If you have a C<ClearModuleList> 
  directive enabled in F<httpd.conf>, you may also need to add
  
   AddModule mod_perl.c
  
  See the descriptions of the C<ClearModuleList> and C<AddModule>
  directives in the Apache documents for more details, especially
  concerning the relative order of these and the C<LoadModule> directive.
  
  =head1 SEE ALSO
  
  The I<mod_perl> manpage, the L<Apache> manpage,
  http://perl.apache.org/, especially the guide, and http://take23.org/.
  
  =head1 Maintainers
  
  Maintainer is the person(s) you should contact with updates,
  corrections and patches.
  
  =over
  
  =item * 
  
  Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>
  
  =back
  
  
  =head1 Authors
  
  =over
  
  =item *
  
  Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>
  
  =back
  
  Only the major authors are listed above. For contributors see the
  Changes file.
  
  
  =cut
  
  
  
  1.1                  modperl-docs/src/docs/1.0/win32/multithread.pod
  
  Index: multithread.pod
  ===================================================================
  =head1 NAME
  
  win32_multithread - discussion of multithreading on Win32 mod_perl-1.xx
  
  =head1 DESCRIPTION
  
  This document discusses the multithreading limitations of
  mod_perl-1.xx on Win32.
  
  =head1 The problem
  
  On Win32, mod_perl is effectively single threaded. What this
  means is that a single instance of the interpreter is created,
  and this is then protected by a server-wide lock that prevents
  more than one thread from using the interpreter at any one time.
  The fact that this will prevent parallel processing of requests,
  including static requests, can have serious implications for
  production servers that often must handle concurrent or
  long-running requests.
  
  This situation will change with Apache/mod_perl 2.0, which is
  based on a multi-process/multi-thread approach using a native
  Win32 threads implementation. See
  http://perl.apache.org/~dougm/modperl_2.0.html for details.
  
  At the time of writing, Apache-2.0 is in a beta stage of
  development. mod_perl-2.0 is being actively developed, including the
  Win32 port; if you would like a preview and/or would like to
  contribute to the development process, see the documents on obtaining
  mod_perl-2.0 by cvs, which can be obtained from mod_perl's home page
  at http://perl.apache.org/. Alternatively, a
  mod_perl-2.0/Apache-2.0 binary distribution based on these cvs 
  sources is available from
  ftp://theoryx5.uwinnipeg.ca/pub/other/Apache2.tar.gz.
  See the accompanying F<Apache2.readme> file in this directory for more
  details. Be aware though that, being a pre-release version,
  bugs are most likely present.
  
  =head1 Does it really matter?
  
  How serious is this? For some people and application classes it may be a 
  non-problem, assuming the static material issue is handled differently.
  
  Low traffic and single user development sites will likely be
  unaffected (though the lattest are likely to experience some surprises
  when moving to an environment where requests are no longer serialized
  and concurrency kicks in).
  
  If your application is CPU bound, and all requests take roughly the
  same time to complete, then having more processing threads than
  processors (CPUs) will actually slow things down, because of the
  context switching overhead. Note that, even in this case, the current
  state of mod_perl will bar owners of multiprocessor Win32 machines
  from gaining any load balancing advantage from their superior hardware.
  
  On the other hand, applications dealing with a large service times
  spread - say ranging from fractions of a second to a minute and above
  - stand to lose a great deal of responsiveness from being single
  threaded. The reason is that short requests that happen to be queueued
  after long ones will be delayed for the entire duration of the "jobs"
  that precede them in the queue; with multitasking they would get a chance 
  to complete much earlier.
  
  =head1 Workarounds
  
  If you need multithreading on Win32, either because your application
  has long running requests, or because you can afford multiprocessor
  hardware, and assuming you cannot switch operating systems, you may
  want to consider a few workarounds and/or alternatives - which do not
  require waiting for 2.0.
  
  You may be able to make Win32 multithreading a non-issue by tuning or
  rearranging your application and your architecture (useful tips on
  both counts can be found elsewhere in this document). You may be able
  to significantly reduce your worst-case timing problems or you may
  find that you can move the webserver to a more mod_perl friendly
  operating system by using a multi-tier scheme.
  
  If your application needs the full power of the Apache modules (often
  the case for people running outside Apache::Registry) you may want to
  consider a multi-server load balancing setup which uses mod_rewrite
  (or a similar URL partitioning scheme) to spread requests to several web
  servers, listening on different ports. 
  
  The mod_proxy dual server setup, discussed in the "Strategy" section,
  is also a possibility, although people who have tried it have reported
  problems with Win32 mod_proxy.
  
  If you code to Apache::Registry (writing CGI compliant code) and can
  characterize the time demanded by a request from its URL, you can use
  a rewrite-based load balancing with a single server, by sending short
  requests to mod_perl while routing longer ones to the pure CGI
  environment - on the basis that startup, compilation and init times
  will matter less in this case.
  
  If none of the above works for you, then you will have to turn to some
  non mod_perl alternatives: this, however, implies giving up on most of
  the flexibility of the Apache modules.
  
  For CGI compliant scripts, two possible (portable) alternatives which
  are supported in an Apache/perl environment are straight CGI and
  FastCGI. In theory a CGI application that runs under mod_perl should
  have very few or no problems to run under straight CGI (though its
  performance may be unacceptable). A FastCGI port should also be
  relatively painless. However, as always, your mileage may vary.
  
  If you do not mind replacing Apache with IIS/PWS, you may want
  to experiment with ActiveState's value added PerlEx extension, which
  speeds up CGI scripts much in a way similar to what FastCGI
  does. PerlEx is transparently supported by CGI.pm, so users of this
  package should be more or less covered. (A IIS-FastCGI accelerator is,
  regrettably, no longer available.)
  
  =head1 SEE ALSO
  
  http://perl.apache.org and http://httpd.apache.org, especially the
  discussion of Apache-2 and modperl-2.
  
  =head1 Maintainers
  
  Maintainer is the person(s) you should contact with updates,
  corrections and patches.
  
  =over
  
  =item * 
  
  Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>
  
  =back
  
  
  =head1 Authors
  
  =over
  
  =item *
  
  Randy Kobes E<lt>randy@theoryx5.uwinnipeg.caE<gt>
  
  =back
  
  Only the major authors are listed above. For contributors see the
  Changes file.
  
  
  =cut
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-cvs-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-cvs-help@perl.apache.org


Mime
View raw message