RISC DISC 2/RISC_DISC_2.iso/pd_share/program/tools/setdate/ReadMe

Text File | 1994-11-01 | 5.4 KB | 140 lines

         ____              _____
        (____   ____ _____  |   \  ___  _____  ____
             \ |___    |    |   | /___\   |   |___
        _____/ |____   |   _|___/ |   |   |   |____

             ©   1 9 9 4   S t r a y l i g h t
___________________________________________________________

                       About SetDate

Whenever I change an application or a module, I invariably
forget to change the date in the version string.  It gets
rather annoying after a while, and it causes great
confusion too.

Near the beginning of my C programming days, I wrote a
program which intercepted calls to the compiler and added a
`-setdate' option, which created a header file containing
the date in a particular format.  This was then included in
necessary source files, and everything was wonderful.
Almost.  There were problems.  Firstly, I had to fake the
datestamp on the header file I created to prevent
recompilations.  Secondly, and more importantly, if I
wanted to change the date, I still had to remember to force
a recompile of the source files which included it (usually
the one which displayed the progInfo window).  This was
clearly unsatisfatory.  Thirdly, it occasionally got the
directory wrong, and I was left with files called
`timenow.h' all over my hard disk.

My reasoning behind trying to extend cc's syntax was fairly
simple -- it meant that Make would create the header at the
same time as compiling.  It is an unfortunate side-effect
of using Make that you can only define one command per
dependency, which is one of the reasons I stopped using it.

Having written the parts of the DLLManager concerned with
messing with AOF files, I decided that a much nicer was of
doing this was to create an object file containing the
date, which could then be linked with the other object
files in the project.  I also decided that this should be a
standalone program, unlike my previous effort, so that it
could also be used from assembler.  I had stopped using
Make in favour of raw amu and homegrown makefiles by this
point.  My new approach has several advantages. It doesn't
cause dependency problems.  If inserted in the makefile
appropriately, it recreates its AOF file whenever the image
is relinked, so the date is always correct.  Thirdly, it
didn't get the directory wrong.
___________________________________________________________

                       Using SetDate

SetDate's command line syntax is fairly simple.  The first
argument is the name of the output file it is to produce.
This is followed by 0 or more definitions of symbols to
create.  These have the format

  <identifier> [ `=' <date format> ]

Each one will create a string containing the date, and
export a symbol with the given name containing its address.
If you don't supply a date format, a default one is
provided, which will output dates like `9 September 1993'.
The formats are an extended version of those used by the
SWI OS_ConvertDateAndTime.

Note that if you want the date format to contain spaces, as
it normally will do, you should enclose it in double
quotes.

As an example, to create a file `o.version' containing a
single symbol `version' containing the version string for
the progInfo window, you might use the command

  setDate o.version version="1.05 (%zdy %mo %ce%yr)"

Typing the command

    setdate -help

will display a quick reminder of this syntax, together with
a list of the date formatting commands available.

--- Use with C programs

You should note that the symbols created by SetDate should
be declared as

  extern char <name>[];

--- Use in modules

When you write modules in assembler, you can use SetDate to
set up the module's help string.  To help you do this, the
excape sequence `\t' will insert the correct number of tabs
to move the cursor to column 16 as required to make the
`*Help Modules' display line up neatly.  Note that the date
format required is `%dy %m3 %ce%yr'.

You should then link the objects into the library using
linker options `-base 0 -bin' -- this will ensure that the
help string offset is correct in the linked module. This
has an unfortunate side effect -- you can't use the
linker's relocation feature.  However, this isn't really
too much of a hardship -- external symbols become offsets
from the module base rather than absolute addresses.

As an example, you might construct a module help string
with the command

  setdate o.version help="MyModule\t3.25 (%dy %m3 %ce%yr)"
___________________________________________________________

                     Technical details

SetDate was written in C, largely because I already had an
AOF generation library in C, so it seemed silly rewriting
it in assembler.  Seeing as it's only 5K anyway, I don't
think that anyone's overly bothered about that.

The source, weighing in at almost 300 lines, was compiled
using Norcroft RISC OS ARM C (that's the Acorn compiler),
linked using Dave Daniels' drlink with a small AOF library
and Straylight's `astubs' Shared C Library stubs, which are
about 3-4K smaller than Acorn's.

Straylight do not release source code.  Don't bother asking
for it.
___________________________________________________________

                  Copying and distribution

You may give copies of setDate and this documentation to
anyone you want.  You may not sell copies of either, except
as part of a PD compilation disk, and even then not for
more than 2 pounds sterling.  You may not alter either the
documentation or the application in any way.
___________________________________________________________