# Readme for using HTML::Mason in XCGI scripts running under Stunnix Perl Web Server

## Running a sample

In order to run this sample no Perl interpreter and any Mason-related modules are required for Windows platform and for Linux on computers with x86 CPU. Running CDROM on other platforms requires Perl interpreter to be installed (but no HTML::Mason and any of its dependacies need to be installed of course).

If the CD is burned directly from this tree, then inserting it into the CDROM tray on Windows will start the site automatically. On Unix-like OSes running Gnome or KDE desktop environment the prompt to run a cd will appear if desktop environment is configured properly.

To run a site without burning CDROM, one can just execute 'autorun' script on Unix-like OSes (it's a shell script) or doubleclick on 'runcd.js' on Windows. To run CDROM on MacOSX, doubleclick on 'runcd-macosx.command' (perl is already preinstalled on MacOSX).

When Mason-based site is run, all Mason modules are loaded only once after first access to the URL that needs to be handled with Mason similar to how Mason works in mod_perl or mod_fastcgi environment.

There is a "lean" package with the same site, but without Perl interpreters and Mason modules available for download at a dedicated page on Stunnix Website.

## Using a sample as a template for your Mason-based site

- Put a purchased perl modules of Stunnix Perl Web Server to 'site/stunnixwebsrv/' (replacing all corresponding files);
- Put all static content to 'www/root';
- Put all Mason components to 'site/www/apps/mason-components' (if you wish to put put components to the $DOCUMENT_ROOT, put them to 'site/www/root' and disable passing parameter 'comp_root' in the construction of 'HTML::Mason::CGIHandler' in the 'site/www/apps/lib/mason.pm';
- If you need to alter parameters passed to 'HTML::Mason::CGIHandler', update 'site/www/apps/lib/mason.pm';
- Edit last portion of 'site/stunnixwebsrv/httpd.conf' - the regular expression in 'LocationMatch' - to reflect the expression for selecting all files with mason components (in this sample, all files with '.zzhtml' extension are treated as Mason components and handled by Mason handler)
- Don't forget to remove this .html file.

## Notes

The entire tree with HTML::Mason and all its dependancies is located in 'site/www/apps/deps-fallbacks' - unmodified versions of all Mason-related modules without any architecture-specific (i.e. compiled) code are present there. A modified version of HTML::Entities is located in 'site/www/apps/deps-unique' - it's modified in order not to depend on HTML::Parser (that requires compiled code). Strictly speaking, Digest::SHA1 (required by Cache::FileBackend) has implementation of its algorithms partially as compiled code (that is not included in 'site/www/apps/deps-fallbacks'!) but it turns out that 'Cache::FileBackend' is not used in the default configuration of Mason, so no problems arise.