rplay INSTALL - Installation instructions.

This file contains a list of installation instructions for rplay.  Please read
this file very carefully and don't skip any steps unless you think you know
what you are doing.  If you get confused at any time during the installation
please read the documents in the `doc' directory.  

Feel free to send email to boyns@sdsu.edu if you have any problems.

* Execute `./configure' to create rplay configuration files for your system.
  If you want to install rplay in a directory tree other than /usr/local,
  use `./configure --prefix=/installation/path'.

  When the configuration script cannot determine your system type it will
  try to use a generic configuration.  Note that the system type is used
  to enable system specific audio routines.  The generic configuration
  assumes an 8000 Hz audio device that accepts ulaw encoded audio data.
  System specific audio routines are located in the rplayd/audio
  directory.  See the PORTING file for more information on porting rplay to
  another system.

* After configure has been executed you may want to edit `Makefile.config'
  to choose the correct C compiler, CC_OPTIONS, and LD_OPTIONS.  Note that
  configure will try to use the gcc compiler with the -O flag by default.
  HP users should uncomment all the lines specified.

* Edit `include/config.h' to change rplay configuration parameters.
  This is where you can change the location of rplay.conf,
  rplay.hosts, rplay.servers, rplay.cache, and rplay.log, if necessary.
  (These pathnames are automatically modified by configure's --prefix option)
  There's several other parameters that you may want to enable/disable/change.

* HP users need to edit `librplay/Makefile' to comment/uncomment a few lines.
  See the directions in `librplay/Makefile' for more information.
  -- I've got to add this to the configure script.

* This step is optional but recommended.  Execute `make depend' to create 
  dependencies in the Makefiles.   The `makedepend' program is used to
  create the dependencies (see `Makefile.config').

* Execute `make' to compile rplay.  Compiler flags can be changed by
  specifying CFLAGS on the make command line.  (i.e. `make CFLAGS="-O2 -g"')
  The C compiler can be changed in the same manner as CFLAGS by using the
  CC make parameter.

  If rplay does not compile successfully you might need to change either
  the `Makefile.config' or `include/config.h'.

* Create your rplay.servers, rplay.hosts, and rplay.conf files.  Samples of all
  of these files are located in the `samples' directory.  If you want any of these
  files to be installed automatically, copy them to the `site' directory.

  Note that the rplay.hosts file is only required if AUTH was defined in 
  include/config.h.  (AUTH is defined by default)

  I run a cron job that creates my rplay.conf every hour.  `find *.au' or 
  `find / -name *.au -print' can used to find all the sound files that are 
  available.  (This all depends on what type of find program you have.
  Try using locate if find doesn't work)

* When rplay successfully compiles, execute `make world'.  This will verify that
  rplay has been compiled successfully, install rplay, and then ask you if
  you would like to send me an email message.

* Can rplayd be installed to run as root?  Well, that entirely up to you.
  The BAD_DIRS option in `include/config.h' restricts the directories that can 
  be accessed by rplayd.  (By default BAD_DIRS includes /etc and /dev)
  I feel rplayd is secure enough to run as root, but that is NOT for me to
  decide.  Remember to read the NO WARRANTY section in the COPYING file.

* rplayd can be configured to run from inetd.  This is not required since
  rplayd can also run as a standalone daemon (see `rplayd --help').
  If you plan on using inetd to invoke rplayd, become root and add the 
  following to /etc/services:

        rplay 5555/udp

  *NOTE* This entry used to be `rplay 55555/udp'.

  (You do not have to add any RPTP entries to /etc/services)

  Then add this to inetd.conf (you may need to change the pathname):

        rplay dgram udp wait nobody /usr/local/bin/rplayd rplayd

  If you do not have a `nobody' user defined in your password file 
  (/etc/passwd), change nobody to a valid username.  Make sure that the 
  user specified in inetd.conf has write access to audio device.  Some
  systems change the owner of audio device to person who's logged in on 
  the console.  (See audio device permissions below)

  If you are running NIS (YP) you will need to update the services map.
  `cd /var/yp; make' will probably do the trick for SunOS 4.1.x users.
  The NIS update must be done on the NIS server.  You can execute `ypwhich'
  to locate your NIS server.

  Now you need to restart inetd.
        bash$ ps aux | grep inetd
        (result will be something like this)
        root       174  0.0  0.0   48    0 ?  IW   13:25   0:04 inetd
        bash$ kill -1 174

  Check /var/adm/messages or the console for any errors.

* If you do not plan on using inetd you need to start rplayd by hand whenever
  you want to use it.  Try `rplayd -n' or `rplayd -n -t0'.  Read the rplayd
  man page and try `rplayd --help' for more information.

  Another option would be to start rplayd from /etc/rc.local or any of the
  other system startup scripts.

* Check your systems audio device permissions.  SunOS 4.1.x can automatically
  set the permissions of /dev/audio using /etc/fbtab.  (`man 5 fbtab')
  Solaris 2.X uses /etc/logindevperm.   When these device permission files
  include the audio device, only the person logged in on the system console
  will have access to the audio device.  Of course, this does not apply
  if you're running rplayd as root.

* Now see if rplay works.  Start rplayd and execute `rplay soundname',
  where soundname is the name of a sound in the rplay.conf.  If
  soundname is played then obviously rplay is working.  However, if a
  sound is not played then I recommend you run rplayd in debug mode to
  see exactly what is wrong.

  (Note that you can also try to use `rplay /full/pathname/soundname')
  
  When using rplayd in debug mode you must remove the rplayd entry from the
  inetd.conf file, restart inetd, and kill any old rplayds that might be running.

  Try running `rplayd -n -d -t0 &' and then `rplay soundname'.
  You should see output like:

  rplayd: 127.0.0.1 play bogus
  rplayd: bogus.au: 8 bit, 8000 Hz, 1 channel

  If you still don't hear any sound, check the following things:

     * Is the volume of the audio device very low or zero?
       Use xrplay or audiotool to change the volume.

     * Is another program using the audio device?
       There are several programs around that hog the audio device.
       These programs include soundtool, audiotool, play, x_soundtool,
       any many others.  Note that rplay is audio device friendly and will
       close the audio device when it is not being used (see --audio-close).
     
     * Are you running another audio server like Aserver?  rplay does not
       work with Aserver and probably won't work with other servers.
       If you want to use rplay make sure other audio servers are not running.

     * If you see errors like `/dev/audio open: Device busy' then another
       program is using the audio device.  Read the audio device permissions
       section above.

  If you are still having problems send email to boyns@sdsu.edu and I will do
  my best to help you out.

* You are done installing rplay.  You now should browse through the contrib 
  directory to see what other rplay applications are available.

