
This is the README for the new instalation and packaging infrastructure
for the Darwin Streaming Server Project - CVS Version - 2001-05-15
and updated at Chris LeCroy's request for CVS Version - 2001-11-19
and then CVS Version - 2001-11-30

File Manifest
=============

replaced  : Install
new       : qtaccess-template
new       : relayconfig.xml-template
new       : streamingserver.xml-template
removed   : streamingserver.xml
removed   : streamingserver.xml-POSIX
new       : WebAdmin/streamingadminserver.conf-template
removed   : WebAdmin/streamingadminserver.conf
removed   : WebAdmin/streamingadminserver_Darwin.conf
removed   : WebAdmin/streamingadminserver_NT.conf
???????   : WebAdmin/streamingadminserver_autostart.conf
removed   : WebAdmin/perlpath.pl
removed   : DSS_MakeProxyRoot
removed   : DSS_MakeRoot
removed   : buildproxytarballx
removed   : buildtarball
generate  : WinNTSupport/qtusers
generate  : WinNTSupport/qtgroups
generate  : WinNTSupport/qtaccess
generate  : WinNTSupport/streamingserver.xml
generate  : WinNTSupport/streamingproxy.cfg
generate  : WinNTSupport/relayconfig.xml

As can be seen by the file manifest, this is not a small change. Some
quite important files have been completely removed from the code base.

But fear not, there is method in the madness :-)

I have move the outline of the problems/solutions/benfits to the end of
the document.

Notes
=====

	Usage:	Install install|package|generateWindowsConfig server|proxy

There are four principal modes of operation :

	1. Installation From Source Tree (Source Install)
		usage: Install install server|proxy

	2. Generation of Package Archive from the Source Tree (Packaging)
		usage: Install package server|proxy

	3. Installation from Package Archive (Binary Installation)
		usage: Install      -- this mode is autodetected and
				       which distribution (server|proxy)
				       is also autodetected, to ease user
				       installation issues.	

	4. Generation of Windows configurations file from templates.
		usage: Install generateWindowsConfig server|proxy

There are only two defined products :

	1. Darwin Streaming Server (server)
	2. Darwin Streaming Proxy  (proxy)

Cavets
======
	The code is about 98% complete - but is it is not complete !!!

	This modification was completely developed on Solaris, and no
	testing has been preformed on the Darwin/MacOS X platform.
	The #TODO#'s in the code should be read and the code updated,
	before running the script on a Darwin/MacOS X platform. 

Getting Started
===============

	1. get the latest cvs version of the code.
	2. Replace or install any files I have provided.
	3. Build the system !!! Both Server and Proxy
	4. Run the script to install the proxy from the source tree,
	   without actually doing the installation. (no need for any
	   privs here - we are not modifying anything)

		DO=: ./Install install proxy

	   if that worked try the following to see what commands would
	   be executed:

		DO=echo ./Install install proxy

	5. If you are not happy with installation locations, look at the
	   DarwinConfiguration, UnixConfiguration, WindowsConfiguration
	   functions in the code. Also look at the function
	   DetermineConfiguration as its currently does not know how to
	   enable the DarwinConfiguration function. This is related to
	   the #TODO# in the DeterminePlatform function

	6. At this point it is time to print the Install script
	   and look over the #TODO# comments. Also find the Main Program
	   comment and read from there to see what is happening, don't
	   worry too much about all the functions at the moment.

	   Most installation functions take three basic arguments,
	   location in source tree, location in packaging area and
	   location after installation. Variables prefixed with PA_
	   are referring to the Packaging Area location.
	
           Also best to read the next section to see what I'm trying
	   to fix.

Assistance
==========

After all the effort to rework the packaging and installation infrastructure
I like to see it make it to the CVS code base, so if you have any questions
or need any help or would like something fixed - PLEASE - email me at 

apple-publicsource-submissions@illumino.org (Peter Bray, Sydney, Australia).



Problems/Solutions/Benefits
===========================

Here is an outline of the problems as I saw them in the Darwin Streaming
Server codebase (noting that I have only looked at installation issues
to date)

PROBLEM:  Inconsistent configuration files - the presence of a configuration
          file for each platform (Darwin, Unix, Windows) meant that changes
	  had been applied to some files and not others.
SOLUTION: Have a template based configuration files and use a substition
	  mechanism to replace the variable components (usually file names)
	  Because Windows is a non standard platform (ie not UN*X based)
	  a facility has been provided to generate the Windows versions
	  of the configuration files (into ./WinNTSupport) so that they 
	  can be checked back in, but still have the benefit of a single
	  master template file for each configuration file.
BENEFITS: Because the variable sections have been factored out of the 
	  templates, location independence(*) of executables, configuration,
	  data and logs was easy to achieve. *Location independence being
	  the ability to install the software where the administrator see
	  fit and ease the process of configuring the software to handle
	  this. 
ACTIONS:  A careful review of the templates is required, I have personally
	  spent quite sometime diff'ing (via emacs' ediff) all versions
	  of each configuration file, and I believe the templates are
	  accurate, but I'm not the best person to judge this.
NOTE:     The template based files are substituted at install time,
	  not packaging time, to allow for maximum flexibility. This
	  works for both source nd binary installation methods. Also,
	  This is done for UN*X platforms only, hence the generation option
	  for Windows

PROBLEM:  Lack of location independance, hard coding of paths, root
	  priviledges required to install the software.
SOLUTION: Make all the paths configurable for each platform (Darwin,
	  Unix, Windows) near the top of the Install script, and only
	  refer to the variable for the rest of the installtion or
	  packaging process. This allows for simple changes at installation
	  time, to customise the final location of the software. Once the
	  location is customisable, the need to be root to install the
	  software is removed. The generation of configuration from templates
	  also means that after installation, time is not wasted simply
	  editing paths to reflect the installation location.
ACTIONS:  As noted in the code a final set of installation paths for
	  the Darwin/MacOS X installation needs to be finialsed. See the
	  TODO comments in the code.

PROBLEM:  Overwriting existing configuration files durring installation
SOLUTION: Have the installation install sample configuration files, and
	  only install the file into the correct location if no file
	  alreadly exists in that location. A warning is provided that
	  you may wish to merge the existing configuration file with the
	  new version's supplied sample, durring software installation.
BENEFITS: Users will not have to restore from backup configuration files
	  destoryed durring installation of a new release.
TODO:     Could POSSIBLY add a force installation option, to force
	  overwriting of existing configuration files

PROBLEM:  The installation and packaging process was spread over many files,
	  all with hardcoded installation locations and very little if any
	  error checking or comments. Multiple edits required to keep the
	  installation system in sync. Overuse of block copying of code
	  fragments. General Understanding and Maintenance of the
	  installation infrastructure was tedious and somewhat difficult IMHO.
SOLUTION: Go completely overboard and spend nearly a week writing, testing
	  and debugging a new installation and packaging infrastructure.
	  :-) At almost 1200 lines long the new Install script takes over
	  the role of all the previous packaging and installation scripts.
	  About 2/3 of the script is helper functions which means when we
	  actually get to the installation or packaging, all refernces to
	  the source, packaging and final installation localation of a 
	  file are all kept together making maintenance less of an issue.
BENEFITS: Long Term maintainability and understandability of the 
	  packaging and installation infrastructure. Hardcoding of all
	  but the source location is avoided, functions have meaningful names
	  adding to the readibility of the code, the functions determine
	  the current mode (more on this soon) and act on the appropriate
	  file is the appropriate way, checking that they exist before
	  acting and reporting any problems. Debugging and Output
	  verboseness are also configurable.


