%% /u/sy/beebe/tex/dosmacux/INSTALL, Thu Sep 25 12:35:47 1997
%% Edit by Nelson H. F. Beebe <beebe@plot79.math.utah.edu>

==================
QUICK INSTALLATION
==================

To compile, test, and install this package on any UNIX system, it
should be sufficient to execute the command

	./configure && make all check install

To force use of a specific C or C++ compiler, on most UNIX systems,
you can do

	env CC=compilername ./configure && make all check install

since the configure script will accept environment definitions of
CC and CFLAGS to override its defaults.

Some older UNIX systems lack the env command, in which case the
above example must be slightly modified:

	for bash, ksh, sh:
		CC=compilername ./configure && make all check install

	for csh, tcsh:
		setenv CC compilername
		./configure && make all check install
		
If you wish to rebuild the package for a new architecture or a new
compiler, you MUST first do

	make distclean

to restore the directory to the pristine state of a newly-unpacked
distribution.

During its development, the dosmacux package has been successfully
compiled, linked, and tested by its author under more than 40
different old-K&R and new Standard C, and C++, compilers on a dozen
flavors of UNIX, plus DEC TOPS-20, DEC VAX VMS, and IBM PC DOS
systems, and on Atari and Amiga systems by others.  Not all of these
systems are currently available, so it is possible that code evolution
has introduced glitches that will require minor customizations on some
non-UNIX systems.


=====================================
CHANGING THE INSTALLATION DIRECTORIES
=====================================

The "make install" step defaults to these GNU-standard, and strongly
recommended, locations for installed files:

	/usr/local/bin/dos2mac
	/usr/local/bin/dos2ux
	/usr/local/bin/mac2dos
	/usr/local/bin/mac2ux
	/usr/local/bin/ux2dos
	/usr/local/bin/ux2mac

	/usr/local/man/man1/dos2mac.1
	/usr/local/man/man1/dos2ux.1
	/usr/local/man/man1/mac2dos.1
	/usr/local/man/man1/mac2ux.1
	/usr/local/man/man1/ux2dos.1
	/usr/local/man/man1/ux2mac.1

You can change the "/usr/local" installation directory prefix at
configure time with, e.g.

	./configure --prefix=/some/other/path

or at install time with

	make install prefix=/some/other/path

Thus, an unprivileged user could build and install a private copy like
this

	./configure --prefix=$HOME/private && make all check install

Otherwise, if you run a haphazard site with bizarre locations for
these directories, then you'll have to copy files by hand.

Under NO circumstances should you install the software under /usr,
except /usr/local; otherwise, the next time that you upgrade your
operating system, your own installations will be lost!


===============
PROBLEM REPORTS
===============

Bug reports, comments, and kudos are welcome, and may be sent to the
program author; see the AUTHORS file for addresses.

Except for possible warnings about unused rcsid strings, there should
be NO warnings of any kind from any compiler.  Please report any that
you encounter, because it is likely that a suitable test can be added
to the configure script to eliminate the warning.

However, you can ignore any messages of the flavor

	warning: conflicting types for built-in function `xxxx'

that compilation with "gcc -traditional" produces. They arise because
of conflicts between vendor-supplied library functions declared in
system header files, and what gcc `thinks' they ought to be.  I cannot
do anything about those.

If the configure script fails to run properly, it may have created a
config.log file that can be used to help diagnose the problem; please
include it with the problem report.


================
PROBLEM RECOVERY
================

In rare cases, the config.h file created may be slightly wrong; the
simplest way to fix this is to add new or replacement definitions to
custom.h, which is always read AFTER config.h.  That way, you can
avoid editing a file that will be overwritten if configure is run
again.

The backup subdirectory contains copies of the automatically-created
Makefile, config.h, and configure files (from a Sun Solaris 2.5.1
system) that may be helpful if configure gets damaged, or fails to
create the Makefile and config.h files.

Sometimes errors are traceable to undefined symbols that were expected
to be defined in system header files. In such a case, examination of
the preprocessor output that was handed to the compiler can be
helpful, so the Makefile supports "make filename.i" to create a
preprocessed filename.i from filename.c.  Almost all UNIX compilers
support the -E option to request this (one exception is the NeXT,
where the preprocessor is integrated into the compiler).


===============
PROBLEM SYSTEMS
===============

On all of the systems listed below, several compiler and compiler
options choices lead to successful builds.  However, there are some
failures, which are recorded here.


---------------------
DECstation ULTRIX 4.3
---------------------

(1) "gcc -traditional" will not compile the code because of the use of
the unrecognized Standard C keyword "volatile" in system header files.


-------------------
DEC Alpha OSF/1 3.2
-------------------

"gcc -traditional" will not compile the code because of the use of the
unrecognized Standard C keyword "volatile" in system header files.


-------------------
IBM RS/6000 AIX 4.1
-------------------

"gcc -traditional" will not compile the code because of the use of the
unrecognized Standard C keyword "signed" in system header files.


-------------
NeXT Mach 3.3
-------------

Warnings may be issued for an unprototyped library function,
unlink(), because it is missing from system header files, or declared
only when certain preprocessor symbols are defined.

"gcc -traditional" will not compile the code because "struct stat" is
then not visible in system header files.

lcc 1.9 will not compile the code because of non-Standard C uses in
NeXT-provided header files.


------------
SGI IRIX 5.3
------------

(1) "gcc -traditional" will not compile the code, because of
signed type qualifiers in system header files, and conflicts
between declared library functions, and gcc's built-ins.

(2) lcc will not compile because <sys/stat.h> is not available.


------------
SGI IRIX 6.4
------------

(1) lcc will not compile because <sys/stat.h> is not available.



================================
INSTALLATION ON NON-UNIX SYSTEMS
================================

On non-UNIX systems, copy config.hin to config.h, and then edit that
file to define or undefine symbols as appropriate.  If a
UNIX-compatible make is not available, then a simple build should be
possible with something like this:

	cc -o dos2ux -I. dos2ux.c common.c

Any errors that show up should be readily fixable with further simple
edits to config.h.  Changes to the .c files should NEVER be required.


==================
PORTABILITY ISSUES
==================

Although vendor-provided, third-party, and freely-distributable C and
C++ implementations are available for all commercially significant
personal, workstation, and mainframe computer environments, any
reasonably large C program faces numerous hurdles for successful
installation on multiple systems.

Traditionally, implementation variations are handled by C preprocessor
conditionals.  Formerly, the conventional procedure was to test for
symbols known to be defined in a certain environment (e.g. __alpha for
a DEC Alpha), but that tends to result in multibranch and/or nested
conditionals as the code is ported to new systems.

Programmers contributing to the Free Software Foundation GNU Project
now practice a different approach: define preprocessor symbols that
indicate the availability of a specific feature (e.g., HAVE_STDLIB_H).
Although many code fragments may still remain under control of C
preprocessor statements, this approach tends to reduce the nesting to
just a single level.

Of course, preparation of a suitable set of definitions of these
preprocessor symbols may still be tedious (there are about 33
preprocessor symbols that must be set in the config.h file),
particularly since the values may depend not only on the operating
system and the compiler, but also on the particular compiler options
chosen.  Thanks to the GNU automake and autoconf programs, suitable
values for these symbols can now be determined by empirical experiment
at installation time, by the configure script which automatically
creates a config.h file and a Makefile, using the config.hin and
Makefile.in files as templates that are modified according to the
results of the experiments.

The dosmacux has been written for a high-degree of portability, with
minimal architectural assumptions.  In particular, it has run on
16-bit, 32-bit, 36-bit, and 64-bit computers, under many different
UNIX systems, and several non-UNIX ones, and has done so successfully
since the first version was written in February 1992.



==================
AUXILIARY SOFTWARE
==================

The generated Makefile references some additional commands which are
not required to install this package, but may nevertheless prove
useful to you.  Here is a list of them, with Internet locations where
you can find their distributions:

dw		doubled word finder utility
		ftp://ftp.math.utah.edu/pub/misc/dw.*

ispell		GNU spelling checker
		ftp://prep.ai.mit.edu/pub/gnu/ispell-x.y.z.tar.gz
		[x.y.z = 3.1.20 on 25 September 1997]

man2html	UNIX-manual-page-to-HTML converter
		ftp://ftp.math.utah.edu/pub/sgml/man2html-x.y.*
		[x.y = 1.05 on 25 September 1997]


================
SAMPLE BUILD LOG
================

Here is what the build looked like on one system at the author's site
(on a Sun UltraSPARC 2170 running Sun Solaris 2.5.1):

% env CC=c89 CXX=CC ./configure
creating cache ./config.cache
checking whether make sets ${MAKE}... yes
checking for gcc... c89
checking whether the C compiler (c89  ) works... yes
checking whether the C compiler (c89  ) is a cross-compiler... no
checking whether we are using GNU C... no
checking for c++... CC
checking whether the C++ compiler (CC  ) works... yes
checking whether the C++ compiler (CC  ) is a cross-compiler... no
checking whether we are using GNU C++... no
checking for a BSD compatible install... /usr/local/bin/install -c
checking whether ln -s works... yes
checking for gawk... gawk
checking for col... col -x -b
checking for cat... (cached) col -x -b
checking for groff... groff -Tascii
checking for nroff... (cached) groff -Tascii
checking for gtbl... gtbl
checking for zip... zip
checking for Standard C/C++ function declarations... yes
checking for void* pointer support... yes
checking how to run the C preprocessor... c89 -E
checking for ANSI C header files... yes
checking for Standard C/C++ prototype support... yes
checking for working const... yes
checking for size_t... yes
checking for dos.h... no
checking for errno.h... yes
checking for file.h... no
checking for io.h... no
checking for jsys.h... no
checking for mon_s.h... no
checking for stdarg.h... yes
checking for stdio.h... yes
checking for stdlib.h... yes
checking for string.h... yes
checking for sys/stat.h... yes
checking for sys/types.h... yes
checking for utime.h... yes
checking for unistd.h... yes
updating cache ./config.cache
creating ./config.status
creating Makefile
creating config.h


% make all
CONFIG_FILES= CONFIG_HEADERS=./config.h ./config.status
creating ./config.h
c89 -c -DHAVE_CONFIG_H -I. -I. -I.   -g  dos2mac.c
c89 -c -DHAVE_CONFIG_H -I. -I. -I.   -g common.c
c89 -g dos2mac.o common.o -o dos2mac
c89 -c -DHAVE_CONFIG_H -I. -I. -I.   -g  dos2ux.c
c89 -g dos2ux.o common.o -o dos2ux
c89 -c -DHAVE_CONFIG_H -I. -I. -I.   -g  mac2dos.c
c89 -g mac2dos.o common.o -o mac2dos
c89 -c -DHAVE_CONFIG_H -I. -I. -I.   -g  mac2ux.c
c89 -g mac2ux.o common.o -o mac2ux
c89 -c -DHAVE_CONFIG_H -I. -I. -I.   -g  ux2dos.c
c89 -g ux2dos.o common.o -o ux2dos
c89 -c -DHAVE_CONFIG_H -I. -I. -I.   -g  ux2mac.c
c89 -g ux2mac.o common.o -o ux2mac

% make check
There should be no differences in these tests
/tmp/dosmacux/test01.dos [OK]
/tmp/dosmacux/test01.dos [OK]
There should be no differences in these tests
/tmp/dosmacux/test02.dos [OK]
/tmp/dosmacux/test02.dos [OK]
There should be no differences in these tests
/tmp/dosmacux/test01.mac [OK]
/tmp/dosmacux/test01.mac [OK]
There should be no differences in these tests
/tmp/dosmacux/test01.ux [OK]
/tmp/dosmacux/test01.ux [OK]


========================
SUCCESSFUL INSTALLATIONS
========================

Immediately prior to release, this version of dosmacux has been built
successfully on these UNIX systems with the indicated compilers and
options, for example

	env CC='cxx -x cxx' ./configure && make all check

This testing covers 139 compiler and option combinations on 11
different UNIX systems, representing 56 distinct C and C++ compilers.

Where the GNU C and C++ compilers are mentioned, they correspond to
versions 2.7.2.2 or 2.7.2.3, the latest at the time of this release of
dosmacux.  lcc compiler releases are 3.6 and 4.0.  All other C and C++
compilers listed are vendor-provided.

DEC Alpha              OSF/1 3.2
	cc (/usr/ccs/bin/cc)
	cc -D_POSIX_SOURCE (/usr/ccs/bin/cc)
	c89 (/usr/ccs/bin/c89)
	c89 -D_POSIX_SOURCE (/usr/ccs/bin/c89)
	cxx -x cxx (/usr/ucb/cxx)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)
	lcc (/usr/local/bin/lcc)

DECstation 5000        ULTRIX 4.3
	cc (/usr/bin/cc)
	cc -D_POSIX_SOURCE (/usr/bin/cc)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)
	lcc (/usr/local/bin/lcc)

HP 375                 4.3BSD
	CC (/usr/local/bin/CC)
	cc (//bin/cc)
	cc -ansi (//bin/cc)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)

HP 9000/735            HP-UX 10.01
	CC (/opt/CC/bin/CC)
	cc (/opt/ansic/bin/cc)
	cc -ansi (/opt/ansic/bin/cc)
	cc -D_POSIX_SOURCE (/opt/ansic/bin/cc)
	cc -Xa (/opt/ansic/bin/cc)
	cc -Xs (/opt/ansic/bin/cc)
	c89 (/opt/ansic/bin/c89)
	c89 -ansi (/opt/ansic/bin/c89)
	c89 -D_POSIX_SOURCE (/opt/ansic/bin/c89)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -traditional (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)

IBM PowerPC            AIX 4.1
	cc (/usr/bin/cc)
	cc -ansi (/usr/bin/cc)
	cc -D_POSIX_SOURCE (/usr/bin/cc)
	c89 -D_POSIX_SOURCE (/usr/bin/c89)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)
	xlC -+ (/usr/bin/xlC)
	xlc (/usr/bin/xlc)

IBM PowerPC            AIX 4.2
	cc (/usr/bin/cc)
	cc -ansi (/usr/bin/cc)
	cc -D_POSIX_SOURCE (/usr/bin/cc)
	c89 -D_POSIX_SOURCE (/usr/bin/c89)
	xlC -+ (/usr/bin/xlC)
	xlc (/usr/bin/xlc)
	[gcc and g++ are not yet installed on this system]

NeXT Turbostation      Mach 3.3
	cc++ (/bin/cc++)
	cc++ -D_POSIX_SOURCE (/bin/cc++)
	cc (/bin/cc)
	cc -ansi (/bin/cc)
	cc -ansiposix (/bin/cc)
	cc -cckr (/bin/cc)
	cc -posix (/bin/cc)
	cc -D_POSIX_SOURCE (/bin/cc)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)

SGI Indigo/2           IRIX 5.3
	CC (/usr/bin/CC)
	NCC (/usr/bin/NCC)
	cc (/usr/bin/cc)
	cc -ansi (/usr/bin/cc)
	cc -ansiposix (/usr/bin/cc)
	cc -cckr (/usr/bin/cc)
	cc -D_POSIX_SOURCE (/usr/bin/cc)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)

SGI O2 R10000-SC       IRIX 6.3
	CC (/usr/bin/CC)
	NCC (/usr/bin/NCC)
	cc (/usr/bin/cc)
	cc -ansi (/usr/bin/cc)
	cc -ansiposix (/usr/bin/cc)
	cc -cckr (/usr/bin/cc)
	cc -D_POSIX_SOURCE (/usr/bin/cc)
	c89 (/usr/bin/c89)
	c89 -ansi (/usr/bin/c89)
	c89 -D_POSIX_SOURCE (/usr/bin/c89)

SGI Origin 200         IRIX 6.4
	CC (/usr/bin/CC)
	NCC (/usr/bin/NCC)
	cc (/usr/bin/cc)
	cc -ansi (/usr/bin/cc)
	cc -ansiposix (/usr/bin/cc)
	cc -cckr (/usr/bin/cc)
	cc -D_POSIX_SOURCE (/usr/bin/cc)
	c89 (/usr/bin/c89)
	c89 -ansi (/usr/bin/c89)
	c89 -D_POSIX_SOURCE (/usr/bin/c89)

Sun SPARC              Solaris 2.5
	CC (/opt/SUNWspro/bin/CC)
	cc (/opt/SUNWspro/bin/cc)
	cc -D_POSIX_SOURCE (/opt/SUNWspro/bin/cc)
	cc -Xa (/opt/SUNWspro/bin/cc)
	cc -Xc (/opt/SUNWspro/bin/cc)
	cc -Xs (/opt/SUNWspro/bin/cc)
	cc -Xt (/opt/SUNWspro/bin/cc)
	c89 (/opt/SUNWspro/bin/c89)
	c89 -D_POSIX_SOURCE (/opt/SUNWspro/bin/c89)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -traditional (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)
	lcc (/usr/local/bin/lcc)

Sun SPARC              SunOS 4.1.3
	acc (/usr/lang/acc)
	cc (/usr/lang/cc)
	cc -D_POSIX_SOURCE (/usr/lang/cc)
	cc -Xs (/usr/lang/cc)
	cc -Xt (/usr/lang/cc)
	gcc (/usr/local/bin/gcc)
	gcc -Wall (/usr/local/bin/gcc)
	gcc -D_POSIX_SOURCE (/usr/local/bin/gcc)
	gcc -ansi (/usr/local/bin/gcc)
	gcc -traditional (/usr/local/bin/gcc)
	gcc -pedantic (/usr/local/bin/gcc)
	g++ (/usr/local/bin/g++)
