Report Magic for Analog Documentation - Installing the Source Package

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">


Installing the Source Package

Saving and Extracting

When you download the package file, store it somewhere on your hard drive (like /usr/src/rmagic or ~/rmagic). When it's completed, uncompress the archive using gzip and/or tar or some similar utility. If you have GNU tar you can simply use 'tar -xzf rmagic-*.tar.gz'.

Documentation

When you uncompress the archive, it will create a subdirectory under the location you told it called docs. From your web browser (or vi if it reads HTML files on your system), open the file index.html in this directory to learn how to use Report Magic for Analog. In the Report Magic directory is also a file called README. Please see this file for last-minute changes.

Installation

(These instructions are also in the file INSTALL in the root of the source package archive.) The first time you install Report Magic can be somewhat complicated. Please read through the instructions on this page completely before starting so you have a good idea of what will be required. Because much of Report Magic is built with reusable code, upgrades will be simple. For upgrade notes, see the What's New page. These instructions and the included Install.PL script assume you are using a Unix-like system. If not, it is up to you to make the necessary translations in the instructions and the Install.PL file to reflect you computer's file system.

To run Report Magic, you need to have Perl 5.004 or newer installed on your system. (You really should have 5.005 or 5.6) You can find the version of Perl that you have by typing 'perl -v' at the prompt. If the system says 'unknown command' you either do not have Perl installed or it is not on your path. If you don't have it see the perl.com home page for details on getting the Perl interpreter. Compiled binaries for Perl are available for almost every platform.

Before installing for the first time, you will need to install some system libraries if they aren't already installed. To generate the graphs, Report Magic needs three libraries - zlib, libpng and libgd. If you want TrueType font support in your graphs, you can also install the lttf TrueType library from FreeType. If you want jpeg support, you can install the jpeg-6b library.

Using Packages

It is much easier to install the libgd library from a package, if your operating system supports such. Of course, you will probably want to make sure a recent version is available. As of this writing, libgd is at version 1.8.3. The following packages were known to exist at this time as well:

Debian Linux

A complete Report Magic package is available for Debian Linux. It may not be the latest version, but it should have links to all dependent packages

FreeBSD

Report Magic is available in the FreeBSD ports collection as www/reportmagic on releases after 4.2. There is also a ready-to-run package on the FTP mirror sites and CDs after 4.2. Analog is in www/analog. Details on installing ports are covered in the Handbook. Basically, in each directory 'make install && make clean' will do the job and recover the drive space used. This may not be the latest version, but it should have links to depenedent packages.

RedHat Linux

You can use the RPM for libgd to get the system libraries installed. Then just run the Install.PL to install the Perl modules and Report Magic files.

Solaris

There are libgd packages available for most sparc versions of Solaris:

Use these as a starting point, then run Install.PL to get the Perl modules and Repport Magic files installed.

Mac OS X

There is a separate set of instruction here that details the installation of Report Magic on Mac OS X.

Building from source

If one of the above packages does not work for you, then you can procede with the standard install procedure described below to install libgd from the source.

zlib: The zlib compression library can be acquired from http://www.info-zip.org/pub/infozip/zlib/zlib.tar.gz (there are other mirrors at the site). This is a link to the latest version. Download the archive and extract it. Read the installation documentation and the license. On most systems (Solaris is an exception) you will not have to build the zlib library if you don't want. When you build libpng, it incorporates the source files rather than the actual lib files. If you choose to build and install zlib (or your system requires that you do) Then do the standard install procedure:
libpng: Installing libpng is a little more complicated. You can acquire the latest version from http://download.sourceforge.net/libpng/. Look for something like 'libpng-x.x.x.tar.gz', where x.x.x is the newest (i.e. highest) version number. Download this and extract it. Read the installation documentation and the license. You need to have the zlib, that you just uncompressed, on the same level as the libpng directory and they should both be named without their versions. Your directory structure should look like this:; Something like this should do it, but may differ from system to system. You'll have to remove the archive before doing this (rm *.tar or rm *.tar.gz depending on your tar version). You should choose one of the makefiles in the libpng/scripts directory according to your system (e.g. scripts/makefile.linux for Linux or scripts/makefile.sunos for Solaris).:
lttf (Optional): If you want to allow support for TrueType fonts in your graphs you can install lttf. This library is not required for installation, but may be useful. (If you intend to output in Japanese or Polish, you will need this library installed. It is also helpful for Italian ouput.) You can download lttf from this page. After reading the installation instructions and license, you can build it with the standard techinique:
jpeg-6b: The jpeg-6b library may already be installed on your system. Check /lib, /usr/lib, and /usr/local/lib or your system's equivalents. If not it can be downloaded from ftp://ftp.uu.net/graphics/jpeg/jpegsrc.v6b.tar.gz. After reading the installation instructions and license, you can build it with the following commands:
libgd: Installing libgd should then be straight-forward. Download the latest version from ftp://ftp.boutell.com/pub/boutell/gd/. Again, it will look something like 'libgd-x.x.x.tar.gz', where x.x.x is the newest (i.e. highest) version number. Download this and extract it. Read the installation documentation and the license. NOTE you will need to edit at least the LIBS and CFLAGS lines Makefile if you wish to include support for jpeg or ttf. You may also have to add -I/usr/local/include/freetype to the INCLUDEDIRS= line to make it work with freetype-1.3.1. Read the notes in the Makefile for more information. You can then build the library with the standard:

Installing rmagic and Perl modules

If all system libraries installed successfully, then the rest should be quite simple. To install change to root user, change directory into the rmagic directory where you uncompressed the Report Magic archive and type the following command:


	perl Install.PL

If all goes well, this will load all the necessary Perl modules (that aren't already loaded and up-to-date), install Report Magic in the directory /usr/local/etc/httpd/rmagic/ (or similar directory with version number) and install the documentation below that.

If you want to install Report Magic elsewhere, simply edit the configuration settings in the top of the Install.PL file.

Autoloading the required perl modules from CPAN may require several more steps. First, this uses the CPAN module to load modules from CPAN. You will need to configure this the first time it runs by answering serveral questions. It also requires that you are connected to the Internet (or a local CPAN mirror if you have such and your CPAN module has been configured for such). Second, using this may be a security risk. There is no signature system for CPAN code. It is possible (though unlikely) that CPAN downloads may have been tampered with. If this bothers you, don't run this part of the install. Instead install all the modules by hand (see below). (Although, this still could contain tampered modules, but at least you can look at all the sources first before you put them in your Perl site library.)

When configuring your CPAN setup, you will be asked for the URL of your favorite CPAN site. On some systems this includes a list to choose from, on some it doesn't. If no list is presented, you can type in 'ftp://ftp.cpan.org/pub/CPAN'.

While the install script is running, watch carefully for any errors. The script will continue to try to install all necessary Perl even if some fail. This may mean that other will fail later (because of dependencies). Also, the latest version of GD will ask you some question about the way libgd was installed on your system.

If you don't want to auto-load the latest version of the necessary Perl modules, use this instead:


	perl Install.PL -no_modules

If you just want to auto-load the latest version of the necessary Perl modules, but don't want to move Report Magic (i.e. you will run it from the directory you unarchived it into) use this instead:


	perl Install.PL -only_modules

Manual Installation of Perl Modules

Report Magic for Analog requires several Perl modules, as well as the core Perl interpreter. If you've chosen not to autoload the necessary, Perl modules, they are shown below in the recommended install order. After each module name is a version number indicating when in the Report Magic history, the module dependency was added. If you are upgrading from a previous version, you need only add modules that show a newer version dependency than the one you are upgrading from.

Each Perl module will install with the standard perl install method:


	perl Makefile.PL

	make

	make test

	make install

CPAN Modules

GD Since 1.0 BETA 1: In order to generate the graphs, Report Magic uses Licoln Stein's GD.pm graphics module interface for Thomas Boutell's libgd graphics library. (If you are running ActivePerl on Win32 this ships with the distribution so you can just continue on to the next item.) The libgd graphics library now outputs PNG format graphics files. This means it, in turn requires libpng, which, in turn, requires zlib for compression. This is a lot of installation, compilation and work (as documentated above), but you'll only need to do it once. If you have an older version of libgd, but want PNG support, follow those instructions to update it.; If you haven't already installed these libraries, follow the instructions above and then continue with the Perl GD module installation. Next, install the GD.pm Perl interface module. This can be downloaded from CPAN. Check here for the latest version of GD.
GD::Text Since 1.3: Martien Verbruggen's GD::Text module is now the source for all text and font handling in the GD::Graph and GD::Graph3d modules. You can find the latest version on CPAN in this directory.
GD::Graph Since 1.3: Martien Verbruggen's GD::Graph module is used as the basis for the graphs. This replaces GIFgraph. If you are upgrading from an older version, Report Magic does not and will no longer need GIFgraph. You can find the latest version on CPAN in this directory.
GD::Graph3d Since 1.3: Extension to Martien Verbruggen's GD::Graph module is used for the 3D graphs. You can find the latest version on CPAN in this directory.
Config::IniFiles Since 2.0 BETA 1: Teh Config::IniFiles package is used to read the configuration and settings files. You can find the latest version here.
HTML::Tagset Since 1.0 BETA 1: This module is a required by the HTML::Parser package by Gisle Aas. You can find the latest version on CPAN here.
HTML::Entities Since 1.0 BETA 1: This module is a part of the HTML::Parser package by Gisle Aas. You can find the latest version on CPAN here.
File::Spec Since 1.0 BETA 3: This modules is part of Perl 5.005 distributions, so if you Perl is 5.005 or newer you don't need to get this. If you're using VMSPerl, make sure you update to the latest available version and install the patch available from http://www.xray.mpe.mpg.de/mailing-lists/vmsperl/1999-05/msg00058.html. If you are running MacPerl, OS/2Perl or Perl 5.004, File:Spec does NOT ship with those distributions. You can get it from CPAN here.
Time::Local Since 2.10: This modules is part of Perl 5.005 and later distributions, so if you Perl is 5.005 or newer you don't need to install this. If you're using MacPerl or other Perl 5.004 or earlier, you can dowload a copy of the Time::Local module from our website here. To install it, save it to a folder called Time under your Report Magic folder.

Perl Modules

These modules ship with Perl 5.004 or higher. They are listed here for completeness, but you should not need to worry about adding or finding them.

File::Copy Since 1.0 BETA 1
File::Basename Since 1.0 BETA 3
File::Path Since 1.0 BETA 3: These modules are in the File directory on CPAN.
FindBin Since 1.0 BETA 1
lib.pm Since 1.0 BETA 1: These two modules are listed by name on CPAN here.

[Introduction] [Documentation map] [Index] [Frequently Asked Questions] [License]