The automatic updater routine for gretl under win32

Allin Cottrell, January 2001

1. When gretl is started up, it sends a query to the gretl update
   server on ricardo (gretl_update.cgi), asking if there are updates
   available.  (This behavior can be turned off by the user under
   "File, Preferences, General".)  The query supplies time-stamp
   information, based initially on the time-stamp file installed with
   gretl, which enables the update server program to tell if any
   update files on the server are subsequent to the gretl installation
   on the client.

2. If there are updates available, the server responds with a list of
   files and their sizes.  On the client side, gretl informs the user
   and suggests exiting gretl and running the auxiliary program,
   gretl_updater.exe.  (On *nix, the user is notified of new files but
   that's all.  I'm presuming that such users would rather control the
   updating process themselves.)

Details so far: 

The function update_query() in gretl's webget.c is called from within
main() in gretl.c.  This function stats the file gretl.stamp (in the
main gretl directory) and sends its "st_mtime" to the server via the
function get_update_info() (also in webget.c).  The string passed to
the server is "opt=QUERY&date=<mtime of gretl.stamp>".

The server, the source for which consists of server.c and update.c,
parses the supplied parameter string.  In the case of a QUERY the
function tgz_list(), in update.c, is called.  This cycles through the
files on the server with extension ".tgz" (if any) and outputs their
names and sizes, if they are newer than the date supplied by the
client.  If there are no new files it outputs "No new files".

Back on the client side, the result of the query is stored in the char
buffer "getbuf", declared and allocated in update_query().  If there
are no new files the output is silently ignored, otherwise the
information is parsed (the new file sizes are added up to give a total
byte count) and passed to the user via a dialog box.  Once the
information is given to the user the buffer is freed.

3. The client updater program, gretl_updater.exe, offers three
   options, as follows:

      gretl_updater (automatically get any new files)
      gretl_updater -f foo.tgz (get foo.tgz, output to file)
      gretl_updater -l (list new files on server)

   When the program is called from the Windows menu the first form
   (with no option flag) is invoked.  Execution then proceeds in two
   stages: (1) The server is queried, as by gretl above, for a listing
   of new files; then (2) the client loops over the list of files
   supplied by the server, grabbing them from the server and unpacking
   them one by one.

Details here: 

The source for gretl_updater consists of update_client.c, webget.c (a
slightly modified version of the gretl source file of the same name),
and untgz.c (a simple .tgz extractor based on untgz.c from the zlib
distribution).

At the second stage, the client contacts gretl_update.cgi with the
parameter string "opt=GRAB_FILE&fname=<desired file>".  

The unpacking of the archive file is done using the function untgz(),
in untgz.c.  The .tgz file is then removed.

4. Preparation of update files on the server:  These should just be
   standard gzipped tar files, with extension ".tgz".  They should
   reside in the same directory on the server as gretl_update.cgi
   since the tgz_list() function simply looks in ".".  They'll be
   unpacked in the main gretl directory, and any internal directory
   structure in the archive should reflect this fact. (check this)

   NOTE: Update files must contain a suitably dated gretl.stamp.
   The client's stamp file will then be overwritten when the update is
   unpacked (and the client will not be offered the same update more
   than once).

   Getting the dates right: An update file for win32 should be made
   available in the context of the release of a new version (the point
   being that a package containing only the modified files is likely
   to be much smaller than the complete distribution, plus the
   auto-updater should be more convenient for the user than having to
   visit the gretl website and download and install the new
   distribution).  The time stamp on the update file (.tgz) itself
   should then be slightly PRIOR to the gretl.stamp file distributed
   with the new (complete) packages, otherwise someone who downloads
   the new complete version will immediately get a message saying that
   an update is available.  This can be achieved using "touch -t
   <time> <update file>".  The gretl.stamp contained in the update
   file, on the other hand, should be equal to or subsequent to the
   stamp in the corresponding complete package (equal to is "correct",
   but slightly subsequent would be OK).

Updating the stamp under *nix is trickier, since ordinary users
generally won't have write permission on the stamp file.  This is not
done properly in gretl version 0.63 and lower; it's fixed (I think) in
version 0.64, as follows (in gretl's webget.c).  We check whether the
current user is the owner of the system-wide gretl.stamp and react
accordingly.

Owner: Use gretl.stamp as the time reference.  In case notification of
an update is given, write to gretl.stamp to update its mtime so that
notification is not given again.

Not owner: See if a per-user ~/gretl/.gretl.stamp exists.  If so, use
this as the time reference, otherwise use the system-wide gretl.stamp
as the reference.  If an update notification is given, write to the
per-user stamp file (creating it or updating it).