tools/page-loader/README.txt

   1 #
   2 # ***** BEGIN LICENSE BLOCK *****
   3 # Version: MPL 1.1/GPL 2.0/LGPL 2.1
   4 #
   5 # The contents of this file are subject to the Mozilla Public License Version
   6 # 1.1 (the "License"); you may not use this file except in compliance with
   7 # the License. You may obtain a copy of the License at
   8 # http://www.mozilla.org/MPL/
   9 #
  10 # Software distributed under the License is distributed on an "AS IS" basis,
  11 # WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12 # for the specific language governing rights and limitations under the
  13 # License.
  14 #
  15 # The Original Code is Mozilla page-loader test, released Aug 5, 2001.
  16 #
  17 # The Initial Developer of the Original Code is
  18 # Netscape Communications Corporation.
  19 # Portions created by the Initial Developer are Copyright (C) 2001
  20 # the Initial Developer. All Rights Reserved.
  21 #
  22 # Contributor(s):
  23 #   John Morrison <jrgm@netscape.com>, original author
  24 #   Heikki Toivonen <heikki@netscape.com>
  25 #
  26 # Alternatively, the contents of this file may be used under the terms of
  27 # either the GNU General Public License Version 2 or later (the "GPL"), or
  28 # the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  29 # in which case the provisions of the GPL or the LGPL are applicable instead
  30 # of those above. If you wish to allow use of your version of this file only
  31 # under the terms of either the GPL or the LGPL, and not to allow others to
  32 # use your version of this file under the terms of the MPL, indicate your
  33 # decision by deleting the provisions above and replace them with the notice
  34 # and other provisions required by the GPL or the LGPL. If you do not delete
  35 # the provisions above, a recipient may use your version of this file under
  36 # the terms of any one of the MPL, the GPL or the LGPL.
  37 #
  38 # ***** END LICENSE BLOCK *****
  39
  40 Rough notes on setting up this test app. jrgm@netscape.com 2001/08/05
  41
  42 1) this is intended to be run as a mod_perl application under an Apache web
  43    server. [It is possible to run it as a cgi-bin, but then you will be paying
  44    the cost of forking perl and re-compiling all the required modules on each
  45    page load].
  46
  47 2) it should be possible to run this under Apache on win32, but I expect that
  48    there are *nix-oriented assumptions that have crept in. (You would also need
  49    a replacement for Time::HiRes, probably by using Win32::API to directly
  50    call into the system to Windows 'GetLocalTime()'.)
  51
  52 3) You need to have a few "non-standard" Perl Modules installed. This script
  53    will tell you which ones are not installed (let me know if I have left some
  54    out of this test).
  55
  56 --8<--------------------------------------------------------------------
  57 #!/usr/bin/perl
  58 my @modules = qw{
  59     LWP::UserAgent   SQL::Statement     Text::CSV_XS      DBD::CSV
  60     DBI              Time::HiRes        CGI::Request      URI
  61     MIME::Base64     HTML::Parser       HTML::Tagset      Digest::MD5
  62     };
  63 for (@modules) {
  64     printf "%20s", $_;
  65     eval "use $_;";
  66     if ($@) {
  67         print ", I don't have that.\n";
  68     } else {
  69         print ", version: ", eval "\$" . "$_" . "::VERSION", "\n";
  70     }
  71 }
  72 --8<--------------------------------------------------------------------
  73
  74    For modules that are missing, you can find them at http://www.cpan.org/.
  75    Download the .tar.gz files you need, and then (for the most part) just
  76    do 'perl Makefile.PL; make; make test; make install'.
  77
  78    [Update: 28-Mar-2003] I recently installed Redhat 7.2, as server, which
  79    installed Apache 1.3.20 with mod_perl 1.24 and perl 5.6.0. I then ran the
  80    CPAN shell (`perl -MCPAN -e shell') and after completing configuration, I
  81    did 'install Bundle::CPAN', 'install Bundle::LWP' and 'install DBI' to
  82    upgrade tose modules and their dependencies. These instructions work on OSX
  83    as well, make sure you run the CPAN shell with sudo so you have sufficient
  84    privs to install the files.
  85
  86    CGI::Request seems to have disappeared from CPAN, but you can get a copy
  87    from <http://stein.cshl.org/WWW/software/CGI::modules/> and then install
  88    with the standard `perl Makefile.PL; make; make test; make install'.
  89
  90    To install the SQL::Statement, Text::CSV_XS, and DBD::CSV modules, there is
  91    a bundle available on CPAN, so you can use the CPAN shell and just enter
  92    'install Bundle::DBD::CSV'.
  93
  94    At the end of this, the output for the test program above was the
  95    following.  (Note: you don't necessarily have to have the exact version
  96    numbers for these modules, as far as I know, but something close would be
  97    safest).
  98
  99       LWP::UserAgent, version: 2.003
 100       SQL::Statement, version: 1.005
 101         Text::CSV_XS, version: 0.23
 102             DBD::CSV, version: 0.2002
 103                  DBI, version: 1.35
 104          Time::HiRes, version: 1.43
 105         CGI::Request, version: 2.75
 106                  URI, version: 1.23
 107         MIME::Base64, version: 2.18
 108         HTML::Parser, version: 3.27
 109         HTML::Tagset, version: 3.03
 110          Digest::MD5, version: 2.24
 111
 112 4) There is code to draw a sorted graph of the final results, but I have
 113    disabled the place in 'report.pl' where its use would be triggered (look
 114    for the comment). This is so that you can run this without having gone
 115    through the additional setup of the 'gd' library, and the modules GD and
 116    GD::Graph. If you have those in place, you can turn this on by just
 117    reenabling the print statement in report.pl
 118
 119    [Note - 28-Mar-2003: with Redhat 7.2, libgd.so.1.8.4 is preinstalled to
 120    /usr/lib. The current GD.pm modules require libgd 2.0.5 or higher, but you
 121    use 1.8.4 if you install GD.pm version 1.40, which is available at
 122    <http://stein.cshl.org/WWW/software/GD/old/GD-1.40.tar.gz>. Just do 'perl
 123    Makefile.PL; make; make install' as usual. I chose to build with JPEG
 124    support, but without FreeType, XPM and GIF support. I had a test error when
 125    running 'make test', but it works fine for my purposes. I then installed
 126    'GD::Text' and 'GD::Graph' from the CPAN shell.]
 127
 128 5) To set this up with Apache, create a directory in the cgi-bin for the web
 129    server called e.g. 'page-loader'.
 130
 131 5a) For Apache 1.x/mod_perl 1.x, place this in the Apache httpd.conf file,
 132     and skip to step 5c.
 133
 134 --8<--------------------------------------------------------------------
 135 Alias /page-loader/  /var/www/cgi-bin/page-loader/
 136 <Location /page-loader>
 137 SetHandler  perl-script
 138 PerlHandler Apache::Registry
 139 PerlSendHeader On
 140 Options +ExecCGI
 141 </Location>
 142 --8<--------------------------------------------------------------------
 143
 144     [MacOSX note: The CGI folder lives in /Library/WebServer/CGI-Executables/
 145     so the Alias line above should instead read:
 146
 147       Alias /page-loader/  /Library/WebServer/CGI-Executables/page-loader
 148
 149     Case is important (even though the file system is case-insensitive) and
 150     if you type it incorrectly you will get "Forbidden" HTTP errors.
 151
 152     In addition, perl (and mod_perl) aren't enabled by default. You need to
 153     uncomment two lines in httpd.conf:
 154       LoadModule perl_module        libexec/httpd/libperl.so
 155       AddModule mod_perl.c
 156     (basically just search for "perl" and uncomment the lines you find).]
 157
 158 5b) If you're using Apache 2.x and mod_perl 1.99/2.x (tested with Red Hat 9),
 159     place this in your perl.conf or httpd.conf:
 160
 161 --8<--------------------------------------------------------------------
 162 Alias /page-loader/  /var/www/cgi-bin/page-loader/
 163
 164 <Location /page-loader>
 165 SetHandler perl-script
 166 PerlResponseHandler ModPerl::RegistryPrefork
 167 PerlOptions +ParseHeaders
 168 Options +ExecCGI
 169 </Location>
 170 --8<--------------------------------------------------------------------
 171
 172    If your mod_perl version is less than 1.99_09, then copy RegistryPrefork.pm
 173    to your vendor_perl ModPerl directory (for example, on Red Hat 9, this is
 174    /usr/lib/perl5/vendor_perl/5.8.0/i386-linux-thread-multi/ModPerl).
 175
 176    If you are using mod_perl 1.99_09 or above, grab RegistryPrefork.pm from
 177    http://perl.apache.org/docs/2.0/user/porting/compat.html#C_Apache__Registry___C_Apache__PerlRun__and_Friends
 178    and copy it to the vendor_perl directory as described above.
 179
 180 5c) When you're finished, restart Apache.  Now you can run this as
 181     'http://yourserver.domain.com/page-loader/loader.pl'
 182
 183 6) You need to create a subdirectory call 'db' under the 'page-loader'
 184    directory. This subdirectory 'db' must be writeable by UID that Apache
 185    executes as (e.g., 'nobody' or 'apache'). [You may want to figure out some
 186    other way to do this if this web server is not behind a firewall].
 187
 188 7) You need to assemble a set of content pages, with all images, included JS
 189    and CSS pulled to the same directory. These pages can live anywhere on the
 190    same HTTP server that is running this app. The app assumes that each page
 191    is in its own sub-directory, with included content below that
 192    directory. You can set the location and the list of pages in the file
 193    'urllist.txt'. [See 'urllist.txt' for further details on what needs to be
 194    set there.]
 195
 196    There are various tools that will pull in complete copies of web pages
 197    (e.g. 'wget' or something handrolled from LWP::UserAgent). You should edit
 198    the pages to remove any redirects, popup windows, and possibly any platform
 199    specific JS rules (e.g., Mac specific CSS included with
 200    'document.write("LINK...'). You should also check that for missing content,
 201    or URLs that did not get changed to point to the local content. [One way to
 202    check for this is tweak this simple proxy server to check your links:
 203    http://www.stonehenge.com/merlyn/WebTechniques/col34.listing.txt)
 204
 205    [MacOSX note: The web files live in /Library/WebServer/Documents, so you will
 206    need to modify urllist.txt to have the appropriate FILEBASE and HTTPBASE.]
 207
 208 8) The "hook" into the content is a single line in each top-level document like this:
 209       <!-- MOZ_INSERT_CONTENT_HOOK -->
 210    which should be placed immediately after the opening <HEAD> element. The script uses
 211    this as the way to substitute a BASE HREF and some JS into the page which will control
 212    the exectution of the test.
 213
 214 9) You will most likely need to remove all load event handlers from your
 215    test documents (onload attribute on body and handlers added with
 216    addEventListener).
 217
 218 10) Because the system uses (X)HTML base, and some XML constructs are not
 219     subject to that (for example xml-stylesheet processing instructions),
 220     you may need to provide the absolute path to external resources.
 221
 222 11) If your documents are tranformed on the client side with XSLT, you will
 223     need to add this snippet of XSLT to your stylesheet (and possibly make
 224     sure it does not conflict with your other rules):
 225 --8<--------------------------------------------------------------------
 226 <!-- Page Loader -->
 227 <xsl:template match="html:script">
 228   <xsl:copy>
 229   <xsl:apply-templates/>
 230   </xsl:copy>
 231   <xsl:for-each select="@*">
 232     <xsl:copy/>
 233   </xsl:for-each>
 234 </xsl:template>
 235 --8<--------------------------------------------------------------------
 236     And near the top of your output rules add:
 237        <xsl:apply-templates select="html:script"/>
 238     Finally make sure you define the XHTML namespace in the stylesheet
 239     with "html" prefix.
 240
 241 12) I've probably left some stuff out. Bug jrgm@netscape.com for the missing stuff.