README


			Build/Release Procedures
			========================
			  (updated 1/8/96)

This memo describes steps taken during the build/release process of Ultra64 
software. It is intended to assist those "lucky" few who have the opportunity 
of being the release meister.


0. Log into sonya as prbuild

	rlogin sonya -l prbuild

1. Set important environment variables

   For HW2:
	prbuild-sonya: release

   For HW1:
	prbuild-sonya: release1

2. Go to top of build tree

	prbuild-sonya: cd $PR

3. Clean everything up if you are totally paranoid

	prbuild-sonya: make clobber (for total paranoid clean build)

   OR

	prbuild-sonya: make clean (for simple clean build)

4. Update the tree

	prbuild-sonya: updatePR.sh (located in ~/bin)

   This script simply updates the tree and directs output to $ROOT/update.log.

5. Increment the version in the $PR/build/spec file
   The current format for HW2 version is 2.0X where X is an upper case 
   letter (ie. B). Similarly, the format for HW1 version is 1.0X where X is an 
   upper case letter (ie. F).

6. Edit the release notes in $PR/man/relnotes to include all last-minute info

7. Install headers, libraries, tools, and propagate "make install" to all of
   the tree.

	prbuild-sonya: makePR.sh (located in ~/bin)

   This script simply runs the followings and directs output to $ROOT/make.log:

     a) make headers (install headers used by following passes)

     b) make exports (install libraries and tools used by following passes)

     c) make rawidb

        Build everything. You will notice 'make install' getting propagated to
        all of the source tree. Ordinarily this causes /etc/install to install
        the binary into its target directory under $ROOT. But the 'make rawidb'
        rule sets a couple of double-secret environment variables (RAWIDB and 
        SRC) that don't actually install the files but add a record to a file 
        named by $RAWIDB. This raw Inst Data Base file is used in the next 
        step below. Note that RAWIDB is set to IDB in $PR/build/Makefile.

8. If you have already built images and building a new one, you need to

	prbuild-sonya: touch $PR/build/idb

   to have the correct dependency condition for rebuilding the isms

   Merge the raw idb file with the checked in idb file ($PR/build/idb) to
   create a final idb used to create the images:

	prbuild-sonya: make ism

   If the checked in idb file matches the generated raw idb file, this
   phase should complete without errors.  Otherwise, you will get the following
   error:

   ERROR: XX line(s) missing, YY line(s) extra

   Missing lines are lines that appear in the checked in idb, but not in
   the generated idb.  These are usually due to targets that have been
   removed from a Makefile.  Look at $PR/build/missing to confirm this,
   and then execute the following command to remove it from the checked in
   idb file:

	prbuild-sonya: idbdelete $PR/build/idb $PR/build/missing

   Extra lines are lines that appear in the generated idb file, but are
   not in the checked in file.  They are usually due to targets that have
   been added to a Makefile.  Look at $PR/build/extra to confirm this.
   Extra files need a little hand massaging to get into the checked in
   idb.  First, slightly reformat the idb lines in the extra file and save
   them in an intermediate file extra.new:

	prbuild-sonya: idbextra $PR/build/extra > $PR/build/extra.new

   Now edit the "extra.new" file to 'tag' the idb line. The tags are (upper 
   case) identifiers that associate an idb line with a product subsystem.
   The product spec file, found in $PR/build/spec, contains the mapping
   from idb tag to product subsystem.  Look at this file for a list of
   all of the subsystems and what tags correspond to which subsystem.
   It is usually easy to find an existing idb line that has the correct tag 
   and just use it. Some of the tags are: BASE, DEMO, DIAG, MAN_DEMO, MAN_BASE,
   and MAN_DIAG.
   
   Then, you need to append the extra.new file to the checked in idb file:

	prbuild-sonya: cat $PR/build/extra.new >> $PR/build/idb

   Finally, you must sort the checked in idb file.  There is probably an
   emacs way to do this, but a good thing to do from within vi is this:

	:5,$!sort +4 -6 -u
	:wq

   Then repeat step 8 until it completes cleanly.

9. Finally, make the images.

	prbuild-sonya: make images

   If this step completes cleanly, you will then have familiar, inst-style
   images in $PR/images.


9.5 Test, test, test. Use the "virgin_indy" script to clean up some
    lab machines, then install the new release. Build the installed
    apps in /usr/src/PR and check them all.

    Install the release as an "update" to some machines, test that
    too.

    Test all the apps on some machines, some apps on all machines.

    Test hardware 1.0, if necessary.

10. Once the images are verified, create a directory in gozar:/PRarchive. 
    Follow the naming convention in PRarchive to name the new directory.
    (ie. use the current date as the directory name). 

	prbuild-sonya: rlogin gozar -l root
	gozar 1# cd /PRarchive
	gozar 2# mkdir [mmmddyy_hw[12]]

    Copy over the images from sonya to the new directory. 
    Also, you need to copy the GameShop and dmedia images from the previous
    release to the new release. Relink LATEST to point to this new directory.

11. Then, you need to make 3 tar tapes:
	a) Tar off all FrameMaker files in $PR/doc/dev directory
	b) Generate postscript files in the $PR/man directory 
	   (ie., make ps-list) and tar off the entire $PR/man directory.
	c) Tar off the newly archived images in gozar. This should include
		- "ultra" images
		- "GameShop" images
		- "dmedia_eoe" images

12. The final step is to copy over the census file from $ROOT/census to the 
    archived directory on gozar.