Copyright (c) 1998-2003 by Jonathan Swartz. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. Welcome to Mason, a Perl-based web site development and delivery system. Mason allows web pages and sites to be constructed from shared, reusable building blocks called components. Components contain a mix of Perl and HTML, and can call each other and pass values back and forth like subroutines. Components increase modularity and eliminate repetitive work: common design elements (headers, footers, menus, logos) can be extracted into their own components where they need be changed only once to affect the whole site. Other Mason features include powerful filtering and templating facilities, and a HTML/data caching model. See http://www.masonhq.com/ for more information. PREREQUISITES Mason requires Perl 5.005 or greater, and the following CPAN modules: * Class::Container * Exception::Class * File::Spec 0.8+ - included in the core as of 5.00504 * File::Spec * Params::Validate * Scalar::Util * Test::More - you could skip this if you don't want to run the tests The following CPAN modules are optional for certain features, but not required: * Either Apache::Request or CGI.pm * Cache::Cache INSTALLATION To install Mason, run the standard sequence: perl Makefile.PL make make install By default, Mason will prompt you for information about where Apache is installed so that it can help you install Mason under mod_perl. If you would like to skip this, invoke the Makefile.PL like this: perl Makefile.PL --no-prompts If you didn't have Mason do this for you, then after Mason is installed, you will need to activate it by adding some directives to your Apache configuration files. The included pod docs have been pre-converted to HTML for you and placed in the htdocs/ directory. The Mason overview (a good place to start) is in Mason.html. WARNINGS! * Don't use Mason with an older mod_perl DSO (dynamic shared object). Using Mason with a mod_perl DSO may cause your Apache server to crash silently at startup, or fail intermittently. The fix for this problem is to install Apache/mod_perl with mod_perl compiled statically into the Apache binary. Packages of Apache with a static mod_perl are available around the net. Testing with recent mod_perls showed improvements, but because this bug can be so intermittent and difficult to spot, mod_perl DSO with Mason is still strictly unsupported. * Don't use Mason with PerlFreshRestart. The mod_perl PerlFreshRestart directive attempts to reload modules on restart in a very simplistic way. Mason cannot be reloaded this way. The Apache::Reload module from CPAN does a much better job, and appears to work with Mason. However, the safest thing to do is to actually stop and start the server. GETTING HELP The official Mason web site is at http://www.masonhq.com/. It's a wiki, so most pages can be edited by any registered user. The official documentation is at http://www.masonhq.com/docs/manual/. The FAQ is at http://www.masonhq.com/?FAQ. Several mailing lists exist for Mason users and developers. Full information can be found at http://www.masonhq.com/?MailingLists. There is a book about Mason, _Embedding Perl in HTML with Mason_, by Dave Rolsky and Ken Williams. This book is published by O'Reilly and Associates. The book's home page is http://www.masonbook.com/, and the entire book is available online. CODE EXAMPLES The samples/ directory contains a few basic components. The Mason site contains a variety of user-contributed code and how-tos; see http://www.masonhq.com/?ContributedCode, for example. Links to various articles containing code examples are listed at http://www.masonhq.com/?Articles. REPORTING BUGS Send bug reports to the user's mailing list for quickest response. But first check the mailing list archives and the official bugs list on the Mason site to see if the problem has already been reported. For all bug reports indicate your architecture, Apache/Perl/module versions, etc. For installation problems send your handler.pl and httpd.conf. For component problems try to isolate the bug in a single small component or set of components, and send those. If you are experiencing test failures, please run the tests like this: make test TEST_VERBOSE=1 and send the output along with the bug report. Otherwise we'll just ask you to do this before we can do anything. See http://www.masonhq.com/?MailingLists for information on the mailing lists. LICENSE Mason was originally developed for the Internet technology group at CMP Media, a publisher of technology magazines. CMP graciously supported our efforts to release Mason as open source software to the Perl community. However, CMP has NO direct involvement with the open source release and bears NO responsibility for its support or maintenance. Mason is provided "as is" and without any express or implied warranties, including, without limitation, the implied warranties of merchantibility and fitness for a particular purpose. Mason is released under the same terms as Perl itself. For more information see the "README" or "Artistic" files provided with the Perl distribution. AUTHORS Jonathan Swartz swartz@pobox.com Dave Rolsky autarch@urth.org Ken Williams ken@mathforum.org