This note describes how to create a software installation package that can install on an altepg TiVo.

1. First, decide on a name for the package.  Look in /var/www/tivo-static/software/available_packages for inspiration and naming conventions.

2. Decide what type of package it is. Choose from:
   - upgrade    : an upgrade of a component of the TiVo software (or of a hack)
   - patch      : an (emergency) patch of the TiVo software (or of hack)
   - test       : a test version of a package
   - diagnostic : a diagnostic tool (not normally visible to end users)
   
3. Create installation zip file for your package (see below for how to do this), and name it {packagename}_install.gz

4. Put the zip file in /var/www/tivo-static/software/packages

5. Update /var/www/altepg.com/packageInfo/{packagetype}Packages.html to provide a description of the package. Use an HTML anchor with the name of the package
   to provide a hook for linking to the package (viz <a name="{packagename}">)

6. Add an entry to /var/www/tivo-static/software/available_packages to make the package visible on the www.altepg.com/am web site

   The entry consists of 5 tab delimited fields:
   1. {packagename} as above. NB for backwards compatibility, the name should be followed by a space.
   2. Description - description of the package
   3. Type - either Test, Patch, Upgrade or Diagnostic (this governs who can see it on the installation page)
   4. URL - name of a file that describes the package (relative to /var/www/altepg.com/packageInfo)
   5. Depends On - earliest version of altepg that this package will work with (for future use - currently this is ignored)

**** Creating the installation zip file ****

The installation zip file is a gzipped tar archive (create with tar cvfz). The root directory of this archive must contain a script named 'install.bash'.
The altepg installation framework will download this tar archive to the TiVo, unzip it and run install.bash.  Simplistically, that's all you need to know.
However, to make things easier, there is a "standard" altepg install.bash script. A copy of the latest version of this script is in /var/www/tivo-static/software/resources
(the config controlled original is on icon:~millsb/dev/tivo/devArea/build/installTivo.bash)
This standard script works from a configuration file named 'fileList.txt'. This file contains lines of the form:

{directive}TAB{data}
Where {directive} is a single letter, and {data} is either a file pathname (relative to root of tar file) or some other string.

The directive letters are as follows:
A - Add new file (data = pathname)
M - Modify file (data = pathname)
D - Delete file or directory (data = pathname)
E - Execute file (data = pathname)
H - Install hack (data = pathname)
P - Package identifier (data = package name)
R - Reboot required (data = restart message)
T - Target directory (data = dirname, relative to /var/hack; or absolute) - used by 'H' directive to install hacks in specific places
V - Minimum version to which this installation can be applied (future functionality - ignored currently)

So if you use the install.bash script, you just need to create a suitable fileList.txt identifying what you want to install, and include that along with
all the files you want to install, in the tar file.

There is a further simplification if what you're installing is already a pre-packaged TiVo hack.  Pre-packaged hacks are gzipped tar files that contain
a bunch of files for installing on tivo (with contents relative to a specific tivo directory).  For these you just need to include the tivo hack file,
install.bash and a fileList.txt file containing the following directives:

P - to identify the package
T - to nominate the directory into which the hack will go
H - to identify the hack file

Note that the 'T' directive MUST PRECEDE the 'H' directive in fileList.txt, as the installer processes the directives in sequence.

**** Using build tools on icon: ****

The icon: server contains some build tools for making installation packages. Here's how to use them.

1. cd to ~millsb/dev/tivo/devArea/build
2. choose a name for your package
3. create 'fileList_{packagename}.txt'
   - filenames in here are relative to the git repository in ~millsb/dev/tivo/devArea. 
     This means that a file that needs to go in the tivo root directory are named (eg) 'root/myfile.txt'
4. run:
   ./buildTivo.bash -p {packagename} {packagename}
   This will create ~millsb/dev/tivo/buildArea/tivo/{packagename}-{date}_install.gz
5. test this package out by installing as a 'test' package according to the steps above
6. (if OK), commit the changes to the git repository and give it a label (normally this should be the same as the packagename), and run:
   ./buildTivo.bash -p {packagename} -f .. {label}
   ** NOTE : THIS GIVES A NASTY ERROR, but it still works.  However instead of -f .. you should really be nominating a work area to do the build
      (this part of the build script doesn't seem to work properly/needs a rethink)
   This will create ~millsb/dev/tivo/buildArea/tivo/{label}_install.gz


Brian Mills 30/06/2013