Difference between revisions of "Handbook:Source Code Install"

Latest revision as of 14:59, 8 July 2009

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

Download and extract the HylaFAX source code distribution. 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-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 the Periodic Maintenance Section 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

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.

Name	Default	Description
Adobe Font Metrics	AFM=auto	This package contains Adobe Font Metric files that came from the public dvips distribution. AFM files are required by the textfmt(1) and faxmail(1) programs for converting ASCII text to PostScript. The AFM files should reflect the characteristics of the fonts that are used for imaging PostScript on the fax server. However if the PostScript RIP used to image text does not come with AFM files for its fonts, then this package can be substituted with only minimal degradation in the formatting of the imaged text. By default this package is configured for installation only if font metric files do not appear to be present on the build machine.
Display PostScript RIP	DPS=no	Whether or not to build and install a DPS-based PostScript imager for IRIX 4.x and 5.x systems from sources present in the HylaFAX build tree. This option is intended for people building binary distributions.
Dynamic Shared Object Support	DSO=auto	This package controls whether or not to configure the building of Dynamic Shared Objects (DSOs) 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 requires it. By default this package is configured only if the build system appears to suport DSOs in a way that fits into the normal build scheme. If DSO support is explicitly enabled and there is no support for using DSOs in the expected way then DSOs are not used. Beware that DSOs can only be used when the compiler and runtime system support the runtime instantiation of global C++ objects that have constructors; something that few systems support.
Getty Support	GETTY=auto	This 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 requirements of the target system.
Ghostscript RIP	GS=no	Whether or not to build and install a PostScript imager from Ghostscript sources present in the HylaFAX build tree. This option is intended for people building binary distributions.
Impressario RIP	IMP=no	Whether or not to build and install an Impressario 2.1 plug-in DSO from sources present in the HylaFAX build tree. This option is intended for people building binary distributions.
PostScript RIP	PS=auto	This package selects which RIP to use for imaging PostScript on the server. Possible values are: gs for Ghostscript, dps for the Display PostScript-based RIP provided for IRIX 4.x and 5.x systems, or imp for a plug-in DSO for Impressario 2.1 under IRIX. By default the DPS support is selected for IRIX systems; otherwise Ghostscript is used.
Regular Expression Support	REGEX=yes	This package controls whether or not to use the regular expression package included with the software. On systems where there is POSIX regular expression support in the standard system library use of this package may be disabled. Note that if this package is disabled the location of the include files and library containing the regular expression support must be specified; see the REGEXINC and LIBREGEX configuration parameters.
SGI RGB Image Converter Support	SGI2FAX=auto	This 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 build system appears to have support for the SGI Image library that sgi2fax uses to read RGB images. If this package is not installed then SGI RGB images must be converted to a form suitable for transmission using some other mechanism.
System V Init Support	SYSVINIT=auto	This 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.
UTMP/WTMP Support	UTMP=auto	This package controls whether or not system accounting work should be done using the normal utmp files and data structures or the extended utmpx facilities. By default the appropriate support is chosen based on whether or not the build system has the <utmpx.h> file (auto). Explicit support can also be chosen by setting this parameter to utmp (normal accounting) or utmpx (extended accounting).
zlib Support	ZLIB=yes	This package controls whether or not to use the zlib compression package included with the software. On systems where the zlib distribution has already been installed this package may be disabled. Note however that if this package is disabled the location of the include files and library for the zlib distribution must be specified; see the ZLIBINC and LIBZ configuration parameters.

Configuring the included HTML Documentation

NOTE: This documentation remained in the distribution up to the 4.3 branch, but hasn't been maintained for years. Despite what is said below, the www.hylafax.org website should be considered the authoritative HTML documentation now, and the HTML docs included with the software should be taking with large grains of salt.

HylaFAX comes with extensive documentation written in HTML, the language used to author many documents found on the World Wide Web (WWW). These materials can be viewed at the main WWW site http://www.hylafax.org/, they can be installed on a local WWW server, or they can be viewed directly from the source area. Viewing the documentation through a WWW server is preferred because the materials include links to reference manual pages that are accessed through CGI scripts, and these links will not be available when the documentation is accessed directly from the source distribution.

To configure the build environment so that it will install the HTML documentation, you need to request the HTML package when running the configure script. This is done by specifying -with-HTML as a command-line option to configure or by setting HTML=yes in a config.site or config.local file. When the HTML package is setup for installation there are four other parameters that should be defined according to local conventions:

Parameter	Default	Description
DIR_HTML	/var/httpd/hylafax	The directory where HTML materials should be installed.
DIR_CGI	/var/httpd/cgi-bin	The directory where CGI scripts should be installed.
CGIPATH	/cgi-bin	The pathname to use in HTML documents to reference scripts installed in DIR_CGI.
HTMLPATH	/hylafax	The pathname to use in HTML documents to reference materials installed in DIR_HTML.

(NB: the default values are suitable for the Apache HTTP server) . Finally, to complete the installation the HTML documents must be edited to fix pathnames that are found in the HTML files. All instances of @HTMLPATH@ and @CGIPATH@ must be replaced with the values of DIR_HTML and DIR_CGI, respectively. (This was done automatically in previous versions of HylaFAX but must now be done manually.) A shell script to do this is:

#! /bin/sh
ROOT=${1-/hylafax}
CGI=${2-/cgi-bin}
PATTERN="@[a-zA-Z][a-zA-Z]*@"
patch()
{
   chmod +w $1
   ed - $1<<EOF
g;@HTMLPATH@;s;;$ROOT;g
g;@CGIPATH@;s;;$CGI;g
w
q
EOF
   chmod -w $1
}

FILES=`grep -l "$PATTERN" *.html */*.html`
test "$FILES" && {
   for i in $FILES
   do
      echo $i; patch $i;
   done
}

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 command does not support the expected options. If you have problems consult the script.
If local support is to be provided, it may be worthwhile to alter the electronic mail addresses embedded in several of the CGI scripts.

A Sample Configuration Session

Showing a commented configuration session presents some serious formatting challenges, but probably should be added here some day. Perhaps you would like to add it? -DPN

Configuration Parameters

This section gives a brief description of the less obvious configuration parameters. Consult the distributed config.site for a complete list of parameters. The list here is sorted alphabetically. NOTE: 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.

Parameter	Description
`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_ABORTBUG`	On some systems the logic used by the server 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_BADEXECVEPROTO`	On some systems the prototype function declaration for the `execve` system call is wrong (it does not list certain parameters as `const`). Setting this parameter to `yes` causes the software to work around this problem.
`CONFIG_BADEXECVPROTO`	On some systems the prototype function declaration for the `execv` system call is wrong (it does not list certain parameters as `const`). Setting this parameter to `yes` causes the software to work around this problem.
`CONFIG_BADGETOPTPROTO`	On some systems the prototype function declaration for `getopt` is wrong (it does not list certain parameters as `const`. Setting this parameter to `yes` causes the software to work around this problem.
`CONFIG_BADSELECTPROTO`	On some systems the prototype function declaration for `select` passes sets of file descriptors as `int` instead of `fd_set`. Setting this parameter to `yes` causes the software to assume the `int*` form is required.
`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_NOREOPEN`	Whether or not to reopen the tty device that a modem is connected to after raising and lowering the `DTR` signal (to reset the modem). This is done because on some systems lowering `DTR` causes the device to be placed in an unusable state. It may be desirable to disable this action however; for example when a modem is connected to an Ethernet-based terminal server. Setting this parameter to `yes` causes the modem to be reopened after reset. By default this parameter is set according to the target system.
`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.
`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_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_SOCKARGLENTYPE`	On some systems the type of call-by-reference parameters that specify the size of variable-length buffers in socket-related calls is wrong (the type is something other than `int`). This parameter can be set to the C type that should be used for length parameters; e.g. ```unsigned long`; otherwise* `int` is assumed. Setting this parameter incorrectly should result in compilation errors.
`CONFIG_TIOCMBISBYREF`	Whether to pass the argument to the TIOCMBIS ioctl by value or by reference. On most systems the value is passed by reference; consult `termio(7)` for your system if you are unsure how your system works. Setting this parameter to `yes` is the default and generates code for passing the argument by reference.
`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.
`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_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_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/hylafax.
`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.
`LIBREGEX`	The command line parameter(s) to use to link the library containing regular expression support. This parameter is set by default to reference the software included in the distribution.
`LIBTIFF`	The command line parameter(s) to use to link against the TIFF library. This parameter is set by default to the default installation location used by the TIFF software distribution.
`LIBZ`	The command line parameter(s) to use to link against the zlib library. This parameter is set by default to reference the software included in the distribution.
`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 <A HREF="man/hylafax-config.html">hylafax-config(4F)</A> 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 (gzip, 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 <A HREF="man/pagesizes.html">pagesizes(4F)</A>.
`PATH_DPSRIP`	The absolute pathname of the Display PostScript-based imager program.
`PATH_EGETTY`	The absolute pathname of suitable getty program to exec to deduce the type of an inbound 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. This program is not part of HylaFAX; it is provided as a ``hook for developers to integrate voice capabilities.
`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_IMPRIP`	The absolute pathname of the Impressario 2.1-based imager program available for IRIX 6.2 (and beyond) systems.
`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.
`PATH_VGETTY`	The absolute pathname of suitable getty program to exec to handle an inbound voice 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. This program is not part of HylaFAX; it is provided as a ``hook for developers to integrate voice capabilities.
`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.
`REGEXINC`	The pathname of the directory containing include files for the regular expression package. By default this parameter is set to reference the package included with this distribution.
`SCRIPT_SH`	The absolute pathname of the shell program to use when building HylaFAX and to use to execute certain command scripts. This shell must support the Bourne shell command syntax. Beware that many versions of bash have bugs in them that make them unsuitable for use.
`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.
`TIFFBIN`	The pathname of the directory where the TIFF software distribution tools have been installed.
`TIFFINC`	The pathname of the directory where the TIFF software include files have been installed.
`ZLIBINC`	The pathname of the directory containing include files for the zlib distribution. By default this parameter is set to reference the package included with this distribution.

Troubleshooting Build Problems

Most compilation problems are because the configure script did not properly setup the software for building. If you have problems compiling the software on a supported system check the output from configure and the contents of the port.h file generated by configure to make sure it makes sense. Another byproduct of the configuration procedure is the config.log file that is found at the top of the build tree. This file contains information about the tests done by the configure script; it should also be studied to check for problems.

The most common problem encountered during building, which is frequently not recognized until later when a program does not work correctly, is when the system include files are lacking proper ANSI C function prototypes. In particular beware of compilation warnings about passing an object as an argument to a function, this usually means that a function was defined without a function prototype and then a C++ object was passed through the interface as an argument. For example, if the C library strchr function is declared as

extern char* strchr();

instead of the expected

extern char* strchr(const char*, int);

then the C++ compiler will not know to do the implicit cast of the first parameter to a const char*; almost certainly causing problems. Unfortunately many older systems do not have system include files that include ANSI C function prototype declarations; if this is true of your system then you are unlikely to get HylaFAX to build correctly.

System-specific Guidance

This section contains some build-related issues that are dependent on the operating system installed on the build machine. The information included here is by no means exhaustive; it reflects feedback from users accumulated over multiple HylaFAX versions and/or operating system releases. Please feel free to add to this section, or update it according to your own experiences.

Mac OS X Guidance

1) Use HylaFAX 4.1.2 or newer.
2) Create a user and group "uucp" with a home directory of /var/spool/uucp/.
3) Create a user "bin".
4) Create a user "fax" which belongs to the "uucp" group.
5) Use chpass to create the /etc/passwd listing for "uucp". i.e.:

chpass -a "uucp:*:10:66::0:0:uucp:/var/spool/uucp:"
where "10" and "66" are the appropriate user and group numeric values.

6) execute ranlib /usr/local/lib/libtiff.a
7) Build and install the source as normally instructed for other systems. If using a HylaFAX version prior to 4.2.0, make sure to untar the source onto a UFS (not HFS) disk.
8) After running faxaddmodem you may want to check file ownerships in /var/spool/hylafax/ and /var/spool/hylafax/etc/ if you guessed at the uucp user and group numeric values.
9) Create the required DSP directory for DEVFS mounting:

mkdir ~fax/dev

10) Do this:

mkdir /Library/StartupItems/HylaFAX
chown root.admin /Library/StartupItems/HylaFAX
chmod 775 /Library/StartupItems/HylaFAX

11) Make the file /Library/StartupItems/HylaFAX/HylaFAX with root:admin ownership and access mode 775 containing this text:

#!/bin/sh
. /etc/rc.common
ConsoleMessage "Starting HylaFAX server processes"
/sbin/mount -t devfs ~fax/dev /var/spool/hylafax/dev
/usr/local/sbin/hylafax start
ConsoleMessage "HylaFAX server processes started"

12) Make the file /Library/StartupItems/HylaFAX/StartupParameters.plist with root:admin ownership and access mode 775 containing this text:

{
 Description     = "HylaFAX daemon";
 Provides        = ("HylaFAX Server");
 OrderPreference = "Last";
 Messages =
 {
   start = "Starting HylaFAX Server";
   stop  = "Stopping HylaFAX Server";
 };
}

13) Edit /etc/ttys and add a line like:

tty.usbmodem091 "/usr/local/sbin/faxgetty"      unknown on secure
where "tty.usbmodem091" is the device name of your modem.

14) Reboot the computer or run the above HylaFAX shell script and restart init.

Many thanks to Guy Loucks and the Apple Developer Connection for their exhaustive work on this.

Note that some unresolved communication (timeout) problems have been experienced when using the AppleSCCModem (tty.modem) driver with xonxoff flow control. More success has been had using rtscts flow control or USB modems.

AIX Guidance

To use the IBM xlC C++ compiler you must have a version that supports the -+ option so that filenames with a .c++ extension are processed properly by the compiler.

Under at least AIX 4.2 some socket-related function declarations have been changed to use non-standard types. To workaround compilation problems the CONFIG_SOCKARGLENTYPE configuration parameter should be specified to reflect the appropriate type of the call-by-reference length parameter passed to accept, getpeername, and getsockname.

BSD/OS Guidance

Beware that the standard BSD/OS distributions place many files and applications in non-standard locations. This can cause confusion when HylaFAX is installed because the old applications distributed with BSD/OS may be accidentally run and do the wrong thing. Under BSD/OS 2.1 the following config.local file may be used to configure a build tree that installs over top of the standard BSD/OS distribution of HylaFAX.

DIR_BIN="/usr/contrib/bin"                # client apps
DIR_MAN="/usr/contrib/man"                # manual pages
DIR_AFM="/usr/contrib/lib/hylafax/afm"    # AFM files
DIR_LIBDATA="/usr/contrib/lib/hylafax"    # client data
DIR_LIBEXEC="/usr/contrib/lib/hylafax"    # libs&hidden apps
DIR_SBIN="/usr/contrib/bin"               # system apps
DIR_SPOOL="/var/spool/hylafax"            # spooling area
PATH_GSRIP="/usr/contrib/bin/gs"          # Ghostscript RIP

Note that you will also need to specify the location of the TIFF software because the version distributed with BSD/OS 2.1 is too old to use.

DELL SVR4 Guidance

On some releases <sys/mkdev.h> includes static functions with non-ANSI C definitions; these must be manually corrected before building the software. (The GNU gcc installation procedure attempts to correct this file but does not.)

The ttymon program is executable only by root; this may cause the configure script to not select it as the getty program that is started up for inbound data calls. To work around this problem override the default selection through the interactive prompts or by creating a config.local file that explicitly sets the PATH_GETTY configuration parameter.

FreeBSD Guidance

FreeBSD 2.0 does not include the file <osfcn.h>. If the software does not compile without this file a copy can be obtained from the GNU libg++ distribution: ftp://prep.ai.mit.edu/pub/gnu/libg++*.tar.gz, libg++-2.6.2/libg++/src/osfcn.h.

HP-UX Guidance

Under HP-UX 9.05 the standard make incorrectly processes VPATH; either use gmake or configure the software to be built directly in the source tree.

Some versions of HP-UX define the select system call with parameters that are of type int*; if so set CONFIG_BADSELECTPROTO=yes to work around the problem.

Some versions of HP-UX have the include file <utmpx.h> but do not support the extended accounting facilities defined by this file. This confuses the configure script; to work around the problem set UTMP=utmp when configuring the build environment.

Linux Guidance

Under various versions of Linux; when linking with the -g option; if the linker complains about needing libc.so.4, then it is necessary to setup symbolic links in /usr/lib so that: libg.a -> libc.a and libg.sa -> libc.sa.

Some recent versions of Linux come setup so that when C++ programs are compiled the standard C functions strchr and strrchr (and possibly others) have multiple definitions based on the types of their arguments. This overloading causes compilation problems because HylaFAX assumes the ANSI C definition which specifies a single definition for these functions. To workaround this problem either correct the include file <string.h> or re-install gcc and/or libg++ (the standard distributions do not cause problems).

Under Caldera OpenLinux 1.3 (and probably previous 1.x versions) the configure script fails when testing for TIFF support. To work around the problem use --with-LIBTIFF="-ltiff -ljpeg -lz".

IRIX Guidance

Older versions of the SGI C++ compiler do not correctly handle nested types. If configure complains that the compiler is unsuitable for use or if the software does not build correctly verify that you have an up to date version of the compiler.

When building the software to use DSOs it may be necessary to set LIBMALLOC=no to avoid conflicts between the memory allocation routines in the standard C library and those in -lmalloc.

Under IRIX 5.3 /bin/sh has a bug that causes the faxsetup script to run correctly but terminate with an error. It may be preferrable to set SCRIPT_SH=/bin/ksh though it is not necessary.

SCO Guidance

These notes pertain to SCO 3.2 v4.2; they may also be relevant to other versions.

With gcc 2.7.2.1 one gcc include file needs to be patched to include missing function prototypes:

*** /usr/local/lib/gcc-lib/i486-unknown-sco3.2v4.2/2.7.2.1/include/sys/signal.h	Thu Sep  5 18:26:45 1996
--- /usr/local/lib/gcc-lib/i486-unknown-sco3.2v4.2/2.7.2.1/include/sys/signal.h.old	Thu Sep  5 18:28:56 1996
***************
*** 214,221 ****
  #else
  	int kill(short, int);
  #endif
! 	int (*ssignal(int, int(*)(int)))(int);
! 	void (*sigset(int, SIG_TYP))(int);
  
  	int sigpause(int);	/* These 4 are SVID functions as well */
  	int sighold(int);
--- 214,221 ----
  #else
  	int kill(short, int);
  #endif
! 	int (*ssignal(int, int(*)(int)))();
! 	void (*sigset(int, SIG_TYP))();
  
  	int sigpause(int);	/* These 4 are SVID functions as well */
  	int sighold(int);

When running configure disable the use of ranlib by specifying -with-RANLIB=true on the command line or in a config.local file.

Some of SCO's system include files have incorrect function prototypes that cause compilation to fail; other include files are not properly setup to deal with their being included multiple times. The following diffs may be applied to the problematic system include files or one may create patched copies of these files in a private sys directory under the top level of the HylaFAX build tree.

*** /usr/include/sys/stat.h	Wed Mar  9 00:00:00 1994
--- sys/stat.h	Thu Sep  5 18:45:25 1996
***************
*** 147,153 ****
  extern int  lstat(const char *, struct stat *);
  extern int  fstat(int, struct stat *);
  extern int  mkdir(const char *, mode_t);
! extern int  mkfifo(char *, mode_t);
  extern mode_t  umask(mode_t);
  #ifdef __cplusplus
  };
--- 147,153 ----
  extern int  lstat(const char *, struct stat *);
  extern int  fstat(int, struct stat *);
  extern int  mkdir(const char *, mode_t);
! extern int  mkfifo(const char *, mode_t);
  extern mode_t  umask(mode_t);
  #ifdef __cplusplus
  };
*** /usr/include/sys/time.h	Fri Mar 27 05:05:45 1992
--- sys/time.h	Thu Sep  5 19:42:08 1996
***************
*** 32,41 ****
--- 32,44 ----
  #ifndef __sys_time_h__
  #define __sys_time_h__
  
+ #ifndef _STRUCT_TIMEVAL_
+ #define _STRUCT_TIMEVAL_
  struct timeval {
  	long            tv_sec;	/* seconds */
  	long            tv_usec;/* and microseconds */
  };
+ #endif /* _STRUCT_TIMEVAL_ */
  
  struct timezone {
  	int             tz_minuteswest;	/* minutes west of Greenwich */
*** /usr/include/sys/select.h	Wed Mar  9 00:00:00 1994
--- sys/select.h	Thu Sep  5 19:41:13 1996
***************
*** 38,47 ****
--- 38,50 ----
  /*
   * Structure used to specify timeout in select(2) system call.
   */
+ #ifndef _STRUCT_TIMEVAL_
+ #define _STRUCT_TIMEVAL_
  struct timeval {
  	long	tv_sec;		/* seconds */
  	long	tv_usec;	/* and microseconds */
  };
+ #endif /* _STRUCT_TIMEVAL_ */
  
  #ifndef _INKERNEL
  #ifdef _NO_PROTOTYPE

These notes pertain to SCO 3.2 v5.0

One of SCO's system include files has incorrect function prototypes that cause compilation to fail; The following diff may be applied to the problematic system include file or one may create a patched copy of the file in a private sys directory under the top level of the HylaFAX build tree.

*** /usr/include/sys/syslog.h Thu Dec 26 04:42:27 1996
--- sys/syslog.h Fri Dec 27 17:05:11 1996
***************
*** 198,204 ****
  void closelog __P((void));
  void openlog __P((const char *, int, int));
  int setlogmask __P((int));
! int vsyslog __P((int, char *, va_list ));
  __END_DECLS
  
  #endif /* !INKERNEL */
--- 198,204 ----
  void closelog __P((void));
  void openlog __P((const char *, int, int));
  int setlogmask __P((int));
! int vsyslog __P((int, const char *, va_list ));
  __END_DECLS
  
  #endif /* !INKERNEL */

Solaris Guidance

Under (at least) Solaris 2.3 the standard make does VPATH processing incorrectly for files passed to the mkdepend script (the last file in the list is not converted to a pathname relative to the source directory); this causes lots of msgs that can be safely ignored.

Some versions of Solaris include an old version of the TIFF library with the OpenWindows software. This can cause problems when running the configure script unless the LD_LIBRARY_PATH environment variable is explicitly set to reference the location of the newer TIFF library DSO or the path is explicitly set with a -R flag in the LIBTIFF configuration parameter.

Ultrix Guidance

Extensive work is required to get the software built and working. The following comments apply to at least Ultrix 4.4. These notes relate to building and running HylaFAX Version 3.0 with gcc-2.6.3 and libg++-2.6.2.

Two header files cause problems: termios.h and sys/socket.h.

termios.h defines tcsetattr, tcgetattr, etc in terms of macros that map to ioctl's; this causes problems with the configure script. As the real functions are present in libc, working around this problem is just a matter of bringing the include file up to date. (When compiling with GNU gcc the file to patch is normally /usr/local/lib/gcc-lib/mips-dec-ultrix4.4/2.6.3/include/sys):

123,125d122
< #if !defined(_POSIX_SOURCE)
< #define tcsetattr(fildes,action,termios_p) 	\
< 	ioctl(fildes,action,termios_p)
127,133d123
< #define tcgetattr(fildes,termios_p) 	\
< 	ioctl(fildes,TCGETP,termios_p)
< #else
< extern	int tcsetattr();
< extern	int tcgetattr();
< #endif

< 
147,152d136
< #if !defined(_POSIX_SOURCE) 
< #define tcdrain(fildes)		\
< 	ioctl(fildes,TCSBRK,-1)
< #else
< extern	int tcdrain();
< #endif
161,166d144
< #if !defined(_POSIX_SOURCE)
< #define tcflush(fildes,queue)	\
< 	ioctl(fildes,TCFLSH,queue)
< #else
< extern	int tcflush();
< #endif
176,181d153
< #if !defined(_POSIX_SOURCE)
< #define tcflow(fildes,action)	\
< 	ioctl(fildes,TCXONC,action)
< #else 

< extern 	int tcflow();
< #endif
183,189d154
< /*
<  * Get input and output baud rates.
<  */
< #if !defined(_POSIX_SOURCE) && !defined(_XOPEN_SOURCE)
< #define OBAUD (CBAUD << 16)
< #define cfgetospeed(termios_p)		\
< 	(((termios_p)->c_cflag & OBAUD) >> 16)
191,198c156,160
< #define cfgetispeed(termios_p)		\
< 	((termios_p)->c_cflag & CBAUD)

< #else
< extern	speed_t cfgetospeed();
< extern	speed_t cfgetispeed();
< extern 	int 	cfsetispeed();
< extern	int 	cfsetospeed();
< #endif
---
> extern int tcsetattr(int, int, const struct termios*);
> extern int tcgetattr(int, struct termios*);
> extern int tcdrain(int);
> extern int tcflush(int, int);
> extern int tcflow(int, int);
199a162
> extern  int tcsendbreak _PARAMS((int, int));

/usr/include/sys/socket.h needs to be protected against multiple inclusion:

2a3,4
> #ifndef _SOCKET_
> #define       _SOCKET_
237a240
> #endif /* _SOCKET_ */

Many of the tools provided with Ultrix are outdated, functionally crippled, or just buggy. Affected here are sh, make, expr, and sed.

configure must be run by ksh; e.g.

<TT>
% ksh configure
</TT>

There is no hope for using /bin/sh, it does not support shell functions. The good news is that the current /bin/ksh handles all the scripts as well, so it is not necessary to install bash; simply use

<TT>
SCRIPT_SH=/bin/ksh
</TT>

A recent version of GNU make must be used (I have used version 3.67).

A replacement expr program is found in the GNU Shell Utilities package; it is needed in place of the default system version. Likewise for sed; I have used GNU Version 2.05.

The syslogd and printf programs are not available on Ultrix. On a host running only client software (no local modem) these may be ignored. On a server machine these are required.

The standard syslog support can not handle the HylaFAX server processes (or any other modern software for that matter). It should be replaced with a newer syslogd. Several alternatives are available, the stuff I have used can be found at <A HREF=ftp://gatekeeper.dec.com:/pub/DEC/jtkohl-syslog-complete.tar.Z>ftp://gatekeeper.dec.com:/pub/DEC/jtkohl-syslog-complete.tar.Z</A>.

(A note here: on my system I have done a complete replacement, including putting new syslog functions in my libc.a. This means that I have not tried to build with the port/syslog.c support included with HylaFAX; though it should be equivalent).

UnixWare Guidance

One system include file needs to be patched to correct function prototypes:

*** /usr/include/netdb.h	Mon Dec 11 05:25:35 1995
--- netdb.h	Wed Oct 30 14:05:35 1996
***************
*** 90,105 ****
  
  #ifdef __STDC__
  
! extern struct hostent	*gethostbyname(char *);
  extern struct hostent	*gethostbyaddr(char *, int, int);
  extern struct hostent	*gethostent(void);
  extern struct netent	*getnetbyname(char *);
  extern struct netent	*getnetbyaddr(long, int);
  extern struct netent	*getnetent(void);
! extern struct servent	*getservbyname(char *, char *);
  extern struct servent	*getservbyport(int, char *);
  extern struct servent	*getservent(void);
! extern struct protoent	*getprotobyname(char *);
  extern struct protoent	*getprotobynumber(int);
  extern struct protoent	*getprotoent(void);
  extern int		endhostent(void);
--- 90,105 ----
  
  #ifdef __STDC__
  
! extern struct hostent	*gethostbyname(const char *);
  extern struct hostent	*gethostbyaddr(char *, int, int);
  extern struct hostent	*gethostent(void);
  extern struct netent	*getnetbyname(char *);
  extern struct netent	*getnetbyaddr(long, int);
  extern struct netent	*getnetent(void);
! extern struct servent	*getservbyname(const char *, const char *);
  extern struct servent	*getservbyport(int, char *);
  extern struct servent	*getservent(void);
! extern struct protoent	*getprotobyname(const char *);
  extern struct protoent	*getprotobynumber(int);
  extern struct protoent	*getprotoent(void);
  extern int		endhostent(void);

On some versions the configuration parameter CONFIG_SOCKARGLENTYPE needs to be set to size_t to force the argument type for call-by-reference parameters to the socket-related system calls; this should automatically be done by configure.

@@ Line 43: / Line 43: @@
          --with-PATH_VGETTY=/sbin/vgetty \
          --with-PATH_GETTY=/sbin/mgetty \
-        --with-HTML=no \
          --with-PAGESIZE=A4 \
          --with-PATH_DPSRIP=/var/spool/hylafax/bin/ps2fax \
@@ Line 83: / Line 82: @@
   /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.
+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 the [[Handbook:Basic Server Configuration:Periodic Maintenance|Periodic Maintenance Section]] for those instructions.
 ==The Gory Details==
@@ Line 166: / Line 165: @@
   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.
@@ Line 209: / Line 206: @@
 | IMP=no
 | Whether or not to build and install an Impressario 2.1 plug-in DSO from sources present in the HylaFAX build tree. This option is intended for people building binary distributions.
-|- valign="top"
-| ''HTML Documentation''
-| HTML=no
-| This package contains this HTML documentation about HylaFAX. By default this package is not configured for installation. 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.hylafax.org/. This option is intended for people building binary distributions.
 |- valign="top"
 | ''PostScript RIP''
@@ Line 240: / Line 233: @@
 ===Configuring the included HTML Documentation===
-''NOTE: This documentation remains in the distribution, but hasn't been maintained for years. Despite what is said below, the www.hylafax.org website should be considered the authoritative HTML documentation now, and the HTML docs included with the software should be taking with large grains of salt.''
+''NOTE: This documentation remained in the distribution up to the 4.3 branch, but hasn't been maintained for years. Despite what is said below, the www.hylafax.org website should be considered the authoritative HTML documentation now, and the HTML docs included with the software should be taking with large grains of salt.''
 HylaFAX comes with extensive documentation written in HTML, the language used to author many documents found on the World Wide Web (WWW). These materials can be viewed at the main WWW site http://www.hylafax.org/, they can be installed on a local WWW server, or they can be viewed directly from the source area. Viewing the documentation through a WWW server is preferred because the materials include links to reference manual pages that are accessed through CGI scripts, and these links will not be available when the documentation is accessed directly from the source distribution.
-To configure the build environment so that it will install the HTML documentation, you need to request the ``HTML package'' when running the configure script. This is done by specifying -with-HTML as a command-line option to '''configure''' or by setting HTML=yes in a '''config.site''' or '''config.local''' file. When the HTML package is setup for installation there are four other parameters that should be defined according to local conventions:
+To configure the build environment so that it will install the HTML documentation, you need to request the ''HTML package'' when running the configure script. This is done by specifying -with-HTML as a command-line option to '''configure''' or by setting HTML=yes in a '''config.site''' or '''config.local''' file. When the HTML package is setup for installation there are four other parameters that should be defined according to local conventions:
@@ Line 302: / Line 295: @@
 * 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 command does not support the expected options. If you have problems consult the script.
 * If local support is to be provided, it may be worthwhile to alter the electronic mail addresses embedded in several of the CGI scripts.
 ===A Sample Configuration Session===
@@ Line 528: / Line 521: @@
 The directory where client applications should be installed; by
 default this is <B>/usr/local/bin</B>.
-</TR>
-<TR>
-<TD VALIGN=top><TT>DIR_CGI</TT></TD>
-<TD>
-The directory where CGI scripts used by the HTML-based
-HylaFAX documentation should be installed; by default this is
-<B>/var/httpd/cgi-bin</B> (usually appropriate for the
-NCSA HTTP server).
-</TR>
-<TR>
-<TD VALIGN=top><TT>DIR_HTML</TT></TD>
-<TD>
-The directory where HTML-based
-HylaFAX documentation should be installed; by default this is
-<B>/var/httpd/htdocs/hylafax</B> (usually appropriate for the
-NCSA HTTP server).
 </TR>
@@ Line 1,005: / Line 979: @@
 By default this parameter is set to reference the package included
 with this distribution.
+</TD>
 </TR>
 </TABLE>
@@ Line 1,025: / Line 999: @@
 This section contains some build-related issues that are dependent on the operating system installed on the build machine. The information included here is by no means exhaustive; it reflects feedback from users accumulated over multiple HylaFAX versions and/or operating system releases. Please feel free to add to this section, or update it according to your own experiences.
+===Mac OS X Guidance===
+) Use HylaFAX 4.1.2 or newer.<br />
+) Create a user and group "uucp" with a home directory of /var/spool/uucp/.<br />
+) Create a user "bin".<br />
+) Create a user "fax" which belongs to the "uucp" group.<br />
+) Use chpass to create the /etc/passwd listing for "uucp". i.e.:
+ chpass -a "uucp:*:10:66::0:0:uucp:/var/spool/uucp:"
+ where "10" and "66" are the appropriate user and group numeric values.
+) execute ranlib /usr/local/lib/libtiff.a <br />
+) Build and install the source as normally instructed for other systems. If using a HylaFAX version prior to 4.2.0, make sure to untar the source onto a UFS (not HFS) disk.<br />
+) After running faxaddmodem you may want to check file ownerships in /var/spool/hylafax/ and /var/spool/hylafax/etc/ if you guessed at the uucp user and group numeric values.<br />
+) Create the required DSP directory for DEVFS mounting:
+ mkdir ~fax/dev
+) Do this:
+ mkdir /Library/StartupItems/HylaFAX
+ chown root.admin /Library/StartupItems/HylaFAX
+ chmod 775 /Library/StartupItems/HylaFAX
+) Make the file /Library/StartupItems/HylaFAX/HylaFAX with root:admin ownership and access mode 775 containing this text:
+ #!/bin/sh
+ . /etc/rc.common
+ ConsoleMessage "Starting HylaFAX server processes"
+ /sbin/mount -t devfs ~fax/dev /var/spool/hylafax/dev
+ /usr/local/sbin/hylafax start
+ ConsoleMessage "HylaFAX server processes started"
+) Make the file /Library/StartupItems/HylaFAX/StartupParameters.plist with root:admin ownership and access mode 775 containing this text:
+ {
+  Description     = "HylaFAX daemon";
+  Provides        = ("HylaFAX Server");
+  OrderPreference = "Last";
+  Messages =
+  {
+    start = "Starting HylaFAX Server";
+    stop  = "Stopping HylaFAX Server";
+  };
+ }
+) Edit /etc/ttys and add a line like:
+ tty.usbmodem091 "/usr/local/sbin/faxgetty"      unknown on secure
+ where "tty.usbmodem091" is the device name of your modem.
+) Reboot the computer or run the above HylaFAX shell script and restart init.
+Many thanks to Guy Loucks and the Apple Developer Connection for their exhaustive work on this.
+Note that some unresolved communication (timeout) problems have been experienced when using the AppleSCCModem (tty.modem) driver with xonxoff flow control. More success has been had using rtscts flow control or USB modems.
 ===AIX Guidance===

Personal tools