Installing Axkit

AxKit combines the power of Perl’s rich and varied XML processing facilities with the flexibility of the Apache web server. But instead of using a monolithic package, it takes a more modular approach. This allows developers great flexibility in choosing what lower-level packages they want, but it can mean a more lengthy and complicated installation process. This article comes from chapter two of the book XML Publishing with AxKit by Kip Hampton (O’Reilly, 2004; ISBN: 0596002165).

Installing AxKit

AxKit combines the power of Perl’s rich and varied XML processing facilities with the flexibility of the Apache web server. Rather than implementing such an environment in a monolithic package, as some application servers do, it takes a more modular approach. It allows developers to choose the lower-level tools such as XML parsers and XSLT processors for themselves. This neutrality with respect to lower-level tools gives AxKit the ability to adapt and incorporate new, better performing, or more feature-rich tools as quickly as they appear. That flexibility costs, however. You will probably have to install more than just the AxKit distribution to get a working system.

Installation Requirements

To get AxKit up and running, you will need:

  • The Apache HTTP server (Version 1.3.x)

  • The mod_perl Apache extension module (Version 1.26 or above)

  • An XML parser written in Perl or, more commonly, one written in C that offers a Perl interface module

  • The core AxKit distribution

Installing Apache and mod_perl

If you are running an open source or open source–friendly operating system such as GNU/Linux or one of the BSD variants (including Mac OS X), chances are good that you already have Apache and mod_perl installed. If this is the case, then you probably will not have to install them by hand. Simply make sure that you are running the most recent version of each, and skip directly to the next section. However, in some cases, using precompiled binaries of Apache and mod_perl proved to be problematic for people who want to use AxKit. In most cases, neither the binary in question, nor AxKit, are really broken. The problem lies in the fact that binaries built for public distribution are usually compiled with a set of general build arguments, not always well suited for specialized environments such as AxKit. If you find that all AxKit’s dependencies install cleanly, but AxKit’s test suite still fails, you may consider removing the binary versions and installing Apache and mod_perl by hand. At the time of this writing, AxKit runs only under Apache versions in the 1.3. x branch. Support for Apache 2. x is currently in development. Given that Apache 2 is quite different from previous versions, both in style and substance, the AxKit development team decided to take things slowly to ensure that AxKit for Apache 2. x offers the best that the new environment has to offer.

To install Apache and mod_perl from the source, you need to download the source distributions for each from http://httpd.apache.org/ and http://perl.apache.org/, respectively. After downloading, unpack both distributions into a temporary directory and cd into the new mod_perl directory. A complete reference for all options available for building the Apache server and mod_perl is far beyond the scope of this book. The following will get you up and running with a useful set of features:

  $ perl Makefile.PL
  > EVERYTHING=1
  > USE_APACI=1
  > DYNAMIC=1
  > APACHE_SRC=../apache_1.3.xxx/src
  > DO_HTTPD=1
  > APACI_ARGS=”–enable-module=so –enable-shared=info
  > –enable-shared=proxy –enable-shared=rewrite
  > –enable-shared=log_agent”
  $ make
  $ make install

All lines before the make command are build flags that are being passed to perl Makefile.PL. The characters are simply part of the shell syntax that allows you to divide the arguments across multiple lines. The > characters represent the shell’s output, and you should not include them. Also, be sure to replace the value of the APACHE_SRC option with the actual name of the directory into which you just unpacked the Apache source.

XML Processing Options

As I mentioned in the introduction to this chapter, AxKit is a publishing and application framework. It is not an XML parser or XSLT processor, but it allows you to choose among these lower-level tools while ensuring that they work together in a predictable way. If you do not already have the appropriate XML processing tools installed on your server, AxKit attempts to install the minimum needed to serve transformed XML content. However, more cautious minds may prefer to install the necessary XML parser and any optional XSLT libraries to make sure they work before installing the AxKit core. Deciding which XML parsers or other libraries to install depends on your application’s other XML processing needs, but the following dependency list shows which tools AxKit currently supports and which publishing features require which libraries.

Gnome XML parser (libxml2)
Requires: XML::LibXML
Required by AxKit for: eXtensible Server Pages
Available from:
http://xmlsoft.org/
Expat XML parser
Requires: XML::Parser
Required by AxKit for: XPathScript
Available from:
http://sourceforge.net/projects/expat/
Gnome XSLT processor (
libxslt)
Requires: libxml2,XML::LibXSLT
Required by AxKit for: optional XSLT processing
Available from:
http://xmlsoft.org/XSLT/
Sablotron XSLT processor
Requires: Expat, XML::Sablotron
Required by AxKit for: optional XSLT processing
Available from:
http://www.gingerall.com/

You do not need to install all these libraries before installing AxKit. For example, if you plan to do XSLT processing, you need to install either libxslt or Sablotron, not both. However, I do strongly recommend installing both supported XML parsers: Gnome Project’s libxml2 for its speed and modern features, and Expat for its wide use among many popular Perl XML modules. In any case, remember that you must install the associated Perl interface modules for any of the C libraries mentioned above, or AxKit will have no way to access the functionality that they provide.

Again, some operating system distributions include one or more of the libraries mentioned above as part of their basic packages. Be sure to upgrade these libraries before proceeding with the AxKit installation to ensure that you are building against the most recent stable code.

{mospagebreak title=Installing the AxKit Core}

Now that you have an environment for AxKit to work in and have some of the required dependencies installed, you are ready to install AxKit itself. For most platforms this is a fairly painless operation.

Using the CPAN Shell

The quickest way to install AxKit is via Perl’s Comprehensive Perl Archive Network (CPAN) and the CPAN shell. Log in as root (or become superuser) and enter the following:

  $ perl -MCPAN -e shell
  > install AxKit

This downloads, unpacks, compiles, and installs all modules in the AxKit distribution, as well as any prerequisite Perl modules you may need. If AxKit installs without error, you may safely skip to “Basic Server Configuration.” If it doesn’t, see “Installation Troubleshooting” for more information.

From the Tarball Distribution

The latest AxKit distribution can always be found on the Apache XML site at http://xml.apache.org/dist/axkit/. Just download the latest tarball, unpack it, and cd to the newly created directory. As root, enter the following:

  $ perl Makefile.PL
  $ make
  $ make test
  $ make install

This compiles and installs all modules in the AxKit distribution. Just like the CPAN shell method detailed above, AxKit’s installer script automatically attempts to install any module prerequisites it encounters. If make stops this process with an error, skip on to “Installation Troubleshooting” for help. Otherwise, if everything goes smoothly, you can skip ahead to “Basic Server Configuration.”

In addition to the stable releases available from CPAN and axkit.org, the latest development version is available from the AxKit project’s anonymous CVS archive:

  cvs -d :pserver:anoncvs@cvs.apache.org:/home/cvspublic
  login

Brave souls who like to live on the edge or who may be interested in helping with AxKit development can check it out. When prompted for a password, enter: anoncvs. You may now check out a piping hot version of AxKit:

  <![CDATA[cvs - 
  d:pserver:anoncvs@cvs.apache.org:/home/cvspublic co xml-
  axkit]]>

Installing the CVS version of AxKit is otherwise identical to installing from the tarball.

{mospagebreak title=Installing AxKit on Win 32 Systems}

As of this writing, AxKit’s support for the Microsoft Windows environment should be considered experimental. Anyone who decides to put such a server into production does so at her own risk. AxKit will run in most cases. (Win9x users are out of luck.) If you are looking for an environment in which to learn XML web-publishing techniques, then AxKit on Win32 is certainly a viable choice.

If you do not already have ActiveState’s Windows-friendly version of Perl installed, you must first download and install that before proceeding. It is available from http:// www.activestate.com/. I suggest you get the latest version from the 5.8. x branch. In addition, you need the Windows port of the Apache web server. You can obtain links to the Windows installer from http://httpd.apache.org/. Be sure to grab the latest in the 1.3. x branch. Next, grab the official Win32 binaries for libxml2 and libxslt fromhttp://www.zlatkovic.com/libxml.en.html and follow the installation instructions there.

After you install Apache, Perl libxml2, and libxslt, you can install AxKit using ActiveState’s ppm utility (which was installed when you installed ActivePerl). Simply open a command prompt, and type the following:

  C:> ppm
  ppm> repository add theoryx
http://theoryx5.uwinnipeg.ca/ppms
  ppm> install mod_perl-1
  ppm> install libapreq-1
  ppm> install XML-LibXML
  ppm> install XML-LibXSLT
  ppm> install AxKit-1

Finally, add the following line to your httpd.conf and start Apache:

LoadModule perl_module modules/mod_perl.so

This combination of commands and packages should give you a workable (albeit experimental) AxKit on your Windows system. If things go wrong, be sure to join the AxKit user’s mailing list and provide details about the versions of various packages you tried, your Windows version, and relevant output from your error logs.

{mospagebreak title=Basic Server Configuration}

As you will learn in later chapters, AxKit offers quite a number of runtime configuration options that allow fine-grained control over every phase of the XML processing and delivery cycle. Getting a basic working configuration requires very little effort, however. In fact, AxKit ships with a sample configuration file that can be included into Apache’s main server configuration (or used as a road map for adding the configuration directives manually, if you decide to go that way instead).

Copy the example.conf file in the AxKit distribution’s examples directory into Apache’s conf directory, renaming it axkit.conf. Then, add the following to the bottom of your httpd.conf file:

  # AxKit Setup
  Include conf/axkit.conf

You now need to edit the new axkit.conf file to match the XML processing libraries that you installed earlier by uncommenting the AxAddStyleMap directives that correspond to tools you chose. For example, if you installed libxslt and XML::LibXSLT, you would uncomment the AxAddStyleMap directive that loads AxKit’s interface to LibXSLT. Example 2-1 helps to clarify this.

Example 2-1. Sample axkit.conf fragment

# Load the AxKit core.
PerlModule AxKit
# Associates Axkit with a few common XML file extensions
AddHandler axkit .xml .xsp .dkb .rdf
# Uncomment to add XSLT support via XML::LibXSLT
# AxAddStyleMap text/xsl Apache::AxKit::Language::LibXSLT
# Uncomment to add XSLT support via Sablotron
# AxAddStyleMap text/xsl Apache::AxKit::Language::Sablot
# Uncomment to add XPathScript Support
# AxAddStyleMap application/x-xpathscript Apache::AxKit::Language::XPathScript
# Uncomment to add XSP (eXtensible Sever Pages) support
# AxAddStyleMap application/x-xsp Apache::AxKit::Language::XSP

The one hard-and-fast rule about configuring AxKit is that the PerlModule directive that loads the AxKit core into Apache via mod_perl must appear at the top lexical level of your httpd.conf file, or one of the files that it includes. All other AxKit configuration directives may appear as children of other configuration directive blocks in whatever way best suits your server policy and application needs, but the PerlModule AxKit line must appear only at the top level.

{mospagebreak title=Testing the Installation}

AxKit’s distribution comes with a fairly complete test suite that typically runs as part of the installation process. Running the make test command in the root of the AxKit source directory fires up a new instance of the Apache server on an alternate port with AxKit enabled. It then examines the output of a series of test requests made to that instance that exercise various aspects of AxKit’s functionality. make test runs automatically by default if you are installing AxKit via the CPAN shell. If all test scripts pass during the make test process, you can be sure that you have a working AxKit installation and are ready to proceed.

In addition to the automated test suite, AxKit comes with a set of demonstration files that you can also use to test your new installation. To install the demo, copy the demo directory and its contents from the root of the AxKit distribution into an appropriate directory to which you have write access. The configuration file in the demo directory presumes that you will copy the demo directory into /opt/axkit.Soif

you choose another location, be sure to edit all paths in the demo’s axkit.conf file to reflect your choice.

Before the demo will work, you need to include the axkit.conf contained in the new demo directory into your server’s httpd.conf file. For example, if you installed the demo in /opt/axkit (again, the default), you would add the following:

  # AxKit Demo
  Include /opt/axkit/demo/axkit.conf

Start (or stop and restart) the Apache server and point a browser to http://localhost/ axkit/. You should see a page congratulating you on your new AxKit installation. This page also presents a number of links that allow you to test AxKit’s various moving parts. For example, if you chose to install libxslt and its Perl interface XML::LibXSLT to use as an XSLT processor, you would click on the XSLT demos, using the XML:: LibXSLT link to verify that AxKit works and is configured properly to those libraries to transform XML documents, as shown in Figure 2-1.


Figure 2-1.  Proof of a successful demo AxKit installation

If you receive an error when you click on one of the demo links, verify that you have the associated libraries for that demo installed. If you go back and install any processor that AxKit supports, there is no need to reinstall the demo. Just reload the demo index and click on the appropriate link to verify that the new libraries work. You must, however, stop and start Apache (not just restart it) for AxKit to pick up the new interfaces.

If all goes as expected, congratulations. You have installed a working version of AxKit and are ready to get down to business.

{mospagebreak title=Installation Troubleshooting}

As I mentioned in this chapter’s introduction, AxKit’s core consists largely of code that glues other things together. In practice, this means that most errors encountered while installing AxKit are due to external dependencies that are missing, broken, out of date, or invisible to AxKit’s Makefile. Including a complete list of various errors that may be encountered among AxKit’s many external dependencies is not realistic here. It would likely be outdated before this book is on the shelves. In general, though, you can use a number of compile-time options when building AxKit. They will help you diagnose (and in many cases, fix) the cause of the trouble. AxKit’s Makefile.PL recognizes the following options:

DEBUG=1

This option causes the Makefile to produce copious amounts of information about each step of the build process. Although wading through the sheer amount of data this option produces can be tedious, you can diagnose most installation problems (missing or unseen libraries, etc.) by setting this flag.

NO_DIRECTIVES=1

This option turns off AxKit’s apache configuration directives, which means you must set these via Apache’s PerlSetVar directives instead. Use this option only in extreme cases in which AxKit’s custom configuration directives conflict with those of another Apache extension module. (These cases are very rare, but they do happen.)

EXPAT_OPTS=”…”

This option is relevant only if you do not have the Expat XML parser installed and decide to install it when installing AxKit. This argument takes a list of options to be passed to libexpat’s ./configure command. For example, EXPAT_ OPTS=”–prefix=/usr” installs libexpat in /usr/lib, rather than the default location.

LIBS=”-L/path/to/somelib -lsomelib”

This option allows you to set your library search path. It is primarily useful for pointing the Makefile to external libraries that you are sure are installed but, for some reason, are being missed during the build process.

INC=”-I/path/to/somelib/include” This option is like LIBS, but it sets the include search path.

{mospagebreak title=Where to Go for Help}

If you get stuck at any point during the installation process, do not despair. There are still other resources available to help you get up and running. In addition to this book, there are other sources of AxKit documentation, as well as a strong AxKit user community that is willing and able to help.

Installed AxKit documentation

Most Perl modules that comprise the AxKit distribution include a level of documentation. In many cases, these documents are quite detailed. You can access this information using the standard perldoc utility typically installed with Perl itself. Just type perldoc <modulename>, in which <modulename> is the package name of the module that you want to read the docs from. The following list provides a general overview of the information you can find in the various modules.

AxKit

The documentation in AxKit.pm provides a brief overview of each AxKit configuration directive, including simple examples.

Example: perldoc AxKit

Apache::AxKit::Language::*

The modules in this package namespace provide support for the various XML processing and transformation languages such as XSLT, XSP, and XPathScript.

Example: perldoc Apache::AxKit::Language::XSP provides an XSP language reference.

Apache::AxKit::Provider::*

The modules in this namespace provide AxKit with the ability to fetch and read the sources for the XML content and stylesheets that it will use when serving the current request.

Example: perldoc Apache::AxKit::Provider::Filter shows the documentation for a module that allows an upstream PerlHandler (such as Apache::ASP or Mason) to generate content.

Apache::AxKit::Plugin::*

Modules in this namespace provide extensions to the basic AxKit functionality.

Example: perldoc Apache::AxKit::Plugin::Passthru offers documentation for the Passthru plug-in, which allows a “source view” of the XML document being processed based on the presence or absence of a specific query string parameter.

Apache::AxKit::StyleChooser::*

The modules in this namespace offer the ability to set the name of a preferred transformation style in environments that provide more than one way to transform documents for a given media type.

Example: perldoc Apache::AxKit::StyleChooser::Cookie shows the documentation for a module that allows stylesheet transformation chains to be selected based on the value of an HTTP cookie sent from the requesting client.

Additional user-contributed documentation is also available from the AxKit project’s web site at http://axkit.org/. Not only does the project site offer several useful tutorials, it also provides a user-editable Wiki that often contains the latest platform-specific installation instructions, as well as many other AxKit tips, tricks, and ideas.

Mailing lists

The AxKit project sports a lively and committed user base with lots of friendly folks who are willing to help. Even if you are not having trouble, I highly recommend joining the axkit-users mailing list. The amount of traffic is modest, the signal-to-noise ratio is high, and topics range from specific AxKit installation questions to general discussions of XML publishing best practices. You can subscribe online by visiting http://axkit.org/mailinglist.xml or by sending an empty email message to mailto:axkit-users-subscribe@axkit.org.

You can find browsable archives of axkit-users at:

  • http://axkit.org/cgi-bin/ezmlm-cgi/3

  • http://www.mail-archive.com/axkit-users@axkit.org/index.html

Topics relating specifically to AxKit development are discussed on the axkit-devel list. Generally, you should post most questions, bug reports, patches, etc., to axkitusers. If you want to contribute to the AxKit codebase, then axkit-devel is the place for you. You can subscribe to the development list by sending an empty message to mailto: axkit-dev-subscribe@xml.apache.org.

In addition to the mailing lists, the AxKit community also maintains an #axkit IRC channel for discussing general AxKit topics. The IRC server hosting the channel changes periodically, so check the AxKit web site for details.

[gp-comments width="770" linklove="off" ]

antalya escort bayan antalya escort bayan Antalya escort diyarbakir escort