Difference between revisions of "Handbook:Source Code Install"

Should I Do This?

In general, if you're not sure you should be building from source, you probably shouldn't. Chance are, someone has already invested a lot of time to build a binary package for you, and some popular distributions offer their own official packages. Before deciding to 'roll your own' HylaFAX server from source, you might want to check the Binary_Packages page.

Before you begin - Prerequisites

A variety of C++ compiler utilities and image manipulation tools must be installed before HylaFAX can be compiled. Each OS/platform will have a slightly different list of prerequisites and recommended installation procedures, but the following is a general list of the most commonly required ones:

• C++ Compiler - You need a contemporary C++ compiler to build this system, which in most cases means gcc. The native/proprietary C++ compilers that ship with some UNIX variants such as Solaris have been reported to work, and the HylaFAX development team is always receptive to bug reports and patches that help them make HylaFAX build on as many platforms as possible.
• C++ Runtime Libraries - HylaFAX requires only minimal C++ runtime support; basic dynamic memory allocation facilities and support for creating global static objects; it does not use any of the newer C++ runtime facilities such as exception handling. Most C++ compiler packages include everything that you need in the way of a runtime library. When using GNU gcc you may also need the libg++ distribution which is packaged separately from gcc. On some systems where gcc is used these facilities can be satisfied without linking against -lg++ or -liberty, but on others one or both of these libraries are needed for certain library routines that are normally found in the C runtime library. The configuration procedure will abort if libg++ is needed but is not present on the build system. If libg++ is required you should use the version that is appropriate for the compiler. For instance, when using gcc version 2.6.3, libg++2.6.2 is the recommended version to use.
• libtiff - HylaFAX requires version 3.4 or later of the freely available TIFF software distribution. The master site for this distribution is http://www.remotesensing.org/libtiff/. Note that the TIFF distribution must be installed before building HylaFAX from source code or HylaFAX must be specially configured to search for TIFF include files and libraries in non-standard locations. One word of warning - do not use an unpatched version 3.6.1.
• Ghostscript - If you are not on a Silicon Graphics machine (and maybe even if you are), then you will need the Ghostscript PostScript interpreter software to build a PostScript imaging engine to be used by the facsimile server. (This imaging engine is frequently referred to as a Raster Image Processor or RIP.) Ghostscript comes in three flavors, two of which are important to us: GNU PostScript, a version governed by the GNU Public License (GPL), and Aladdin Ghostscript, a version covered by the Aladdin Free Public License. Both versions are copyrighted work and are not shareware or in the public domain. Aladdin Ghostscript is free for use by end users but does not allow commercial distribution; to do this you must arrange for a commercial license. Versions of GNU Ghostscript are distributed approximately a year following the corresponding Aladdin Ghostscript version. For more information on these and other issues consult the information located at http://www.cs.wisc.edu/~ghost/.
• awk (or gawk, mawk, nawk etc) - most distributions ship with at least one of these
• MTA - A mail transport agent such as sendmail or postfix is required in order to deliver faxes, reports, and errors by email. Again, we don't know of a distro that ships without one of these.
• metamail, uuencode, or base64-encode - For optional use in fax-to-email gateways.

Quick Build & Install

Download and Extract the Source Code

Get and extract the HylaFAX source from: ftp://ftp.hylafax.org/source/.Change directories to to /usr/src/ and extract the tarball via 'tar xzvf hylafax-version.tar.gz'. The tarball can now be deleted if so desired.

Compile and Install

In most cases it's as simple as:

cd hylafax-version
./configure (uses default values)
make
make install (must be root or equivalent)

If you want to override any of the defaults, the configure script is your friend. For instance, here's the configure line used when building a Red Hat RPM Package:

./configure \
       --with-DIR_BIN=/usr/bin \
       --with-DIR_SBIN=/usr/sbin \
       --with-DIR_LIB=/usr/lib \
       --with-DIR_LIBEXEC=/usr/sbin \
       --with-DIR_LIBDATA=/etc/hylafax \
       --with-DIR_LOCKS=/var/lock \
       --with-LIBDIR=/usr/lib \
       --with-TIFFBIN=/usr/bin \
       --with-DIR_MAN=/usr/man \
       --with-PATH_GSRIP=/usr/bin/gs \
       --with-DBLIBINC=/usr/include \
       --with-LIBTIFF="-ltiff -ljpeg -lz" \
       --with-DIR_SPOOL=/var/spool/hylafax \
       --with-AFM=no \
       --with-AWK=/usr/bin/gawk \
       --with-PATH_VGETTY=/sbin/vgetty \
       --with-PATH_GETTY=/sbin/mgetty \
       --with-HTML=no \
       --with-PAGESIZE=A4 \
       --with-PATH_DPSRIP=/var/spool/hylafax/bin/ps2fax \
       --with-PATH_IMPRIP="" \
       --with-SYSVINIT=/etc/init.d/hylafax \
       --with-INTERACTIVE=no

If you are using an environment that supports DSOs and HylaFAX supports DSOs in your environment (i.e. Linux), then you might need to ensure that your /etc/ld.so.conf (or equivalent) file contains a reference to /usr/local/lib or wherever libfaxserver.so and libfaxutil.so were installed. (Remember that if you alter /etc/ld.so.conf you must run ldconfig afterwards.)

Run faxsetup and faxaddmodem

With root permissions, execute '/usr/local/sbin/faxsetup'. When finished, faxsetup will automatically run faxaddmodem for you. Generally, you can follow all of the defaults except those for FaxMaster, the local fax number(s), TSI, and any modem-specific information in faxaddmodem.

Starting the hfaxd, faxq, and faxgetty Daemons

This procedure may vary depeding on your specific operating system and init type. Be cautious to follow what is appropriate for your environment.
On BSD-init (non-SysV-init) systems, you may need to edit etc/setup.cache and change the appropriate lines to read:

FAXQ_SERVER='yes'
HFAXD_SERVER='yes'
SYSVINIT='/usr/local/sbin/hylafax'

Edit /etc/rc.d/rc.local and add the lines:

# Starting the HylaFAX hfaxd and faxq Daemons at Boot.
/usr/local/sbin/hylafax start

Edit /etc/inittab and add a line(s) similar to:

m0:2345:respawn:/usr/local/sbin/faxgetty ttyS0

where 'm0' is unique in inittab and 'ttyS0' matches the device name(s) used at the outset of the faxaddmodem script.

faxcron and faxqclean

It would be wise to run faxcron and faxqclean regularly from cron so that the queue directories do not clutter up and fill the storage device. Many installations run faxqclean every hour and faxcron every day. Insert something like this into your uucp or root crontab file:

0 * * * * /usr/local/sbin/faxqclean
0 0 * * * /usr/local/sbin/faxcron | mail -s "HylaFAX Usage Report" faxmaster

Finishing Up

Either restart the system, or alternatively, execute the following commands:

/usr/local/sbin/hylafax start
/sbin/init q

Now you're done with a basic HylaFAX installation. Check things out with faxstat and various other tests as noted in this document. You'll also likely want to configure faxcron and faxqclean. See General Tweaking and Customization Hints for those instructions.

The Gory Details

To build the software you need to first run the configure shell script that is located in the top level of the source directory. This script probes the target system for necessary tools and functions and constructs a build environment in which the software may be compiled. Once configuration is done, you simply run make to build the software and then make install to do the installation; for example:

hyla% cd hylafax-4.2.3
hyla% ./configure
 ...lots of messages... 
hyla% make
 ...lots of messages... 
hyla% su             # NB: installation must be done by the super-user 
hyla# make install 

In general, the software is designed such that the following should be ``make-able in each directory:

Target	Purpose
all	build everything that is to be installed (default)
depend	build dependency information
install	build and install everything normally installed
clean	remove .o files and cruft, but not executables
clobber	remove everything that can be recreated
distclean	remove absolutely everything that can be recreated

Note that after running "make clobber" or "make distclean" the configure script must be run again to create the Makefiles and other build-related files.

Build Trees

There are two schemes for configuring and building the software. If you intend to build the software for only one target system, you can configure the software so that it is built in the same directories as the source code.

hyla% cd hylafax-4.2.3
hyla% ls
CHANGES       configure     distrules  faxrm        man       sendfax
config        CONTRIBUTORS  etc        faxstat      pkg       sendpage
config.guess  COPYRIGHT     faxalter   hfaxd        port      sgi2fax
config.h.in   CVS           faxcover   html         README    TODO
config.site   defs.in       faxd       INSTALL      regex     util
config.sub    dist          faxmail    Makefile.in  rules.in  VERSION
hyla% ./configure

Otherwise, you can configure a build tree that is parallel to the source tree hierarchy but which contains only configured files and files created during the build procedure.

hyla% cd hylafax-4.2.3
hyla% mkdir obj obj/mycpu
hyla% cd obj/mycpu
hyla% ../../configure 

This second scheme is useful for:

• building multiple targets from a single source tree
• building from a read-only source tree (e.g. if you receive the distribution on CD-ROM)

Beware that if you choose to use the second scheme for configuring the software you must not use an absolute pathname when you run configure (i.e. a pathname that begins with ``/) and the make that you use to build the software must correctly support the VPATH facility.

Configuration Files

The configuration process is critical to the proper compilation, installation, and operation of the software. The configure script runs a series of tests to decide whether or not the target system supports required functionality and, if it does not, whether it can emulate or workaround the missing functions. This procedure is fairly complicated and, due to the nonstandard nature of most UNIX systems, prone to error. The first time that you configure the software for use you should check the output from the configure script and look for anything that does not make sense for your system. A sample configure run is shown below together with an explanation of the work that is done.

A second function of the configure script is to set configuration parameters for the software. Many of these values are just default settings that can be changed after configuration through files that programs read at runtime, but some settings cannot be changed without rerunning the configure script. For example, by default the software is configured for installation in the /usr/local hierarchy; this cannot be changed without rerunning the configure script.

The configure script reads two configuration files to get configuration parameters: a site-wide configuration file that has settings that are to be applied to all systems at a particular site, and a target-specific configuration file that has settings for a specific system. Site-wide configuration files are named config.site and are automatically searched for first in any directory specified on the command line to configure with the -site option, or if that fails, in the directory in in which the configure script is located. Target-specific configuration files are named config.local and are looked for first in the top-level build directory, or, if that fails, in the directory in which the configure script is located.

NOTE: configure reads any config.site file first, and then any config.local file. This permits target-specific definitions to override site-wide definitions.

Configuration files are actually just shell scripts (written in the Bourne shell syntax) that define well-known shell variables that are used in the configuration process. For example, the following file might be used on a BSD/OS system to configure the software for installation in the /usr/contrib area and to make use of the Adobe Font Metric files that are already distributed as part of the BSD/OS 1.1 distribution:

#
# Parameters suitable for BSD/OS 1.1
#
DIR_AFM="/usr/contrib/lib/flexfax/afm"     # reuse existing files
DIR_BIN="/usr/contrib/bin"                 # directory for client apps
DIR_SBIN="/usr/contrib/bin"                # directory for system apps
DIR_LIBEXEC="/usr/contrib/bin"             # directory for libraries & hidden apps
DIR_LIBDATA="/usr/contrib/lib/hylafax"     # directory for client data
DIR_MAN="/usr/contrib/man"                 # directory for manual pages
DIR_SPOOL="/var/spool/hylafax"             # directory for spooling area
DIR_HTML="/usr/contrib/html/hylafax"       # directory for HTML documentation 
DIR_CGI="/usr/contrib/html/cgi-bin"        # directory for CGI scripts 

The complete list of configuration parameters is given in the sample config.site file provided in the source distribution. Also, the sections below on ``Configuring Packages and ``Configuration Parameters have information on the most important or obscure parameters.

Finally, take note that there are two other configuration-related files that may be useful. The file named config.cache has all the configuration parameter settings that were selected the last time configure was run. This file is automatically read in by configure when it starts up to speed the configuration process. config.cache may be safely removed at any time. Cached settings are also automatically ignored if new settings are set through command line arguments to configure or through a config.local or config.site file.

The other file of interest is config.log. This file contains information and messages related to the various tests that configure does when constructing a build environment. If the configuration process fails for some reason or configure does something unexpected this file should be used to debug the problem.

NOTE: Beware that the configure script is designed to be similar to scripts generated by the GNU autoconf facility but it is not 100% compatible. Use the -help option to configure for a list of the available options.

Configuring Packages

HylaFAX uses the notion of a package to control which pieces of software are included in a build. Some packages are optional and are installed only as needed, or only if specifically requested at the time the configure script is run. Other packages may select one of several incompatible choices that must be made when the software is built. Packages can be specified in a config.site or config.local file, or by using a -with-package option when invoking configure; e.g. configure -with-AFM to request the AFM package. Most packages are automatically configured according to the characteristics of the system where HylaFAX is being built; this may not be appropriate when preparing binary distributions for multiple systems in which case they can be explicitly enabled or disabled.