| 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. 2.6.1 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. 2.6.1.1 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. 2.6.1.2 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: Topics relating specifically to AxKit development are discussed on the axkit-devel list. Generally, you should post most questions, bug reports , patches, etc., to axkit-users. 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. |
