• Before You Start
• The Build Procedure
• Build Trees
• Configuration Files
• Configuring Optional Packages
• Configuring the HTML Documentation
• Upgrading From FlexFAX
• A Sample Configuration Session
• Configuration Parameters

gcc

C++ runtime libraries

ghostscript

gmake

gawk

sed

/bin/test

ps2fax binary for IRIX systems

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

make [all]	build stuff
make depend	build dependency information
make install	build&install stuff
make clean	remove .o files and cruft, but not executables
make clobber	remove everything that can be recreated
make distclean	remove absolutely everything that can be recreated

hyla% cd hylafax-v3.0beta099
hyla% ls
Distfile      config        distrules     faxmail       rules.in
HOWTO         config.guess  doc           faxrm         sendfax
Makefile.in   config.h.in   dps           faxstat       sendpage
RCS           config.site   etc           html          sgi2fax
README        config.sub    fax2ps        libtiff       util
TODO          configure     faxalter      man
VERSION       defs.in       faxcover      port
afm           dist          faxd          recvfax
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-v3.0beta099
hyla% mkdir obj obj/mycpu
hyla% cd obj/mycpu
hyla% ../../configure

• 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)

HPUX 9.05: The standard make incorrectly processes VPATH; either use gmake or configure builds in the source tree.

Solaris 2.3: The standard make does VPATH processing incorrectly for files passed to the make dependency generator script (the last file in the list is not converted to a pathname relative to the source directory); this causes lots of messages that can be ignored.

Configuration Files

A second function of the configure script is to set the default configuration parameters for the software. Many of these parameters can be changed after configuration through files that programs read at runtime, but some parameters cannot be changed without rerunning the configure script. Of particular note are the directories where the software is to be installed. By default the software is installed in the /usr/local hierarchy. To change this behaviour the appropriate parameters can be specified either:

• on the command line to configure,
• in a site-wide configuration file, or
• in a target-specific configuration file.

Site-wide configuration files are named config.site and are automatically searched for first in any directory specified on the command line to configure (using 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 configuration directory, or, if that fails, in the directory in which the configure script is located.

Configuration files are just shell scripts that define shell variables that control the configuration process. For example, the following file might be used on a BSDI 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 BSDI 1.1 distribution:

#
# Parameters suitable for BSDI 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

For a complete list of the possible configuration parameters, look at the sample config.site file provided in the distribution or check the section below.

Configuring Optional Packages

AFM Package

The AFM package contains sample Adobe Font Metric files that came from the public dvips distribution. AFM files are required by the textfmt(1) and faxmail(1) programs for proper formatting of ASCII text. The AFM files used should reflect the characteristics of the fonts that are used for imaging. However, if the PostScript RIP used to image text does not come with AFM files for its native fonts, this package can be installed with only minimal degradation in the quality of the imaged text. By default this package is configured for installation only if font metric files do not appear to be present (auto).

DSO Package

The DSO package controls whether or not to configure the software to build Dynamic Shared Objects for the TIFF library, for utility routines used by both client and server applications, and for a nucleus of common code used by server applications. Use of DSOs can significantly reduce the disk space needed for the HylaFAX software. If DSOs are not used then the code is statically linked into each application that uses it. By default this package is configured only if the system appears to suport DSOs in a way that fits into the normal build scheme (auto). If DSO support is explicitly enabled and there is no support for using DSOs in the expected way then DSOs are not used.

GETTY Package

The GETTY package controls whether or not to configure BSD- or System V-style getty support for handling incoming data connections. By default this package is configured according to the target environment.

HTML Package

The HTML package contains this HTML documentation about HylaFAX. By default this package is not configured for installation. Some HTML documentation can be viewed directly from the source directory; otherwise all the documentation can be viewed from the main WWW site at http://www.vix.com/hylafax/. You may want to configure the installation of the HTML materials if there is poor connectivity to the main WWW site. See the next section for more information about configuring the HTML materials.

PS Package

The PS package selects whether to configure use of Ghostscript (gs) or Display PostScript (dps) for imaging PostScript on the server. By default the DPS support is selected only for IRIX systems; otherwise Ghostscript is used. IRIX users may choose to use this control to select Ghostscript for use on their SGI systems.

SGI2FAX Package

The SGI2FAX package controls whether or not to configure the sgi2fax program that converts SGI RGB images to TIFF/F (for direct transmission as facsimile). By default this package is configured for installation only if the target system appears to have support for the SGI Image library that sgi2fax uses to read RGB images (auto). If this package is not installed then SGI RGB images must be converted to a form suitable for transmission using some other mechanism.

SYSVINIT Package

The SYSVINIT package controls whether or not to configure the System V-style support for automatically starting the HylaFAX queuer process from init(1). By default this support is configured for installation only if the target system appears to use a System V-style init (auto); i.e. the /etc/rc0.d and /etc/rc2.d directories exist.

When the HTML package is configured for installation there are four other parameters that should be setup according to local needs:

DIR_HTML

The directory where the HTML materials should be installed.

DIR_CGI

The directory where the supporting CGI scripts should be installed.

CGIPATH

The virtual pathname to use in the HTML documents to invoke CGI scripts installed in DIR_CGI.

HTMLPATH

The virtual pathname to use in the HTML documents to reference materials installed in the DIR_HTML directory.

DIR_HTML="/var/httpd/hylafax"
HTMLPATH="/hylafax"
DIR_CGI="/var/httpd/cgi-bin"
CGIPATH="/cgi-bin"

DIR_HTML="/usr/local/html/hylafax"
HTMLPATH="/hylafax"
DIR_CGI="/usr/local/html/cgi-bin"
CGIPATH="/cgi-bin"

There are a few other issues to consider when installing the CGI scripts:

• The manpage script that provides access to the UNIX manual pages may require some tailoring if manual pages are installed in non-standard locations or if the normal system man(1) command does not support the expected options. If you have problems consult the script.
• The cat-pages and cat-faq scripts will optionally return a cached copy of concatenated documents; consult the scripts for more information.
• If local support is to be provided, it may be worthwhile to alter the electronic mail addresses embedded in several of the CGI scripts.

• The default server operation parameters set in config.h have changed; for example the default kill time for a fax job is now 3 hours instead of 24 hours. Verify the parameters in config.h are what you want.
• Numerous pathnames may have changed. The source-based installation procedure does not remove previously installed files unless they are to be overwritten; this can result in multiple versions of applications such as faxaddmodem being installed. Verify the parameters used for installation; you may want to tailor them to your environment by creating a config.local file with local configuration parameters.
• HylaFAX includes an improved install.sh script that is used to install files on non-IRIX systems. Certain files in the distribution are treated as configuration-specific files and are not overwritten if they appear to have local modifications. Instead the install.sh script will install the new file with a .N suffix and print a warning message. Be sure to reconcile these conflicts by comparing the old and new file contents with a program like diff(1); in most cases you should incorporate any local modifications into the new file and install it for use.

There are other issues with upgrading from FlexFAX; they are discussed in the chapter that describes setting up the server.

A Sample Configuration Session

wullbrandt% mkdir fax
wullbrandt% cd fax
wullbrandt% ln -s /hosts/oxford/usr/people/sam/fax src

wullbrandt% src/configure

Configuring HylaFAX (tm) (aka FlexFAX) v3.0beta095.

Reading site-wide parameters from src/config.site.
Fee, fie, foe, this smells like a i386-unknown-bsdi1.1 system.

Using /usr/local/bin/gcc for a C compiler (set CC to override).
Looks like /usr/local/bin/gcc supports the -g option.
Looks like an ANSI C preprocessor.
... but __ANSI_CPP__ is not automatically defined, will compensate.
Looks like /usr/local/bin/gcc supports the -M option for make dependencies.

Note that an ANSI C compiler is required to build the software. If a C compiler requires options to enable ANSI C compilation, they can be specified with the ENVOPTS parameter.

Once a compiler is selected configure does several checks to see:

• if the compiler accepts a -g option to enable the generation of debugging symbols,
• if the compiler includes an ANSI C preprocessor, and
• if the compiler will generate make dependency rules with a -M option.

Using /usr/local/bin/gcc for a C++ compiler (set CXX to override).
Looks like /usr/local/bin/gcc supports the -g option.
Using " -g" for C++ compiler options.
Looks like an ANSI C++ preprocessor.
... but __ANSI_CPP__ is not automatically defined, will compensate.

Using /usr/bin/make to configure the software.
Using ".include <file>" syntax for Makefiles.

Using /bin/bash to process command scripts.

Looks like -lutil is needed for wtmp file logging.
Looks like -lm is the library for math functions.

Creating port.h. The port.h file is included by all the C and C++ code in the system. It includes definitions for functions and type definitions that are missing from system include files, #defines to enable or disable system-specific functionality, and other odds and ends.

Creating port.h with necessary definitions.
... open FIFO files read-only
... use (sig_t) for signal handler type
... use (sig_t) for sigvec handler type
... use (sig_t) for sigaction handler type
... configure use of mmap for memory-mapped files
... configure use of fchown
... add function prototype for cuserid
... configure use of fchmod
... add function prototype for setutent
... add function prototype for endutent
... add function prototype for pututline
... configure use of <locale.h> (internationalization support)
... configure use of <paths.h>
... configure use of <sys/select.h>
... configure use of logwtmp (BSD-style wtmp logging)
... add function prototype for logwtmp
... configure use of logout (BSD-style utmp support)
... add function prototype for logout
Done creating port.h.

Selecting emulated library functions. Certain functions used by the software are not present on all systems and can be emulated using other system functionality. configure checks for the presence of such functions and if they are missing, will configure emulation code from the port directory to use instead. Building HylaFAX on unsupported systems may require adding to the code to the port directory.

Checking system libraries for functionality to emulate.
... emulate cuserid
Done checking system libraries.

Setting up libtiff configuration parameters.
Using memory mapped file support in libtiff.
Done setting up libtiff.

Checking for Dynamic Shared Object (DSO) support.
Done checking for DSO support.

Selecting utility programs. configure locates various system utility programs that are used by the software. Note that absolute pathnames are selected because several scripts and programs excute with super-user privileges.

Selecting programs used during installation and operation.
Looks like /usr/bin/awk should be used to process command scripts.
Looks like /usr/sbin/sendmail should be used to deliver mail.
Looks like /usr/bin/mkfifo creates FIFO special files.
Looks like /bin/mv supports the -f option to force a move.
Looks like /bin/ln supports the -s option to create a symbolic link.
Done selecting programs.

Selecting default configuration parameters. The remainder of the work done by configure involves setting up configuration parameters that are mainly used during the operation of the fax software. These parameters can be set during configuration or, in most cases, they can be set through runtime configuration files.

Using uid uucp and gid dialer for controlling access to fax stuff.
Using uid bin and gid bin for installing programs.
Using LSB2MSB bit order for your i386 cpu.
Looks like you need BSD getty support.
Looks like /usr/libexec/getty is the program to exec for a data call.
Looks like you use binary-style UUCP lock files.
Looks like UUCP lock files go in /var/spool/uucp.
Looks like font metric information goes in /usr/contrib/lib/flexfax/afm.
Looks like the gs imager package should be used.
Looks like /usr/contrib/bin/gs is the PostScript RIP to use.
Looks like manual pages go in /usr/local/man.
Looks like manual pages should be installed with bsd-nroff-gzip-0.gz.

HylaFAX configuration parameters are:

[ 1] Directory for applications:        /usr/local/bin
[ 2] Directory for lib data files:      /usr/local/lib/fax
[ 3] Directory for lib executables:     /usr/local/lib/fax
[ 4] Directory for system apps:         /usr/local/bin
[ 5] Directory for manual pages:        /usr/local/man
[ 6] Directory for HTML documentation:  /usr/local/doc/fax
[ 7] Directory for spooling:            /var/spool/fax
[ 8] Directory for font metrics:        /usr/contrib/lib/flexfax/afm
[ 9] Directory for uucp lock files:     /var/spool/uucp
[10] Uucp lock file scheme:             binary
[11] PostScript imager package:         gs
[12] PostScript imager program:         /usr/contrib/bin/gs
[13] Manual page installation scheme:   bsd-nroff-gzip-0.gz
[14] Default page size:                 North American Letter
[15] Default vertical res (lpi):        98
[16] Location of getty program:         /usr/libexec/getty
[17] Location of sendmail program:      /usr/sbin/sendmail

Are these ok [yes]? 

Once acceptable parameters are setup configure will generate all the files that depend on these parameters. Note that certain files may or may not be created based on the configuration of optional packages and/or the functions supported by target system.

Creating defs from src/defs.in
Creating rules from src/rules.in
Creating Makefile from src/Makefile.in
    ...stuff deleted...
Setting up make dependency files.
Done.

The default setting for most configurations parameters is usually correct. Be especially careful about enabling or overriding parameters that control workarounds for system bugs; certain problems can cause server processes to go into infinite loops!

Note that HylaFAX is composed of client and server applications. Client applications are programs that normal users invoke to send facsimile, query the status of facsimile servers, etc. Server applications are programs that reside only on the machine where the fax modems are present.

AROPTS

The options passed to ar when creating an archive. Note that configure will automatically check to see if ar supports an s to create a symbol table instead of using ranlib.

CONFIG_OPENFIFO

The mode to use when opening a FIFO special file in a server process. Normally this should be O_RDONLY, but on some systems this must be O_RDWR to avoid kernel bugs that cause select system calls to return prematurely after a process closes the ``client side'' of a FIFO. By default this parameter is set according to the target system.

CONFIG_FIFOBUG

Whether or not to enable a workaround for a kernel bug that causes select system calls to return prematurely after a process closes the ``client side'' of a FIFO special file. Setting this parameter to yes causes server processes to close and reopen FIFO special files after each received message. Note that aside from the additional overhead incurred in the server processes, this problem can also cause client programs to be temporarily unable to reach a server process. To minimize this possibility, the client code tries to reach a server process up to 5 times before giving up; this can introduce noticeable delays in applications such as faxstat.

CONFIG_SELECTBUG

On some systems where the FIFO select bug (see above) exists the select system call may return bits set in the read, write, and exception masks even if they were not requested; this in turn can cause the Dispatcher code to abort. Setting this parameter to yes causes the Dispatcher to ignore any bits set in bit vectors returned by select if the bits were not requested. Enabling this workaround adds additional overhead to each server process.

CONFIG_WINSZHACK

On some systems the TIOCWINSZ ioctl is defined, but its use requires the inclusion of two non-standard files. Setting this paramter to yes causes the inclusion of these files.

CONFIG_ABORTBUG

On some systems the logic used by the sever processes to poll for messages on a FIFO special file while actively doing work can cause the process to go into an infinite loop. Setting this parameter to yes causes the server processes to not poll for messages. Enabling this workaround means that the faxgetty process will not recognize messages to abort a facsimile while it is being received.

CONFIG_NOSTDINDUP

On some systems, if the standard output is redirected to be the same as the standard input, then the stty program will emit a warning message. This is necessary for some older systems because it is the only way to force stty to change parameters on a tty device that is not the controlling tty. Setting this parameter to yes causes the ondelay program to not set stdout to stdin. Enabling this workaround can break the faxaddmodem program; it should be used only on systems where stty supports the -f option to select a tty device other than the controlling tty.

CXXFILE

The options to the C++ compiler required to get the compiler to process a file with a .c++ suffix as C++ source code. configure automatically sets this parameter to "-x c++" for gcc and to "-+" for the IBM xlC compiler under AIX.

DEFVRES

The default vertical resolution in lines/inch that clients should use for submitted facsimile. Choices are 98 and 196.

DIR_AFM

The directory where client applications should find Adobe Font Metric (AFM) files. These files are used by various HylaFAX programs when converting text to PostScript.

DIR_BIN

The directory where client applications should be installed; by default this is /usr/local/bin.

DIR_CGI

The directory where CGI scripts used by the HTML-based HylaFAX documentation should be installed; by default this is /var/httpd/cgi-bin (usually appropriate for the NCSA HTTP server).

DIR_HTML

The directory where HTML-based HylaFAX documentation should be installed; by default this is /var/httpd/htdocs/hylafax (usually appropriate for the NCSA HTTP server).

DIR_LIBDATA

The directory to install data files that are required by client applications; by default this is /usr/local/lib/fax.

DIR_LIBEXEC

The directory to install executable programs that are invoked by other applications and not from the command line (e.g. the textfmt program invoked by sendfax to convert text to PostScript when submitting a fax job); by default this is the same as DIR_SBIN.

DIR_LOCKS

The directory in which to create UUCP lock files.

DIR_MAN

The top-most directory of the manual area where client/server manual pages should be installed.

DIR_BIN

The directory where server-specific applications should be installed; by default this is DIR_SPOOL/bin.

DIR_SBIN

The directory where system applications such as servers should be installed; by default this is /usr/local/sbin.

DIR_SPOOL

The directory in which the HylaFAX server spooling area should be setup; by default this is /var/spool/fax.

DSODELAY

When DSO's are built, the option to specify to CC and/or CXX to note that a library should be loaded only as needed. This option is used to delay the loading of the TIFF library for applications that may use it infrequently.

DSOOPTS

When DSO's are built, the options to specify to CC and/or CXX to create a DSO.

DSOSUF

When DSO's are built, the filename suffix for a DSO. If this is set to "a" then statically linked archives are used.

ENVOPTS

Options to pass to CC and CXX to force ANSI C compilation.

FAXGID

The group ID to use for the fax user; by default this is selected according to the target system.

FAXUID

The user ID to use for the fax user; by default uucp.

FILLORDER

The order of bits in a byte on the server machine; either LSB2MSB or MSB2LSB. This is normally selected according to the target system.

GCOPTS

Special options to pass the C compiler. If this parameter is set, then configure may append other options to this list.

GCXXOPTS

Special options to pass the C++ compiler. If this parameter is set, then configure may append other options to this list.

INSTALL

The pathname of the install program to use. Note that this program must emulate the command line interface used by the IRIX install program.

LIBMALLOC

Whether or not to use -lmalloc in building the software. By default (auto) configure will probe the system to see if the library is present; if it is then the software will be configured to use it when building. Other possible values are: yes and no to enable and disable use, respectively. On systems that support DSOs it may be important to disable the use of -lmalloc to avoid conflicts with the normal memory alocation routines present in the standard C library.

LIBPORT

The pathname of the library that holds code to emulate missing system functionality. Normally this parameter is set by configure based on whether or not emulation code is required for the target.

LIBSUN

Whether or not to use -lsun in building the software. By default (auto) configure will probe the system to see if the library is present; if it is then the software will be configured to use it when building. Other possible values are: yes and no to enable and disable use, respectively.

LLDOPTS

Extra command line options passed to CC and CXX when linking an executable. This option is usually set only when DSO support is enabled (to force the executable to search for the HylaFAX-specific DSO's in non-standard locations in the filesystem.)

LOCKS

A specification of the default type of UUCP lock files to use. This parameter is usually one of ascii, binary, -ascii or +ascii; consult the config(4F) manual page for a description of the UUCPLockType configuration parameter.

MACHDEPLIBS

Target-dependent libraries that should be used when linking applications. Note that if this parameter is specified configure will append to the list of libraries.

MAKECXXOVERRIDE

A special parameter used by configure when constructing Makefiles. This parameter is required when compiling the software with the SunPRO C++ compiler; it works around limitations in the SunPRO compilation environment.

MAKEDEPINCLUDE

The keyword used to specify the inclusion of a make dependency file when constructing Makefiles. This parameter is set to MAKEINCLUDE if make dependendcies are to be constructed by the software; otherwise it is set to # so that no make dependency rules are included (and used).

MAKEDSOINCLUDE

The keyword used to specify inclusion of a file containing rules for building DSO's. This parameter is set to MAKEINCLUDE if DSO's are to be built; otherwise it is set to # so that nothing is included.

MAKEINCLUDE, MAKELQUOTE, MAKERQUOTE

The syntax used to specify an include file for make; e.g. @MAKEINCLUDE@ @MAKELQUOTE@file@MAKERQUOTE@. These parameters are normally deduced by configure depending on the capabilities of the make program to use.

MANSCHEME

The scheme to use when preparing and installing manual pages. Schemes are constructed according to:

<organization>-<formatting>-<compression>[-<suffix>]

where: <organization> is either bsd for BSD-style section organization (e.g. file formats in section 5) or sysv for System V-style organization (e.g. file formats in section 4). <formatting> is either nroff to force installation of formatted materials (using nroff) or source to get the nroff source installed. <compression> is either the name of a program to compress the manual pages (gipz, compress, pack) or cat for uncompressed data. <suffix> is either the file suffix to convert installed pages to (e.g. 0.gz for gzip-compressed pages under BSD) or strip to force the normal ".4f" suffix to be converted to ".4" (or ".5" if using the BSD organization). If no -<suffix> is specified then filenames are not converted when they are installed.

PAGESIZE

The default page size that client applications will use for submitted facsimile. Page sizes are specified by name and checked against the pagesizes database installed in the DIR_LIBDATA directory. See also pagesizes(4F).

PATH_DPSRIP

The absolute pathname of the Display PostScript-based imager program.

PATH_GETTY

The absolute pathname of suitable getty program to exec to handle an inbound data call. Note that this parameter must be set correctly before the software is built; there is no mechanism for doing this through a runtime configuration file.

PATH_GSRIP

The absolute pathname of the Ghostscript-based imager program. Beware that this must be a version of the gs program that includes the tiffg3 device driver.

PATH_SENDMAIL

The absolute pathname of the sendmail program on the server machine; sendmail is used by HylaFAX to post mail messages for a variety of reasons.

PORTFUNCS

A list of non-standard functions that should be emulated. Normally this list is constructed by configure based on checks it does. If this parameter is set, configure will append to the specified list.

PROTOTYPES

Options that should be passed to the C compiler to force it to check for function prototype mismatches. This parameter should not be needed because ANSI C compilers should do this automatically.

SETMAKE

If make does not automatically set $MAKE to the name of the make program to invoke for subdirectories, then configure will create an explicit definition. If this parameter is set, then it will be used instead.

SHDLIBC

A special library to use in place of the standard -lc implicitly provided by CC and/or CXX.

SIGHANDLERTYPES

The type signatures to use when checking for the correct type for a signal handler. If this parameter is set then configure will check these types before it checks a builtin list of well-known values.

SYSGID

The group ID to use for installing non-setgid programs; by default this is chosen according to the target system.

SYSUID

The group ID to use for installing non-setuid programs; by default bin is used.

How to setup a HylaFAX server and prepare it for use.
HylaFAX table of contents.