#
# @(#)INSTALL	5.14 95/02/07
#
# xmcd - Motif(tm) CD Audio Player
# cda  - Command-line CD Audio Player
#
# by Ti Kan
#

Please read through the following notes before attempting to
compile and install xmcd and cda.  If you encounter a problem,
read the FAQ file.

You must have X11R4/Motif 1.1 or later to build xmcd.  Xmcd has been
successfully built under X11R4 with Motif 1.1, and X11R5 or X11R6
with Motif 1.2.

If you are running Motif 1.1, I recommend version 1.1.4 or later.
Also, you must have an ANSI C compatible compilation environment.

Xmcd can be built using the native X libraries that are supplied with
your OS release.  If you have XFree86 installed, you can also build
xmcd using the libraries from the XFree86 distribution.  Make sure
you use the right set of X include files to match!  Motif is not a
part of the XFree86 package, so you will need to get it separately.
Motif is available from various third party vendors for those OS
platforms that do not come standard with the libraries and headers.
If you cannot find a commercial Motif product for your platform
you can also build the Motif library from the OSF sources (if you
have the source license).

The cda utility requires named pipe (FIFO) support in your OS
platform.  If your system does not support named pipes, you
must edit the top level Imakefile or Makefile.std and remove
the cda.d directory from the SUBDIRS definition.

If you do not have X11 or Motif, you can still build cda.  Edit
the top level Makefile.std and remove xmcd.d from the SUBDIRS
definition, and follow the instructions below for systems that
do not have imake.


Platform-specific Notes
-----------------------
All platforms:
    If you use the GNU C compiler (gcc), do not use the -ansi
    option.  The -ansi option changes the compiler's
    interpretation of structure bit-fields and breaks both
    xmcd and cda.

Apple A/UX 3.x on Macintosh:
    Use gcc to compile the xmcd distribution.  You may have to add
    an explicit -DmacII to CFLAGS if your C pre-processor does not
    already define this.

    You are advised to make certain that xmkmf uses the X11R5 config
    files (e.g., /usr/local/X11R5/lib/config).  The default config
    files in Apple's distribution of X11R4 (/usr/lib/X11/config) will
    require extensive hand-editing of the resulting Makefiles (to use
    gcc instead of cc, shared-libs are not available, etc.).

Data General DG/UX on DG AViiON:
    You should use the instructions below for systems without imake
    to build this distribution, since DG/UX does not provide imake.
    A makedgux.inc is provided, which you should rename as make.inc.

DEC OSF/1 on Alpha AXP:
    See the README file for minimum operating system version
    requirements.  Xmcd requires the C pre-processor flags -D__alpha
    and -D__osf__ to be set.  This is normally pre-defined, but if
    your environment does not, you will have to add them explicitly.

DEC Ultrix on MIPS-based DECstations:
    See the README file for minimum operating system version
    requirements.  Xmcd requires the C pre-processor flag -D__ultrix
    to be set. This is normally pre-defined, but if your environment
    does not, you will have to add them explicitly.  Also, check
    the top level Makefile that's generated by imake.  There should
    be a SHELL=/bin/sh5 line.  If there are any other SHELL= lines
    they should be removed.

FreeBSD on x86:
    See the README file for minimum operating system version
    requirements.  Xmcd requires the C pre-processor flag -D__FreeBSD__
    to be set.  This is done by default with the FreeBSD development
    package.  If your system does not #define __FreeBSD__ for you, then
    you will have to add -D__FreeBSD__ explicitly.

HP-UX on PA-RISC:
    You may have to add an explicit -D__hpux to CFLAGS if your C
    pre-processor does not already define this.  If the HP cc compiler
    is used, you must enable ANSI C mode (using the -Aa or -Ae options,
    depending on your HP-UX release).  You may also have to define
    -D_HPUX_SOURCE to successfully compile xmcd.  See your cc(1) online
    manual entry for details.

IBM AIX 3.2.x and 4.x on RS/6000 Power/PowerPC:
    You may have to add an explicit -D_AIX to CFLAGS if your C
    pre-processor does not already define this.  Also, you must ensure
    that the _BSD flag is _not_ defined.

Linux on x86:
    Xmcd requires the C pre-processor flag -Dlinux to be set.  This is
    done by default with the XFree86 distribution that is included
    with most Linux releases.  If your system does not #define linux
    for you, then you will have to add -Dlinux explicitly.

SCO Open Desktop/SCO UNIX on x86:
    Xmcd requires the C pre-processor flag -Dsco (lower-case) to be
    set.  This is done by default on systems running the ODT
    Development System.  If you are using XFree86, you must modify the
    appropriate "OsDefines" line in your
    /usr/X386/lib/X11/config/x386.cf file to include -Dsco.  Also, if
    your imake configuration isn't fixed, you may need to explicitly
    add -lintl and -lPW to your xmcd.d/Makefile in order to resolve
    the regcmp(), regex() and alloca() routines.

Silicon Graphics Irix on SGI workstations:
    Xmcd requires the C pre-processor flag -Dsgi to be set.  This is
    normally pre-defined, but if your environment does not, you will
    have to add them explicitly.

Stratus FTX SVR4 3.x on Stratus PA-RISC:
    Xmcd requires the C pre-processor defines -D_FTX, -D__hppa and
    -DSVR4.  These should be defined by default.  Note that this
    release of xmcd/cda only supports the HP PA-RISC based Stratus
    fault-tolerant servers.  Earlier Intel i860 and Motorola 68k 
    based Stratus systems are not supported.

SunOS 4.1.x/Solaris 1.x on sparc:
    Xmcd requires the C pre-processor define -Dsun, which should be
    defined by default.  You must use the GNU C compiler (gcc) instead
    of the cc compiler.  This is because cc under SunOS 4.1.x is not
    ANSI compliant.

SunOS 5.x/Solaris 2.x on sparc/x86:
    Xmcd requires the C pre-processor defines -DSVR4 and -Dsun.
    These should be defined by default.  Xmcd also requires -Di386
    on Intel x86 platforms.  Also, you may need to add -lgen to
    the xmcd.d/Makefile to resolve the regcmp() and regex() routines.

    Be sure that /usr/ccs/bin is before /usr/ucb in your PATH
    environment variable, to get the appropriate cc compiler.
    This ensures that the proper SVR4 header files are used to compile
    the distribution.

    On Solaris 2.2 or later, you may wish to add -DSOL2_RSENSE to
    the libdi.d/Makefile enable support for the auto request-sense
    feature.

UNIX SVR4.x on x86:
    Xmcd requires the C pre-processor flag -DSVR4 and -Di386
    to be set.  This is normally pre-defined, but if your environment
    does not, you will have to add them explicitly.  On SVR4.2MP
    systems you may need to add -lXimp and -lgen to xmcd.d/Makefile
    in order to resolve some external symbols Motif requires.


Xmcd Demo Mode
--------------

You must compile on one of the supported UNIX OS flavors (See the
README file for a list of the supported OS environments) to get a
real functional xmcd.  You can compile on other platforms, but you
will end up with a "demo" version of xmcd.

You can also force the build of the demo version by specifying
-DDEMO_ONLY when compiling in the libdi.d directory.  See the
comments in libdi.d/Imakefile.

It should be possible to build the demo-only xmcd on any platform
that supports compiling a Motif application.  Minor porting work
may be required on systems that aren't POSIX-compliant.

The "demo" version does not actually control or respond to a real
CD-ROM device.  Instead, a built-in CD-ROM simulater is used,
which allows you to play with the look-and-feel of xmcd/cda and try
the behavior of all the controls and functions.

If you are running the demo version of xmcd/cda, the following message
will be displayed on stderr when you start the program:

    CD-ROM simulator version x.xx (pid=xxxxx) starting...


Build instructions
------------------

If your system has imake (most supported systems do), use these
steps to build xmcd and cda:

    1. Take a look at the Imakefiles in various directories, read
       the comments, and make changes as appropriate.  Pay special
       attention to the comments in xmcd.d/Imakefile pertaining to
       the LOCAL_LIBRARIES=XmClientLibs line.  You may need to change
       it in order to successfully compile xmcd.
    2. Change to the xmcd top level source directory.
    3. Type "xmkmf" (or "imake -DUseInstalled -I/usr/lib/X11/config")
    4. Type "make Makefiles"
    5. Type "make depend" (this step is required only if you intend
       to modify the source code or header files).
    6. Type "make"

If your system does not have imake, use these steps to build xmcd:

    1. Change to the xmcd top level source directory.
    2. Type "cp Makefile.std Makefile"
    3. Type "cp common.d/Makefile.std common.d/Makefile"
    4. Type "cp libdi.d/Makefile.std libdi.d/Makefile"
    5. Type "cp xmcd.d/Makefile.std xmcd.d/Makefile"
    6. Type "cp cda.d/Makefile.std cda.d/Makefile"
    7. Type "cp wm2xmcd.d/Makefile.std wm2xmcd.d/Makefile"
    8. Edit make.inc.  You will most certainly need to make some
       changes in this file to make things compile on your OS
       platform.
    9. Type "make"


Install instructions
--------------------

1. Log in as the super-user and change to the xmcd source directory.
   Super-user status is used to set the permissions of all files
   and ensures that you have write privilege to all target directories.
   If any target directory is an NFS remote resource, however, the
   super-user status may be insufficient and you will need to manually
   install some files and set their permissions.
2. You may want to strip(1) the symbol table of the cda.d/cda,
   xmcd.d/xmcd and wm2xmcd.d/wm2xmcd binaries to reduce their size.
   On some platforms, you can also use mcs(1) with the -d option to
   remove the binary comment section.
3. Type "make install".  Answer all questions to configure xmcd and cda.
   This step is REQUIRED.  If you do not configure the software using
   "make install" it will not run correctly.  Install errors, if any,
   are recorded in the /tmp/xmcd.err file.
4. Edit LIBDIR/xmcd/config/common.cfg and make sure that the "device:"
   path matches the default raw CD-ROM device on your system (LIBDIR
   varies depending on the OS platform environment, but is typically
   /usr/lib/X11).
5. Edit LIBDIR/app-defaults/XMcd and make sure that the "XMcd*libdir:"
   path is correct.  Xmcd will not run properly if this is wrong.
6. You may need to change the XMcd*cddbMailCmd resource in the
   LIBDIR/app-defaults/XMcd file to match the requirements of your
   local mailer.  For example, A/UX sites should use mush(1) instead
   of mail(1).  You must use a mailer that can accept a command-line
   argument to specify the mail Subject.  Otherwise, the CDDB mail
   will be rejected by the archive server.
7. The install.sh script only places the man page raw files in the
   designated directories.  Depending on your OS platform, you may
   need to hand format the files using nroff(1) with the -man option.


To make a binary release
------------------------

1. Follow the Build Instructions as above.
2. Make sure the binary you build has the proper mix of static vs.
   shared library components for your target system. In particular,
   if your target system does not have Motif installed, then you
   will want to statically link libXm.a.  The same consideration
   should be given to libXt, libXext, libX11, libnsl, libsocket,
   libc, and others where applicable.  The more libraries you link
   statically, the less platform-dependent the binary is, but the
   larger it becomes.  In some cases, even a fully static xmcd binary
   will still have problem running if the target system has different
   kernel-to-library interfaces than the compiling system.
2. Run the "misc.d/makerel.sh" script.  The script generates a file
   "xmcdbin.tar.gz", which is a "gzip"ed  tar format file containing
   all files necessary for a xmcd binary distribution.  It also
   creates a "xmcdbin.uue" file, which is a uuencoded version of
   the xmcdbin.tar.gz file suitable for transmission via electronic
   mail.  This script assumes the existence of the GNU zip (gzip)
   utility.
3. Consult the OSF/Motif licensing terms pertaining to your version
   of Motif before distributing binaries containing Motif code to
   others.


To make a source release
------------------------

1. Run the "misc.d/makesrc.sh" script.  The script generates a file
   "xmcdsrc.tar.gz", which is a "gzip"ed tar format file containing
   all xmcd source files.  It also creates a "xmcdsrc.uue" file,
   which is a uuencoded version of the xmcdsrc.tar.gz file suitable
   for transmission via electronic mail.  This script assumes the
   existence of the GNU zip (gzip) utility.

   Alternatively, you can use the "misc.d/makeshar.sh" script.  This
   generates a multi-part shar archive of the source code instead.
   Note that makeshar.sh assumes the existence of the "shar" program
   as provided in the "cshar" package from Rich Salz.  Other shar
   implementations may support different command line parameters
   which is incompatible with cshar.  The makeshar.sh must be modified
   to accommodate those.


Additional Notes:
-----------------

The "configure.sh" shell script supplied with this distribution is
not intended to be run directly in the libdi.d source directory.
You should use "make install" to install the package, which causes
configure.sh to be executed with the proper environment.  If you
must reconfigure xmcd/cda, run the copy of "configure.sh" as
installed in LIBDIR/xmcd/config (where LIBDIR is typically
/usr/lib/X11).

