README modperlize

How to transform twiki beta20040507

- without using global variables

- multiple configurations

using modperl2

what transformation does

how to use this package

requirements to transform twiki with other plugins

transform twiki without using global variables

transform twiki without using global variables and install it with modperl2

install twiki with multiple configurations

transform other versions of twiki

benchmark

benchmark twiki
benchmark twiki without using global variables
benchmark twiki without using global variables on modperl2
conclusions

-why

Transforming global variables in local variables prevents conflits between multiple twiki session opened on an Apache server with mod_perl. So twiki installation with multiple configuration becomes possible and stable.

Moreover having multiple configurations working on the same web server without conflits also allows you to reduce the number of processes and web server instances running on a single system.

-what transformation does

-All global variables are substituted with local variables named as
$$config{<package_name_of_global_var>::<global_var_name>}.
The $config variable is an address to a hash where each key refer to a single twiki global variable.
Example: the global variable "templateDir" of the package "TWiki.pm", will be replaced with "$$config{'TWiki::templateDir'}".

- $config variable is added as first parameter to all subroutine calls to make these local variables visible, i.e.: following subroutine call

writeHeaderFull($query, 'basic', 'text/html', 0);

will be replaced with

writeHeaderFull($config, $query, 'basic', 'text/html', 0);

All changes of values of $config keys are visible to every subroutine using it.

-In every subroutine, the value of this new parameter is saved to a local variable named $config.

-A new subroutine called init_config has been created to contain global variable initializations not included in any subroutine ( the same for code in BEGIN blocks ).

-The .pm files composed of several packages, generate a single file for each package. For example the file Prefs.pm generates the files Prefs.pm , Prefs/PrefsCache.pm, Prefs/TopicPrefs.pm.

-how to use this package

This package contains a modified version of TWiki ( beta20040507 version ) transformed to use local variables instead of global variables ( tested on a Red Hat 9 ), it is composed of:
- the directories ./bin and ./lib
- some configuration files
(NOTE: The name of the url and the name of configuration files are strictly related )

- lib/alphaPort80twikimodperl.pm will deploy http://alpha:80/twikimodperl/bin/view
(twiki code have to be installed in the directory /home/httpd/twikimodperl )

- lib/alphaPort80twikinoglob.pm will deploy http://alpha:80/twikinoglob/bin/view
(twiki code have to be installed in the directory /home/httpd/twikinoglob )

The package also contains :
- modperlizebeta20040507.pl and twiki.diff.beta20040507 used to "transform" the original twikibeta20040507. You can use them to transform also your own twiki code as described in this document.
- READMEbeta20040507modperlize.html (this document)

To use this package you need to:

copy twiki directory in twikimodperl

cd /home/httpd/
cp -r twiki twikimodperl

untar package in /home/httpd/twikimodperl/

cd /home/httpd/twikimodperl/

tar --recursive-unlink -xvzf twikimodperlizebeta20040507.tar.gz ./bin ./lib

check that all files in bin directory have execution permission

modify perl.conf as described in transform twiki without using global variables and install it with modperl2

copy alphaPort80twikimodperl.pm in <your server name>Port<your port>twikimodperl.pm

cd /home/httpd/twikimodperl/lib
cp alphaPort80twikimodperl.pm <your server name>Port<your port>twikimodperl.pm

edit file <your server name>Port<your port>twikimodperl.pm and set correct pubDir, templateDir, dataDir

stop and start Apache

now url http://<your server name>:<your port>/twikimodperl/bin/view is available for browsing.

-requirements to transform twiki with other plugins

You can apply the transformation on your twiki installation ( beta20040507 ) with any installed plugin, you just need to :
-verify Plugin file in lib/TWiki/Plugins/ to check it for local variables name equal to any its global variable name. If you found any, you need to change the name of conflicting local variable.
-with plugins using object classes, methods must use the self variable for properties of the object.

-transform twiki without using global variables

Following this steps it is possible to make a version of your own twiki (beta20040507) without using global variables and run it on a webserver without modperl.
Settings, twiki users, installed plugins will be remain unchanged.
For the plugins verify their prerequisities as described in "requirements to transform twiki with other plugins".

STEPS
------------------
1 - Copy files twiki.diff.beta20040507 and modperlizebeta20040507.pl in the parent directory of twiki

2 - Run ./modperlizebeta20040507.pl
(The script will apply the patch and will ask confirm before continue, so you can check the result of patch process)
During transformation the script shows several messagges on standard output.
Estimated time : few minutes .

3 - Choose A or B :

A: (replace running twiki installation)

backup your twiki directory ( for example you can copy the directory twiki )

replace bin and lib directories with the bin and lib ones just created by step 2 in twiki.modperlOneKey directory.
check that all files in bin directory have execution permission.
create the configuration file lib/twiki.pm : cp TWikicfg.pm twiki.pm

B : (create a new twiki installation inheriting settings, users, etc. )

copy twiki directory in a directory named twikinoglob.
replace bin and lib directories (in twikinoglob) with the bin and lib ones just created by step 2 in twiki.modperlOneKey directory
check that the directory pub, data have write pernission for webserver user.
check that all files in bin directory have execution permission.
modify twikinoglob/lib/TWikicfg.pm file, replacing string twiki with twikinoglob where necessary, use the commands:
```
cd twikinoglob/bin
perl -pi~ -e 's/\/twiki\//\/twikinoglob\//' TWikicfg.pm
```
copy TWikicfg.pm in twikinoglob.pm :

            cp TWikicfg.pm alpahPort80twikinoglob.pm

Add in the configuration file perl.conf:

#
# FOR twiki without global variable
#
 ScriptAlias /twikinoglob/bin/ "/home/httpd/twikinoglob/bin/"
 Alias /twikinoglob/ "/home/httpd/twikinoglob/"
 <Directory "/home/httpd/twikinoglob/bin">
    Options +ExecCGI
    SetHandler cgi-script
    Allow from all
 </Directory>
 <Directory "/home/httpd/twikinoglob/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twikinoglob/data">
    deny from all
 </Directory>
 <Directory "/home/httpd/twikinoglob/templates">
    deny from all
 </Directory>
#

4 - now you can remove twiki.patched and twiki.modperlOneKey directories.

Stop and start Apache. Now url http://alpha:80/twiki/bin/view is available for browsing ( for case B, the url will be http://<hostname>/twikinoglob/bin/view) . Twiki pages will appear as usual, but in twiki/bin/testenv page you can see the new local variable that replaced the global ones, i.e. you can read "$$config{'TWiki::pubDir'}" instead of "pubDir".

-transform twiki without using global variables and install it with modperl2

If you have installed modperl2 , ( included in Linux-Red Hat 9 installation ), you can transform twiki without using global variables using modperl, following described steps.

STEPS
--------------------------
1 - Apply changes as described in steps 1,2: transform twiki without using global variables

2 -

copy twiki directory in a directory named twikimodperl .

replace bin and lib directories (in twikimodperl) with the bin and lib ones just created by step 2 in twiki.modperlOneKey directory

check that all files in bin directory have execution permission.

modify twikinoglob/lib/TWikicfg.pm file, replacing string twiki with twikimodperl where necessary, use the commands:

      cd twikimodperl/lib

      perl -pi~ -e 's/\/twiki\//\/twikimodperl\//' TWikicfg.pm

create configuration file alphaPort80twikimodperl.pm : cp TWikicfg.pm alphaPort80twikimodperl.pm ( this guide assumes "alpha" the name of your name server )

3 - Add in the configuration file perl.conf ( usually you can find it in /etc/httpd/conf.d/ ) :

LoadModule perl_module modules/mod_perl.so
#
# FOR twiki modperl installation and without global variable
#
Alias /twikimodperl /home/httpd/twikimodperl/
<Directory /home/httpd/twikimodperl/bin>
    SetHandler perl-script
    PerlHandler ModPerl::Registry::handler
    PerlOptions +ParseHeaders
    Options +ExecCGI
 </Directory>
 <Directory "/home/httpd/twikimodperl/pub">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twikimodperl/data">
    deny from all
 </Directory>
 <Directory "/home/httpd/twikimodperl/templates">
    deny from all
 </Directory>

4 - now you can remove twiki.patched and twiki.modperlOneKey directories.

Stop and start Apache. Now url http://alpha:80/twikimodperl/bin/view is available for browsing. Twiki pages will appear as usual, but in twikimodperl/bin/testenv page you can see the new local variable that replaced the global ones, i.e. you can read "$$config{'TWiki::pubDir'}" instead of "pubDir", and you can read :

MOD_PERLmod_perl/1.99_07-dev
mod_perl:Used for this script (mod_perl not loaded into Apache) - mod_perl version 1.9907

-install twiki with multiple configurations

When you have a twiki version without using global variable and installed on modperl2, you can define multi configuration files.
The name of the url and the name of configuration files are strictly related; the name of configuration file are composed of:
-the server name
-the server port
-the third string of the url counting from the end and ".pm" .
i.e. url http://alpha:80/twikinoglob2/bin/view will serch for configuration file lib/alphaPort80twikinoglob2.pm.
Following the steps to define multi configurations.

STEPS
--------------------------
1 - Apply all steps described in transform twiki without using global variables and install it with modperl2
2 - Create pub2 data2 and templates2 directory in twikimodperl directory :

Copy pub directory in pub2 , data directory in data2 and templates directory in templates2

check that the directory pub2, data2 have write pernission for webserver user.
create twikimodperl/lib/alphaPort80twikimodperl2.pm file and replace references as described here :

      cd twikimodperl/lib
      cp alphaPort80twikimodperl.pm alphaPort80twikimodperl2.pm
      perl -pi~ -e 's/\/twikimodperl\/bin/\/twikimodperl2\/bin/' alphaPort80twikimodperl2.pm
      perl -pi~ -e 's/\/data/\/data2/' alphaPort80twikimodperl2.pm
      perl -pi~ -e 's/\/pub/\/pub2/' alphaPort80twikimodperl2.pm
      perl -pi~ -e 's/\/templates/\/templates2/' alphaPort80twikimodperl2.pm

3 - Add in the configuration file perl.conf ( usually you can find it in /etc/httpd/conf.d/ ) :

LoadModule perl_module modules/mod_perl.so
#
# FOR twiki modperl installation and without global variable
#
Alias /twikimodperl2 /home/httpd/twikimodperl/
 <Directory "/home/httpd/twikimodperl/pub2">
    Options FollowSymLinks +Includes
    AllowOverride None
    Allow from all
 </Directory>
 <Directory "/home/httpd/twikimodperl/data2">
    deny from all
 </Directory>
 <Directory "/home/httpd/twikimodperl/templates2">
    deny from all
 </Directory>

Stop and start Apache. Now url http://<hostname>/twikimodperl2/bin/view is available for browsing.

-transform other versions of twiki

This trasformation can be applied to different versions of twiki, with the same improvement achieved in beta20040507.
This is possible because modperlizebeta20040507.pl it isn't strictly related to the twiki version ( except for the patch twiki.diff.beta20040507 ).
Steps to transform your twiki:
- run modperlizebeta20040507.pl

- this will apply the patch twiki.diff.beta20040507
- probably this patch won't be able to complete successfully due to different source code
- in this case you need to reply no at the question "Check patching and press y to continue: " prompted by the perl script
- check .rej files created in twiki.patched directory
- make patches rejected by editing manually source in twiki.package directory.
- make the new patch file:
diff -uwbBr twiki twiki.patched > twiki.diff.beta20040507
- run again modperlizebeta20040507.pl

-now go to step 3 in transform twiki without using global variables if you wan't use modperl or step 2 in transform twiki without using global variables and install it with modperl2 if you want use modperl.

-benchmark

As benchmark program has been used "ab", a tool for benchmarking Apache HyperText Transfer Protocol server distibuited with Linux RedHat 9. The command used to perform 500 http requests was :

ab -n 500 http://localhost/twiki/bin/view

-benchmark twiki

The following output is the result of "ab" requesting twiki/bin/view page in a twiki standard installation version beta20040507.

--------------------------------
This is ApacheBench, Version 2.0.40-dev <$Revision: 1.116 $> apache-2.0
Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
Copyright (c) 1998-2002 The Apache Software Foundation, http://www.apache.org/
 
Benchmarking localhost (be patient)
 
 
Server Software:        Apache/2.0.40
Server Hostname:        localhost
Server Port:            80
 
Document Path:          /twiki/bin/view
Document Length:        10038 bytes
 
Concurrency Level:      1
Time taken for tests:   1327.766158 seconds
Complete requests:      500
Failed requests:        0
Write errors:           0
Total transferred:      5110000 bytes
HTML transferred:       5019000 bytes
Requests per second:    0.38 [#/sec] (mean)
Time per request:       2655.532 [ms] (mean)
Time per request:       2655.532 [ms] (mean, across all concurrent requests)
Transfer rate:          3.76 [Kbytes/sec] received
 
Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.1      0       1
Processing:  2569 2654 101.3   2614    3900
Waiting:     2566 2653 101.2   2613    3900
Total:       2569 2654 101.3   2614    3900
 
Percentage of the requests served within a certain time (ms)
  50%   2614
  66%   2681
  75%   2706
  80%   2717
  90%   2736
  95%   2764
  98%   2809
  99%   3089
 100%   3900 (longest request)

 
--------------------------------------------------

-benchmark twiki without using global variables

The following output is the result of "ab" requesting twikinoglob/bin/view page in a twiki version beta20040507 without using global variables , without mod_perl.

------------------------------------------
 This is ApacheBench, Version 2.0.40-dev <$Revision: 1.116 $> apache-2.0
Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
Copyright (c) 1998-2002 The Apache Software Foundation, http://www.apache.org/
 
Benchmarking localhost (be patient)
 
 
Server Software:        Apache/2.0.40
Server Hostname:        localhost
Server Port:            80
 
Document Path:          /twikinoglob/bin/view
Document Length:        10457 bytes
 
Concurrency Level:      1
Time taken for tests:   1391.146694 seconds
Complete requests:      500
Failed requests:        0
Write errors:           0
Total transferred:      5319500 bytes
HTML transferred:       5228500 bytes
Requests per second:    0.36 [#/sec] (mean)
Time per request:       2782.293 [ms] (mean)
Time per request:       2782.293 [ms] (mean, across all concurrent requests)
Transfer rate:          3.73 [Kbytes/sec] received
 
Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.0      0       0
Processing:  2697 2781  93.3   2761    4368
Waiting:     2696 2780  93.4   2758    4367
Total:       2697 2781  93.3   2761    4368
 
Percentage of the requests served within a certain time (ms)
  50%   2761
  66%   2808
  75%   2825
  80%   2833
  90%   2849
  95%   2880
  98%   2927
  99%   3022
 100%   4368 (longest request)


------------------------------------------

-benchmark twiki without using global variables on modperl2

The following output is the result of "ab" requesting twikimodperl/bin/view page in a twiki version beta20040507 without using global variables installed on a server mod_perl.

------------------------------------------------------

 This is ApacheBench, Version 2.0.40-dev <$Revision: 1.116 $> apache-2.0
Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, http://www.zeustech.net/
Copyright (c) 1998-2002 The Apache Software Foundation, http://www.apache.org/
 
Benchmarking localhost (be patient)
 
 
Server Software:        Apache/2.0.40
Server Hostname:        localhost
Server Port:            80
 
Document Path:          /twikimodperl/bin/view
Document Length:        10531 bytes
 
Concurrency Level:      1
Time taken for tests:   832.82634 seconds
Complete requests:      500
Failed requests:        0
Write errors:           0
Total transferred:      5356500 bytes
HTML transferred:       5265500 bytes
Requests per second:    0.60 [#/sec] (mean)
Time per request:       1664.165 [ms] (mean)
Time per request:       1664.165 [ms] (mean, across all concurrent requests)
Transfer rate:          6.29 [Kbytes/sec] received
 
Connection Times (ms)
              min  mean[+/-sd] median   max
Connect:        0    0   0.0      0       0
Processing:  1386 1662 967.0   1461   10405
Waiting:     1328 1659 966.0   1457   10404
Total:       1386 1662 967.0   1461   10405
 
Percentage of the requests served within a certain time (ms)
  50%   1461
  66%   1510
  75%   1561
  80%   1605
  90%   1792
  95%   2112
  98%   4901
  99%   8613
 100%  10405 (longest request)


------------------------------------------------------

-conclusions

Run time with modperl2 are less than standard installation of about 38%.